Payment Lifecycle and Request Structure
Payment Lifecycle
Status | Description |
---|---|
CREATED | Payment request initialized. |
AUTHORIZED | Payment authorized post OTP (if applicable). |
PENDING_WITH_BANK | Awaiting confirmation from the customer’s bank. |
SUCCESS | Payment successfully completed. |
FAILED | Payment failed due to error, decline, or timeout. |
CANCELLED | Payment cancelled by the user. |
PARTIALLY_REFUNDED | A portion of the transaction amount has been refunded. |
REFUNDED | Full amount has been refunded. |
Payment Request Structure
Field | Type | Required | Description |
---|---|---|---|
orderId | string | Yes | Unique identifier for the transaction. |
paymentDetail | object | Optional | Contains amount and currency . |
paymentMode | string | Yes | Accepted values: NET_BANKING , UPI , CREDIT_CARD , DEBIT_CARD , PREPAID_CARD , PAY_LATER , WALLET , CORPORATE_CARD |
cardHolderName | string | Depends | Required for card-based payments. |
cardNumber | string | Depends | Required for card-based payments. |
cvv | string | Depends | Required for card-based payments. |
expiry | string | Depends | Format: MM/YY . Required for card-based payments. |
bankCode | string | Depends | Required for NetBanking , BNPL , and Wallet modes. |
bnplPaymentOptionId | string | Depends | Required for BNPL mode. |
vpa | string | Depends | Required for UPI mode. |
accountNumber | string | Depends | Required for UPI TPV. Must be between 9–36 characters. |
ifsc | string | Depends | Required for UPI TPV. Must match ^[A-Z]{4}0[A-Z0-9]{6}$ . |
Example Payment Request
{
"orderId": "ORD123456789",
"paymentDetail": {
"amount": 1000,
"currency": "INR"
},
"paymentMode": "CREDIT_CARD",
"cardHolderName": "John Doe",
"cardNumber": "4111111111111111",
"cvv": "123",
"expiry": "12/24",
"bankCode": "HDFC",
"vpa": "john.doe@upi",
"accountNumber": "123456789012",
"ifsc": "HDFC0001234"
}
Key Considerations
orderId
Must be unique per transaction to avoid payment duplication.
Format and validate card/UPI/bank details on the client side to prevent backend errors.
Implement logic for status transitions
FAILED
,PENDING_WITH_BANK
,CANCELLED
Ensure sensitive fields are handled over secure connections and never exposed on the client.