Initiate Payment with SplitInfo
To Initiate Payment with SplitInfo API helps you initiate payments and distribute the amount across multiple linked accounts. It supports split settlement for both self and vendor accounts. You can configure selected payment instruments like UPI cards and net banking. The API ensures smooth transactions with flexible checkout options. Use iFrame or redirect method to open the PayPage. Make sure split settlement is enabled before using this feature.
⚠️ Prevent Transaction Blocking in Production!
To avoid transaction blocking in production, ensure the following:
- If using a personalised Chrome tab within your Android app prevents URL retrieval, switch to SDK integration.
- If launching PayPage in a new window or tab removes the referrer, then use redirection or an iFrame instead.
- Do not use a
no-referrer-policyon the checkout page, as it results in blank merchant URLs.
Environment
| Environment | Http Method | Value |
|---|---|---|
Sandbox | POST | https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/pay |
Production | POST | https://api.phonepe.com/apis/checkout/v2/pay |
⚠️ Setup Required Before Payment Initiation!
Before initiating the payment, install the PhonePe Test App and ensure the Payment Template is configured.
Failing to do this 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_CHECKOUT",
"message": "Payment message used for collect requests",
"merchantUrls":
{
"redirectUrl": ""
}
},
"splitSettlementInfo":
{
"type": "PERCENT", // Values: PERCENT or ABSOLUTE
"accountsSplit":
[
{
"value": 10.5, // Floor upto 2 decimal
"accountId": "B12345678"
},
{
"value": 20.5,
"accountId": "B9101112"
}
]
}
}{
"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_CHECKOUT",
"message": "Payment message used for collect requests",
"merchantUrls":
{
"redirectUrl": ""
},
"paymentModeConfig":
{
"enabledPaymentModes":
[
{
"type": "UPI_INTENT"
},
{
"type": "UPI_COLLECT"
},
{
"type": "UPI_QR"
},
{
"type": "NET_BANKING"
},
{
"type": "CARD",
"cardTypes":
[
"DEBIT_CARD",
"CREDIT_CARD"
]
}
],
"disabledPaymentModes":
[
{
"type": "UPI_INTENT"
},
{
"type": "UPI_COLLECT"
},
{
"type": "UPI_QR"
},
{
"type": "NET_BANKING"
},
{
"type": "CARD",
"cardTypes":
[
"DEBIT_CARD",
"CREDIT_CARD"
]
}
]
}
},
"splitSettlementInfo":
{
"type": "PERCENT", // Values: PERCENT or ABSOLUTE
"accountsSplit":
[
{
"value": 10.5, // Floor upto 2 decimal
"accountId": "B12345678"
},
{
"value": 20.5,
"accountId": "B9101112"
}
]
}
}Important Notes for Configuring paymentModeConfig
You can choose to control the payment instruments that appear on the PhonePe Checkout Page using the paymentModeConfig block. If you do not wish to manage this manually, you can skip this block and the default instruments configured on PhonePe will be shown.
When to Use
- Use the
paymentModeConfigblock only if you want to manage which payment methods your customers see on the checkout page. - You must pass either
enabledPaymentModesordisabledPaymentModes. If both are passed, the API will return an error.
How it Works
paymentModeConfig.enabledPaymentModes- Use this to allow only specific instruments. Only the instruments listed here will appear on the checkout page. All other instruments, even if enabled on PhonePe, will be hidden.
- paymentModeConfig.
disabledPaymentModes- Use this to hide specific instruments. The instruments listed here will not appear on the checkout page. All other instruments enabled on PhonePe will still be visible.
Special Note on Configuring the CARD Instrument
When you choose to enable or disable the CARD payment option, it is important to include the cardTypes field along with the type.
- If you set
enabledPaymentModes.typetoCARDbut do not passenabledPaymentModes.cardTypes, the checkout page will show the card types based on what is active on your PhonePe account. This may include Credit Card, Debit Card, or both. - If you pass
enabledPaymentModes.typeasCARDand setenabledPaymentModes.cardTypestoDEBIT_CARD, then only the Debit Card option will be shown on the checkout page. - If you set
disabledPaymentModes.typetoCARDwithout passingdisabledPaymentModes.cardTypes, the Card option will still be shown based on what is active on your PhonePe account. - If
disabledPaymentModes.typeis set toCARDanddisabledPaymentModes.cardTypesis set toDEBIT_CARD, only the Debit Card option will be hidden. Credit Card will still be available. - To hide both Debit Card and Credit Card, you need to set
disabledPaymentModes.typetoCARDanddisabledPaymentModes.cardTypestoDEBIT_CARDandCREDIT_CARD. This will ensure that the Card option is not shown at all on the checkout page.
| Parameter Name | Data Type | Description | Mandatory (Yes/No) | Constraints |
| merchantOrderId | String | Unique merchant order id generated by merchant | Yes | Max Length = 63 charactersNo Special characters allowed except underscore “_” and hyphen “-“ |
| expireAfter | Long | Order expiry in seconds. If not passed, default value will be used. | No | Min Value = 300, Max Value = 3600 (in Seconds) Default Value = 1200 Secs (20 Mins) |
| amount | Long | Order amount in paisa | Yes | Min Value = 100 (In paise) |
| metaInfo | Object | Merchant defined meta info to store additional information.same data will be returned in status and callback response | No | |
| metaInfo.udf1-4 | String | Merchant defined additional information | No | Max length = 256 characters |
| paymentFlow | Object | Additional details required by this flow | Yes | |
| paymentFlow.type | String | Type of payment flow | Yes | Valued Allowed = [PG_CHECKOUT] |
| paymentFlow.message | String | Payment message used for collect requests | No | |
| paymentFlow.merchantUrls | Object | Object to store different merchant Urls | Yes | |
| paymentFlow.merchantUrls.redirectUrl | String | Url where user will be redirected after success/failed payment. | Yes | |
| paymentModeConfig | Object | Additional details to display only the selected instruments | Optional | Either enabledPaymentModes or disabledPaymentModes is required, if both are present API will throw error. |
| splitSettlementInfo | Object | Accounts into which the merchant wants to split the amount. Applicable only for merchants who have split enabled. | No | Total Amount split must not be more than the amount provided. |
| splitSettlementInfo.type | String | Yes | Type of split. i.e if the amount in split is in percent or absolute. | |
| splitSettlementInfo.accountsSplit | List | Yes | Specifies the account details where the transaction amount should be split and transferred. |
The splitSettlementInfo object contains two key details:
| 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 | Specifies the account details where the transaction amount should be split and transferred. |
If splitSettlementInfo.type is set to PERCENT, then accountsSplit will include:
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
value | Double | Yes | Indicates the percentage of the transaction amount to be split, with precision allowed up to two decimal places. The value is calculated using floor rounding. |
accountId | String | Yes | A reference name assigned during beneficiary setup, used to identify or manage the beneficiary. |
If splitSettlementInfo.type is set to "ABSOLUTE", then accounts will include:
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
value | Double | Yes | Amount in Paisa to be split |
accountId | String | Yes | Name given by the merchant while adding beneficiary, this will be reference for the merchant. |
Response
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
Response Payload
{
"orderId": "OMO123456789",
"state": "PENDING",
"expireAt": 1703756259307,
"redirectUrl": "https://mercury-uat.phonepe.com/transact/uat_v2?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MjgyNTk1MzE0NzgsIm1lcmNoYW50SWQiOiJWUlVBVCIsIm1lcmNoYW50T3JkZXJJZCI6Ik1PLTlkMC1hNmMyYmY1ZWM4MmUifQ.Trj5fub__kJpQhzOlJttXl2UPruHE7fsbH5QWj-iy6E"
}
{
"
code": SPLIT_SETTLEMENT_NOT_ENABLED/ INVALID_SPLIT_DETAILS / BAD_REQUEST
"message": Split settlement not enabled/ invalid split details
}{
"code": "BAD_REQUEST",
"message": "Please check the inputs you have provided."
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}
How to Initiate Payment ?
The JS Checkout bundle helps display the PayPage directly on your website. You can choose to show it in an IFrame (recommended) or through a Redirect mode.
- Invoke PayPage on the Checkout Page
- In IFrame (Recommended)
- In Redirect Mode
<
script src="https://mercury.phonepe.com/web/bundle/checkout.js"></
script>Once you include the script:
- The
PhonePeCheckoutobject becomes available, which you can use to open the PayPage using thetransactfunction. - You can also use the
closePagefunction to manually close the PayPage if it is opened in an iFrame.
Make sure to call the correct function and pass the required parameters to manage the PayPage flow smoothly on your checkout page.
Response Parameters
| Field Name | Data Type | Description |
|---|---|---|
orderId | String | A unique internal order ID generated by the PG. |
state | String | Indicates the current status of the order. The expected value at the time of order creation is “CREATED”. |
expiryAt | Long | The timestamp at which the order will expire, represented in epoch (milliseconds). |
redirectUrl | String | The URL to which the user should be redirected to complete the payment process. |