Skip to main content
Phone Pe Business Logo

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:

  1. If using a personalised Chrome tab within your Android app prevents URL retrieval, switch to SDK integration.
  2. If launching PayPage in a new window or tab removes the referrer, then use redirection or an iFrame instead.
  3. Do not use a no-referrer-policy on the checkout page, as it results in blank merchant URLs.
EnvironmentHttp MethodValue
SandboxPOSThttps://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/pay
ProductionPOSThttps://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 Headers
Header NameHeader Value
Content-Typeapplication/json
AuthorizationO-Bearer <partner-auth-token>
X-MERCHANT-IDMID
Sample Request
{
    "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"
            }
        ]
    }
}
Sample Request with Selected Instrument
{
    "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 paymentModeConfig block only if you want to manage which payment methods your customers see on the checkout page.
  • You must pass either enabledPaymentModes or disabledPaymentModes. 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.type to CARD but do not pass enabledPaymentModes.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.type as CARD and set enabledPaymentModes.cardTypes to DEBIT_CARD, then only the Debit Card option will be shown on the checkout page.
  • If you set disabledPaymentModes.type to CARD without passing disabledPaymentModes.cardTypes, the Card option will still be shown based on what is active on your PhonePe account.
  • If disabledPaymentModes.type is set to CARD and disabledPaymentModes.cardTypes is set to DEBIT_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.type to CARD and disabledPaymentModes.cardTypes to DEBIT_CARD and CREDIT_CARD. This will ensure that the Card option is not shown at all on the checkout page.
Request Parameters
Parameter NameData TypeDescriptionMandatory (Yes/No)Constraints
merchantOrderIdStringUnique merchant order id generated by merchantYesMax Length = 63 charactersNo Special characters allowed except underscore “_” and hyphen “-“
expireAfterLongOrder expiry in seconds. If not passed, default value will be used.NoMin Value = 300, Max Value = 3600 (in Seconds)
Default Value = 1200 Secs (20 Mins)
amountLongOrder amount in paisaYesMin Value = 100 (In paise)
metaInfoObjectMerchant defined meta info to store additional information.same data will be returned in status and callback responseNo
metaInfo.udf1-4StringMerchant defined additional informationNoMax length = 256 characters
paymentFlowObjectAdditional details required by this flowYes
paymentFlow.typeStringType of payment flowYesValued Allowed = [PG_CHECKOUT]
paymentFlow.messageStringPayment message used for collect requestsNo
paymentFlow.merchantUrlsObjectObject to store different merchant UrlsYes
paymentFlow.merchantUrls.redirectUrlStringUrl where user will be redirected after success/failed payment.Yes
paymentModeConfigObjectAdditional details to display only the selected instrumentsOptionalEither enabledPaymentModes or disabledPaymentModes is required, if both are present API will throw error.
splitSettlementInfoObjectAccounts into which the merchant wants to split the amount. Applicable only for merchants who have split enabled.NoTotal Amount split must not be more than the amount provided.
splitSettlementInfo.typeStringYesType of split. i.e if the amount in split is in percent or absolute.
splitSettlementInfo.accountsSplitListYesSpecifies the account details where the transaction amount should be split and transferred.

The splitSettlementInfo object contains two key details:

Field NameData TypeMandatoryDescription
splitSettlementInfo.typeStringYesType of split. i.e if the amount in split is in percent or absolute.
splitSettlementInfo.accountsSplitListYesSpecifies the account details where the transaction amount should be split and transferred.

If splitSettlementInfo.type is set to PERCENT, then accountsSplit will include:

Field NameData TypeMandatoryDescription
valueDoubleYesIndicates the percentage of the transaction amount to be split, with precision allowed up to two decimal places. The value is calculated using floor rounding.
accountIdStringYesA 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 NameData TypeMandatoryDescription
valueDoubleYesAmount in Paisa to be split
accountIdStringYesName given by the merchant while adding beneficiary, this will be reference for the merchant.
Response Headers
Header NameHeader Value
Content-Typeapplication/json

Response Payload

Case 1: Order with Validation Failure due to Invalid or Unsupported Split Information
{
    "orderId": "OMO123456789",
    "state": "PENDING",
    "expireAt": 1703756259307,    
    "redirectUrl": "https://mercury-uat.phonepe.com/transact/uat_v2?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MjgyNTk1MzE0NzgsIm1lcmNoYW50SWQiOiJWUlVBVCIsIm1lcmNoYW50T3JkZXJJZCI6Ik1PLTlkMC1hNmMyYmY1ZWM4MmUifQ.Trj5fub__kJpQhzOlJttXl2UPruHE7fsbH5QWj-iy6E"
}
Case 2: Orders Failing Due to Invalid Split Configuration or Validation Errors
{
    "
code": SPLIT_SETTLEMENT_NOT_ENABLED/ INVALID_SPLIT_DETAILS / BAD_REQUEST
    "message": Split settlement not enabled/ invalid split details
}
Case 3: Duplicate Order ID Not in Created State
{
    "code": "BAD_REQUEST",
    "message": "Please check the inputs you have provided."
}
Case 4: Internal Server Error
{
    "code": "INTERNAL_SERVER_ERROR",
    "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

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 to include
<
script src="https://mercury.phonepe.com/web/bundle/checkout.js"></
script>

Once you include the script:

  • The PhonePeCheckout object becomes available, which you can use to open the PayPage using the transact function.
  • You can also use the closePage function 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.

Field NameData TypeDescription
orderIdStringA unique internal order ID generated by the PG.
stateStringIndicates the current status of the order. The expected value at the time of order creation is “CREATED”.
expiryAtLongThe timestamp at which the order will expire, represented in epoch (milliseconds).
redirectUrlStringThe URL to which the user should be redirected to complete the payment process.
Is this article helpful?