Skip to main content
Phone Pe Business Logo

Token

This flow enables payment using a TOKEN along with support for split settlements. PCI-DSS certification is required to use this flow. Token and CVV must be encrypted using RSA 4096 with RSA/ECB/PKCS1Padding. The encryptionKey and encryptionKeyId are shared at the MID level and may differ across MIDs, so these values should not be hardcoded. Split settlement details can be configured using the splitSettlementInfo block.

EnvironmentHttp MethodAPI
SandboxPOSThttps://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/pay
ProductionPOSThttps://cards.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 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",    
       "paymentMode" : {
            "type" : "TOKEN",
            "authMode": "3DS",
            "tokenDetails": {
                "encryptedToken": "<encryptedToken>",
                "encryptionKeyId": 122,
                "expiry": {
                    "month": "12",
                    "year": "2029"
                },
                "panSuffix": "<panSuffix>",
                "cardHolderName": "Dummy Name",
                "cryptogram": "<cryptogram>",
                "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"
            }
        ]
    } 

Request Parameters
Parameter NameData TypeDescriptionMandatory (Yes/No)Constraints
authModeStringAuthentication mode for the transaction. Defaults to 3DS.Yes
tokenDetails.encryptionKeyIdIntegerID of the key used to encrypt the card number, token, and CVV.Yes
tokenDetails.encryptedTokenStringToken number encrypted using RSA 4096 with RSA/ECB/PKCS1Padding.Yes
tokenDetails.encryptedCvvStringCVV encrypted using RSA 4096 with RSA/ECB/PKCS1Padding.Yes
tokenDetails.cryptogramStringCryptogram received from the tokenization gateway.Yes
tokenDetails.panSuffixStringLast four digits of the card number.Yes
tokenDetails.cardHolderNameStringName of the cardholder.No
tokenDetails.expiry.monthStringExpiry month of the token.Yes
tokenDetails.expiry.yearStringExpiry year of the token.Yes
merchantOrderIdStringUnique order ID created by the merchant to identify the transaction.YesMax Length = 63 charactersNo Special characters allowed except underscore “_” and hyphen “-“
amountLongTotal amount of the order specified in paisa.YesMin Value = 100 (In paise)
expireAfterLongTime after which the order will expire, specified in seconds. If not provided, a default value will be applied.NoMin Value = 300, Max Value = 5184000

Default Value (in Secs):
UPI QR: 480
UPI Intent : 600
UPI Collect: 480
Card : 720
NetBanking : 480
metaInfoObjectMerchant 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-5StringAdditional information provided by the merchant, usually used to store custom data related to the order.NoMax length = 256 characters 
deviceContext.deviceOSStringDevice operating system is required only when the payment mode is UPI_INTENT.YesValues Allowed:
• iOS
• ANDROID
deviceContext.merchantCallBackSchemeStringMerchant callback scheme is required only when the target app is PhonePe and the device operating system is IOS.Yes
paymentFlowObjectAdditional information required to complete this payment flow.Yes
paymentFlow.typeStringSpecifies the type of payment flow used.YesValued Allowed: PG
paymentModeObjectContains information related to available payment modes.Yes
paymentMode.typeStringSpecifies the type of the payment methodYesValues Allowed:
• UPI_INTENT
• UPI_COLLECT
• UPI_QR
• NET_BANKING
• TOKEN
• CARD
merchantUrls.redirectUrlStringURL to which the user is redirected after completing the payment. Required only for NET BANKING, TOKEN, and CARD payment modes.YesValid Http url. 
splitSettlementInfoObjectAccounts where the merchant wants the amount to be distributed. Applicable only if split is enabled for the merchant.NoThe total split amount must not exceed the order amount provided.

The splitSettlementInfo field contains two key components which are explained below.

Field NameData TypeMandatoryDescription
splitSettlementInfo.typeStringYesType of split. i.e if the amount in split is in percent or absolute.
splitSettlementInfo.accountsSplitListYesInformation 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 NameData TypeMandatoryDescription
valueDoubleYesPercentage of the amount to be split, allowing up to two decimal places.
accountIdStringYesName 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 NameData TypeMandatoryDescription
valueDoubleYesAmount to be split, specified in Paisa.
accountIdStringYesName assigned by the merchant while adding the beneficiary. This acts as a reference for the merchant.
Response Headers
Header NameHeader Value
Content-Typeapplication/json
Case 1: Success Response
{
	"orderId": "OMO123456789",
	"state": "PENDING",
	"expireAt": 1703756259307,
	"redirectUrl": ""
}
Case 2: Order fails validation due to issues like split not being enabled, invalid split details, or incorrect split amount.
{
    "code": SPLIT_SETTLEMENT_NOT_ENABLED/ INVALID_SPLIT_DETAILS / BAD_REQUEST
    "message": Split settlement not enabled/ invalid split details
}
Case 3: 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."
}
Response Field Details:
Field NameData TypeDescription
orderIdStringInternal order ID generated by the PG.
stateStringCurrent state of the created order. The expected value is CREATED.
expiryAtLongThe timestamp when the order will expire, represented in epoch (milliseconds).
redirectUrlStringThe URL to which the merchant should redirect the user to complete the payment.
intentUrlStringThe intent URL used to trigger the UPI app flow. Present only in case of UPI_INTENT or UPI_QR payment modes.
Error Response Field Details:
Field NameData TypeDescription
codeStringError Code
messageStringError Message
Is this article helpful?