Cards
This flow enables payments using cards with the option to split the amount across multiple accounts. Card details must be securely encrypted using RSA 4096 encryption. The request includes order information, encrypted card data, and a redirect URL for 3DS authentication. The response returns an orderId, a PENDING status, and a redirectUrl for completing the payment.
⚠️ Custom Card Flow – PCI-DSS Requirement!
To use the Custom Card Flow, PCI-DSS certification is mandatory. Card Number and CVV must be encrypted using RSA 4096 with RSA/ECB/PKCS1Padding. The encryptionKey and encryptionKeyId are issued at the MID level and may vary across MIDs. Do not hardcode these values.
Environment
| Environment | Http Method | API |
|---|---|---|
| POST | https://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/pay |
Production | POST | https://api.phonepe.com/apis/pg/payments/v2/pay |
📘 Pre-requisite for UAT Testing
Before initiating the payment, ensure that the PhonePe Test App is installed and the template is configured. Failing to do so will result in an HTTP 500 error.
Request
| Header Name | Header Value |
| Content-Type | application/json |
| Authorization | O-Bearer <partner-auth-token> |
| X-MERCHANT-ID | MID |
{
"merchantOrderId": "TX123456",
"amount": 1000,
"expireAfter": 1200,
"metaInfo": {
"udf1": "<additional-information-1>",
"udf2": "<additional-information-2>",
"udf3": "<additional-information-3>",
"udf4": "<additional-information-4>",
"udf5": "<additional-information-5>"
},
"paymentFlow": {
"type": "PG",
"paymentMode" : {
"type": "CARD",
"authMode": "3DS",
"cardDetails": {
"encryptedCardNumber": "<encryptedCardNumber>",
"encryptionKeyId": 1,
"cardHolderName": "Dummy Name",
"expiry": {
"month": "12",
"year": "2029"
},
"encryptedCvv": "<encryptedCvv>"
},
"merchantUserId": "dummyUser"
},
"merchantUrls": {
"redirectUrl": "<redirectUrl>"
}
},
"splitSettlementInfo":
{
"type": "PERCENT", // Values: PERCENT or ABSOLUTE
"accountsSplit":
[
{
"value": 10.5, // Floor upto 2 decimal
"accountId": "B12345678"
},
{
"value": 20.5, // Floor
"accountId": "B9101112"
}
]
}
}| Parameter Name | Data Type | Description | Mandatory (Yes/No) | Constraints |
merchantOrderId | String | Unique order ID created by the merchant to identify the transaction. | Yes | Max Length = 63 charactersNo Special characters allowed except underscore “_” and hyphen “-“ |
amount | Long | Total amount of the order specified in paisa. | Yes | Min Value = 100 (In paise) |
expireAfter | Long | Time after which the order will expire, specified in seconds. If not provided, a default value will be applied. | No | Min Value = 300, Max Value = 5184000 Default Value (in Secs): UPI QR: 480 UPI Intent : 600 UPI Collect: 480 Card : 720 NetBanking : 480 |
metaInfo | Object | Merchant defined meta information used to store additional data related to the order. The same data will be returned in the status and callback response. | No | |
metaInfo.udf1-5 | String | Additional information provided by the merchant, usually used to store custom data related to the order. | No | Max length = 256 characters |
deviceContext.deviceOS | String | Device operating system is required only when the payment mode is UPI_INTENT. | Yes | Values Allowed: • iOS • ANDROID |
deviceContext.merchantCallBackScheme | String | Merchant callback scheme is required only when the target app is PhonePe and the device operating system is IOS. | Yes | |
paymentFlow | Object | Additional information required to complete this payment flow. | Yes | |
paymentFlow.type | String | Specifies the type of payment flow used. | Yes | Valued Allowed: PG |
paymentMode | Object | Contains information related to available payment modes. | Yes | |
paymentMode.type | String | Specifies the type of the payment method | Yes | Values Allowed: • UPI_INTENT • UPI_COLLECT • UPI_QR • NET_BANKING • TOKEN • CARD |
merchantUrls.redirectUrl | String | URL to which the user is redirected after completing the payment. Required only for NET BANKING, TOKEN, and CARD payment modes. | Yes | Valid Http url. |
splitSettlementInfo | Object | Accounts where the merchant wants the amount to be distributed. Applicable only if split is enabled for the merchant. | No | The total split amount must not exceed the order amount provided. |
The splitSettlementInfo field contains two key components which are explained below.
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
splitSettlementInfo.type | String | Yes | Type of split. i.e if the amount in split is in percent or absolute. |
splitSettlementInfo.accountsSplit | List | Yes | Information of the account into which the split should be done |
If splitInfo.type is set to “PERCENT”, the splitInfo.accounts field should contain details of each account along with the percentage of the total amount to be allocated.
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
value | Double | Yes | Percentage of the amount to be split, allowing up to two decimal places. |
accountId | String | Yes | Name assigned by the merchant when adding the beneficiary, used for the merchant’s reference. |
If splitInfo.type is set to ABSOLUTE, then accountsSplit must include the following details.
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
value | Double | Yes | Amount to be split, specified in Paisa. |
accountId | String | Yes | Name assigned by the merchant while adding the beneficiary. This acts as a reference for the merchant. |
Response Details
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
{
"orderId": "OMO123456789",
"state": "PENDING",
"expireAt": 1703756259307,
"redirectUrl": ""
}{
"code": SPLIT_SETTLEMENT_NOT_ENABLED/ INVALID_SPLIT_DETAILS / BAD_REQUEST
"message": Split settlement not enabled/ invalid split details
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}| Field Name | Data Type | Description |
|---|---|---|
orderId | String | Internal order ID generated by the PG. |
state | String | Current state of the created order. The expected value is CREATED. |
expiryAt | Long | The timestamp when the order will expire, represented in epoch (milliseconds). |
redirectUrl | String | The URL to which the merchant should redirect the user to complete the payment. |
intentUrl | String | The intent URL used to trigger the UPI app flow. Present only in case of UPI_INTENT or UPI_QR payment modes. |
| Field Name | Data Type | Description |
|---|---|---|
code | String | Error Code |
message | String | Error Message |