A self-hosted UPI & COD payment gateway with zero per-transaction platform fees, universal JavaScript checkout integration, dynamic QR payments, WhatsApp OTP authentication, and automated payment verification.
JavaScript
openapi: 3.0.3
info:
title: YOUPI PG V2 — Public Developer Integration API
version: 2.0.0
description: |
Official public integration API and webhook contract for YOUPI PG V2 Sovereign Payment Gateway.
Allows merchants to create payment sessions, query verification status, and receive authoritative HMAC-SHA256 signed webhooks.
servers:
- url: http://localhost:7000
description: Local Checkout Portal (Transparent API Proxy with Zero-CORS)
- url: http://localhost:6100
description: Local Payment Core API (Direct Service Port)
- url: https://pay.yourdomain.com
description: Production Gateway Base URL
paths:
/api/v1/payments:
post:
summary: Create Payment Session / Order
description: |
Initializes a new payment session. Returns the payment identifier and the checkoutUrl
to be loaded inside the YOUPI modal iframe or standalone browser window.
operationId: createPayment
parameters:
- name: X-Merchant-Id
in: header
required: false
description: Public publishable merchant identifier. If omitted, uses the default configured merchant.
schema:
type: string
example: "00000000-0000-0000-0000-000000000001"
- name: Idempotency-Key
in: header
required: false
description: Unique idempotency key preventing duplicate payment creation.
schema:
type: string
example: "idem_9f82b71e"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
responses:
'201':
description: Payment session successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResponse'
'200':
description: Existing session returned for idempotent request or ongoing active session.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResponse'
'400':
description: Missing or invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Access blocked due to security/fraud flagging on customer account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Duplicate active payment session detected on another device.
content:
application/json:
schema:
$ref: '#/components/schemas/DuplicateSessionResponse'
/api/v1/payments/{id}:
get:
summary: Get Payment Status
description: |
Retrieves current lifecycle status and outcome of a payment session.
operationId: getPaymentStatus
parameters:
- name: id
in: path
required: true
description: Unique payment session UUID.
schema:
type: string
example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
responses:
'200':
description: Payment details and outcome.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentDetailsResponse'
'404':
description: Payment session not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v1/checkout/{id}/cancel:
post:
summary: Cancel Payment Session
description: |
Explicitly cancels an active or queued payment session, immediately releasing the UPI concurrency slot.
operationId: cancelPaymentSession
parameters:
- name: id
in: path
required: true
description: Payment session UUID to cancel.
schema:
type: string
responses:
'200':
description: Session transitioned to CANCELLED.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
status:
type: string
example: "CANCELLED"
'404':
description: Session not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
CreatePaymentRequest:
type: object
required:
- orderId
- amount
properties:
orderId:
type: string
description: Merchant order identifier.
example: "ORDER-1001"
amount:
type: string
description: Amount in Indian Rupees (INR) with up to 2 decimal places.
example: "499.00"
currency:
type: string
default: "INR"
example: "INR"
customer:
type: object
properties:
name:
type: string
example: "Mohit Kumar"
email:
type: string
example: "[email protected]"
phoneNumber:
type: string
example: "9876543210"
description:
type: string
example: "Order Payment #1001"
returnUrl:
type: string
description: Merchant URL to redirect customer upon completion.
example: "https://mystore.example/order-success?orderId=ORDER-1001"
metadata:
type: object
description: Unmodified custom key-value pairs preserved by YOUPI PG.
additionalProperties: true
example:
product_id: "TSHIRT-01"
cart_id: "CART-88"
CreatePaymentResponse:
type: object
properties:
paymentId:
type: string
example: "c7942127-14e3-469a-9e4a-9359a16f903a"
orderId:
type: string
example: "ORDER-1001"
amount:
type: string
example: "499.00"
amountPaise:
type: string
example: "49900"
currency:
type: string
example: "INR"
status:
type: string
enum: [INITIATED, ACTIVE, QUEUED, PROCESSING, SUCCESS, FAILED, EXPIRED, CANCELLED]
example: "INITIATED"
queuePosition:
type: integer
example: 0
checkoutUrl:
type: string
example: "http://localhost:7000/checkout/c7942127-14e3-469a-9e4a-9359a16f903a"
PaymentDetailsResponse:
type: object
properties:
paymentId:
type: string
example: "c7942127-14e3-469a-9e4a-9359a16f903a"
orderId:
type: string
example: "ORDER-1001"
amount:
type: string
example: "499.00"
amountPaise:
type: string
example: "49900"
currency:
type: string
example: "INR"
status:
type: string
enum: [INITIATED, ACTIVE, QUEUED, PROCESSING, SUCCESS, FAILED, EXPIRED, CANCELLED]
example: "SUCCESS"
method:
type: string
example: "UPI"
verificationLevel:
type: integer
description: 0 = unverified, 1 = SMS observed, 2 = Dual SMS + Gmail verified.
example: 2
completedAt:
type: string
format: date-time
nullable: true
example: "2026-10-07T12:00:00.000Z"
metadata:
type: object
additionalProperties: true
WebhookPayload:
type: object
description: Payload delivered to merchant configured webhook URL via HTTPS POST.
properties:
event:
type: string
enum: [SUCCESS, FAILED, EXPIRED, CANCELLED]
example: "SUCCESS"
paymentId:
type: string
example: "c7942127-14e3-469a-9e4a-9359a16f903a"
orderId:
type: string
example: "ORDER-1001"
amount:
type: string
example: "499.00"
amountPaise:
type: integer
example: 49900
currency:
type: string
example: "INR"
method:
type: string
example: "UPI"
utr:
type: string
description: 12-digit bank reference number extracted by banking observers.
example: "123456789012"
completedAt:
type: string
format: date-time
example: "2026-10-07T12:00:00.000Z"
metadata:
type: object
additionalProperties: true
DuplicateSessionResponse:
type: object
properties:
error:
type: string
example: "DUPLICATE_SESSION_DETECTED"
code:
type: string
example: "DEVICE_SESSION_MISMATCH"
session_id:
type: string
example: "c7942127-14e3-469a-9e4a-9359a16f903a"
action:
type: string
example: "END_SESSION_AND_CREATE_NEW"
message:
type: string
ErrorResponse:
type: object
properties:
error:
type: string
example: "Missing required fields: orderId and amount."
message:
type: string
nullable: true