Pay API

This API initiates a payment transaction.

Quick Links

👍

The API endpoint remains the same for all the payment instruments.

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload + "/pg/v1/pay" +
salt key) + ### + salt index

Request Parameters - Common Parameters

Parameter NameData TypeDescriptionMandatoryComments
merchantIdSTRINGUnique MerchantID assigned to the merchant by PhonePeYes
merchantTransactionIdSTRINGUnique TransactionID generated by the merchant to track request to PhonePe
transactionId length should be less than 38 characters.
Yes
amountLONGTransaction amount in PaiseYes
merchantUserIdSTRINGUnique UserID of the users generated by the merchant.

Note:
Avoid passing email/mobile number.
ConditionalMandatory if paymentInstrument.type is:
● PAY_PAGE
● CARD
● SAVED_CARD

Optional for if paymentInstrument.type is:
● UPI_INTENT
● UPI_COLLECT
● UPI_QR
● TOKEN
● NET_BANKING
redirectUrlSTRINGThe url where the user will be redirected after transaction completion.Yes
redirectModeENUMGET / POST modes for redirectUrlYesPossible values:
● GET
● POST
callbackUrlSTRINGThe url where server to server callback will be posted. Always POSTYesThis callback will be of POST type and will contain the same payload as the status response. The callback will contain an X-VERIFY header which the merchant should verify.
paymentInstrumentOBJECTPayment detailsYes
paymentInstrument.typeENUMPayment instrument typeYesPossible values:
● PAY_PAGE
● CARD
● UPI_INTENT
● SAVED_CARD
● TOKEN
● UPI_COLLECT
● UPI_QR
● NET_BANKING
mobileNumberSTRINGMobile number of the userNo

Pay Request For Web Flow

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "redirectUrl": "https://webhook.site/redirect-url",
  "redirectMode": "POST",
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "PAY_PAGE"
  }
}
{
    "request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiUEFZX1BBR0UiCiAgfQp9"
}

Request Field Details
For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
paymentInstrument.typeENUMType of instrument with which payment is being initiatedYesValues = PAY_PAGE

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Iniiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "instrumentResponse": {
        "type": "PAY_PAGE",
            "redirectInfo": {
            "url": "https://mercury-uat.phonepe.com/transact?token=MjdkNmQ0NjM2MTk5ZTlmNDcxYjY3NTAxNTY5MDFhZDk2ZjFjMDY0YTRiN2VhMjgzNjIwMjBmNzUwN2JiNTkxOWUwNDVkMTM2YTllOTpkNzNkNmM2NWQ2MWNiZjVhM2MwOWMzODU0ZGEzMDczNA",
        "method": "GET"
      }
    }
  }
}

Pay Request For Card Flow

Sample Request

{
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "OD620471739210623",
    "merchantUserId": "MU933037302229373",
    "amount": 10000,
    "redirectUrl": "https://webhook.site/redirect-url",
    "redirectMode": "POST",
    "callbackUrl": "https://webhook.site/callback-url",
    "mobileNumber": "9999999999",
    "paymentInstrument": {
        "type": "CARD",
        "authMode": "3DS",
        "saveCard": true,
        "cardDetails": {
            "encryptedCardNumber": "<encrypted_card_number>",
            "encryptionKeyId": 10,
            "cardHolderName": "Carlos Sainz",
            "expiry": {
                "month":"06",
                "year":"2025"
            },
            "encryptedCvv": "<encrypted_cvv_number>",
            "billingAddress": {
                "line1": "Unit No.001, Ground Floor, Boston House",
                "line2": "Suren Road, Andheri(East)",
                "city": "Mumbai",
                "state": "Maharashtra",
                "zip": "400093",
                "country": "India"
            }
        }
    }
}
{
  "request":"ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICAgImFtb3VudCI6IDEwMDAwLAogICAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgICAgICJ0eXBlIjogIkNBUkQiLAogICAgICAgICJhdXRoTW9kZSI6ICIzRFMiLAogICAgICAgICJzYXZlQ2FyZCI6IHRydWUsCiAgICAgICAgImNhcmREZXRhaWxzIjogewogICAgICAgICAgICAiZW5jcnlwdGVkQ2FyZE51bWJlciI6ICI8ZW5jcnlwdGVkX2NhcmRfbnVtYmVyPiIsCiAgICAgICAgICAgICJlbmNyeXB0aW9uS2V5SWQiOiAxMCwKICAgICAgICAgICAgImNhcmRIb2xkZXJOYW1lIjogIkNhcmxvcyBTYWlueiIsCiAgICAgICAgICAgICJleHBpcnkiOiB7CiAgICAgICAgICAgICAgICAibW9udGgiOiIwNiIsCiAgICAgICAgICAgICAgICAieWVhciI6IjIwMjUiCiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJlbmNyeXB0ZWRDdnYiOiAiPGVuY3J5cHRlZF9jdnZfbnVtYmVyPiIsCiAgICAgICAgICAgICJiaWxsaW5nQWRkcmVzcyI6IHsKICAgICAgICAgICAgICAgICJsaW5lMSI6ICJVbml0IE5vLjAwMSwgR3JvdW5kIEZsb29yLCBCb3N0b24gSG91c2UiLAogICAgICAgICAgICAgICAgImxpbmUyIjogIlN1cmVuIFJvYWQsIEFuZGhlcmkoRWFzdCkiLAogICAgICAgICAgICAgICAgImNpdHkiOiAiTXVtYmFpIiwKICAgICAgICAgICAgICAgICJzdGF0ZSI6ICJNYWhhcmFzaHRyYSIsCiAgICAgICAgICAgICAgICAiemlwIjogIjQwMDA5MyIsCiAgICAgICAgICAgICAgICAiY291bnRyeSI6ICJJbmRpYSIKICAgICAgICAgICAgfQogICAgICAgIH0KICAgIH0KfQ=="
}

Request Field Details
For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
paymentInstrument.typeENUMType of instrument with which payment is being initiatedYesValues = CARD
authModeSTRINGAuthorisation mode with PG for payment validationYes
saveCardBOOLEANtrue if merchant wants to save token on phonepe platformYes
encryptionKeyIdLONGKeyId of key which merchant uses to encrypt card number & cvvYes
encryptedCardNumberSTRINGEncrypted 16-Digit Card Number entered by the user.
Encryption Method: RSA 4096
Yes
cardHolderNameSTRINGName of holder printed on cardYes
expiry.monthSTRINGCard Expiry MonthYes
expiry.yearSTRINGCard Expiry YearYes
encryptedCvvSTRINGEncrypted CVV of the card with which payment is being initiated.

Encryption Method: RSA 4096
Yes
billingAddressOBJECTBilling address details to be passed to the PGNo

Sample Response

{
    "success": true,
    "code": "PAYMENT_INITIATED",
    "message": "Payment initiated",
    "data": {
        "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "MT7850590068188104",
        "transactionId": "T2204071334465821320730",
        "instrumentResponse": {
            "type": "CARD",
            "redirectInfo": {
                "url": "https://pg-uat.phonepe.com/pg-transport/v1/redirect/dummy?id=d085d94a-8d58-4043-a73f-31e9de41af46",
                "method": "GET"
            }
        }
    }
}

Sample S2S Callback after Card Tokenization is Success

{
  "success": true,
  "code": "TOKENIZATION_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "state": "COMPLETED",
    "responseCode": "TOKENIZATION_SUCCESS",
    "cardId": "C34081038691063664100",
    "cardMetaData": {
      "cardType": "CREDIT_CARD",
      "cardIssuer": "VISA",
      "bankCode": "ICICI",
      "cardSuffix": "5544",
      "expiry": {
        "month": "12",
        "year": "2030"
      }
    },
    "tokenMetaData": {
      "panReferenceNumber": "qzyezl9ocsw42m3tckli",
      "tokenBin": "456234",
      "expiry": {
        "month": "12",
        "year": "2030"
      },
      "tokenState": "ACTIVE"
    }
  }
}

Sample S2S Callback after Card Tokenization is Failed

{
  "success": false,
  "code": "TOKENIZATION_ERROR",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "state": "FAILED",
    "responseCode": "AUTH_TRANSACTION_FAILED"
  }
}

Pay Request For UPI Open Intent Flow

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MU933037302229373",
  "amount": 10000,
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "deviceContext": {
    "deviceOS": "ANDROID"
  },
  "paymentInstrument": {
    "type": "UPI_INTENT",
    "targetApp": "com.phonepe.app"
  }
}
{
  "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MU933037302229373",
  "amount": 10000,
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "deviceContext": {
    "deviceOS": "IOS"
  },
  "paymentInstrument": {
    "type": "UPI_INTENT",
    "targetApp": "PHONEPE"
  }
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKIAkibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJBTkRST0lEIgogIH0sCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0lOVEVOVCIsCiAgICAidGFyZ2V0QXBwIjogImNvbS5waG9uZXBlLmFwcCIKICB9Cn0="
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKIAkibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJJT1MiCiAgfSwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJVUElfSU5URU5UIiwKICAgICJ0YXJnZXRBcHAiOiAiUEhPTkVQRSIKICB9Cn0="
}

Request Field Details
For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
paymentInstrument.typeSTRINGType of instrument with which payment is being initiatedYesvalue = UPI_INTENT
paymentInstrument.targetAppENUMTarget app for intent.
For iOS: If one needs to generate an intent url targeted at specific app on iOS, then the respective value should be passed.

For ANDROID: If one needs to open specific app on intent, then the respective package name needs to be passed.
YesPossible values for iOS:
● PHONEPE
● GPAY
● PAYTM

Possible values for Android:
Android package name
(For example:
● com.phonepe.app for PHONEPE
● net.one97.paytm for PAYTM)
deviceContext.deviceOSSTRINGDevice Operating SystemENUMPossible values for iOS:
● ANDROID
● IOS

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
        "instrumentResponse": {
            "type": "UPI_INTENT",
            "intentUrl": "upi://[email protected]&pn=MerchantUAT&am=3.00&mam=3.00&tr=OD620471739210623&tn=Payment%20for%OD620471739210623&mc=5311&mode=04&purpose=00&utm_campaign=DEBIT&utm_medium=FKRT&utm_source=OD620471739210623"
    }   
    }
}
{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "instrumentResponse": {
      "type": "UPI_INTENT",
      "intentUrl": "ppe://[email protected]&pn=MerchantUAT&am=1.00&mam=1.00&tr=MT7850590068188104&tn=Payment%20for%20MT7850590068188104&mc=5311&mode=04&purpose=00&utm_campaign=B2B_PG&utm_medium=JUSPAYUAT&utm_source=MT7850590068188104"
    }
  }
}

Sample Failure Response

{
  "success": false,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

Pay Request with Card Id

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "OD620471739210623",
  "merchantUserId": "MU933037302229373",
  "amount": 10000,
  "redirectUrl": "https://mykewlapp.com/redirect",
  "redirectMode": "POST",
  "callbackUrl": "https://mykewlapp.com/callback",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "SAVED_CARD",
    "authMode": "3DS",
    "cardDetails": {
      "cardId": "C903889349294273423",
      "encryptedCvv": "<encrypted_cvv_number>",
      "encryptionKeyId": 10
    }
  }
}
{
  "request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL3JlZGlyZWN0IiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiU0FWRURfQ0FSRCIsCiAgICAiYXV0aE1vZGUiOiAiM0RTIiwKICAgICJjYXJkRGV0YWlscyI6IHsKICAgICAgImNhcmRJZCI6ICJDOTAzODg5MzQ5Mjk0MjczNDIzIiwKICAgICAgImVuY3J5cHRlZEN2diI6ICI8ZW5jcnlwdGVkX2N2dl9udW1iZXI+IiwKICAgICAgImVuY3J5cHRpb25LZXlJZCI6IDEwCiAgICB9CiAgfQp9"
}

Request Field Details
For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
paymentInstrument.typeENUMType of instrument with which payment is being initiatedYesValues = SAVED_CARD
authModeSTRINGAuthorisation mode with PG for payment validationYesvalue = 3DS
cardIdSTRINGCardId for the user as sent by phonepe when the card was saved on phonepe platformYes
encryptedCvvSTRINGEncrypted CVV of the card with which payment is being initiated.

Encryption Method: RSA 4096
Yes
encryptionKeyIdLONGKeyId of key which merchant uses to encrypt cvvYes

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "OD620471739210623",
    "instrumentResponse": {
        "type": "SAVED_CARD",
            "redirectInfo": {
                "url": "https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224",
                "method": "GET"
            }
    }
  }
}

Pay Request with Token

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "U4909206497168257",
  "amount": 10000,
  "redirectUrl": "https://webhook.site/redirect-url",
  "redirectMode": "POST",
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "TOKEN",
    "authMode": "3DS",
    "tokenDetails": {
      "encryptedCvv": "<encrypted_cvv_number>",
      "cryptogram": "95031131582962057737",
      "encryptedToken": "SJk7Sazu894+cHsxsTOLML5ZYseMzdQ",
      "encryptionKeyId": 10,
      "expiry": {
        "month": "11",
        "year": "2037"
      },
      "panSuffix": "1212",
      "cardHolderName": "Prashant"
    }
  }
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIlU0OTA5MjA2NDk3MTY4MjU3IiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJQT1NUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlRPS0VOIiwKICAgICJhdXRoTW9kZSI6ICIzRFMiLAogICAgInRva2VuRGV0YWlscyI6IHsKICAgICAgImVuY3J5cHRlZEN2diI6ICI8ZW5jcnlwdGVkX2N2dl9udW1iZXI+IiwKICAgICAgImNyeXB0b2dyYW0iOiAiOTUwMzExMzE1ODI5NjIwNTc3MzciLAogICAgICAiZW5jcnlwdGVkVG9rZW4iOiAiU0prN1NhenU4OTQrY0hzeHNUT0xNTDVaWXNlTXpkUSIsCiAgICAgICJlbmNyeXB0aW9uS2V5SWQiOiAxMCwKICAgICAgImV4cGlyeSI6IHsKICAgICAgICAibW9udGgiOiAiMTEiLAogICAgICAgICJ5ZWFyIjogIjIwMzciCiAgICAgIH0sCiAgICAgICJwYW5TdWZmaXgiOiAiMTIxMiIsCiAgICAgICJjYXJkSG9sZGVyTmFtZSI6ICJQcmFzaGFudCIKICAgIH0KICB9Cn0="
}

Request Field Details

For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
paymentInstrument.typeENUMType of instrument with which payment is being initiatedYesValues = TOKEN
encryptedCvvSTRINGEncrypted CVV of the card with which payment is being initiated.

Encryption Method: RSA 4096
Yes
encryptedTokenSTRINGEncrypted TOKEN number which merchant passes to process card transaction

Encryption Method: RSA 4096
Yes
encryptionKeyIdLONGKeyId of key which merchant uses to encrypt token and cvvYes
expiry.monthSTRINGToken expiry monthYes
expiry.yearSTRINGToken expiry yearYes
cryptogramSTRINGCryptogram which is generated in the get transaction data callYes
panSuffixSTRINGLast four digits of cardNumberYes
cardHolderNameSTRINGCard Holder NameNo
merchantUserIdSTRINGMerchant User Id unique for the customerNo

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T9693997646897938",
        "instrumentResponse": {
        "type": "TOKEN",
            "redirectInfo": {
                "url": "https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224",
                "method": "GET"
            }
        }
  }
}

Pay Request for UPI Collect

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "OD620471739210623",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "callbackUrl": "https://mykewlapp.com/callback",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "UPI_COLLECT",
    "vpa": "[email protected]"
  }
}

🚧

Test VPA

For testing in the UAT environment, kindly use the VPA of the PhonePe PreProd app only.
To setup VPA, refer Creating/Viewing VPA from here
Example: [email protected]

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVVJRDEyMyIsCiAgImFtb3VudCI6IDEwMDAwLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0NPTExFQ1QiLAogICAgInZwYSI6ICJ0ZXN0LXZwYUB5YmwiCiAgfQp9"
}

Request Field Details
For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
typeSTRINGType of instrument with which payment is being initiatedYesvalue = UPI_COLLECT
vpaSTRINGVPA of user initiating payment

Sample Response

{
    "success": true,
    "code": "PAYMENT_INITIATED",
    "message": "Payment initiated",
    "data": {
        "merchantId": "RUMMYLEGENDSUAT",
        "merchantTransactionId": "d852fe13-a25e-4c49-82e1-27aab36b40e1",
        "instrumentResponse": {
            "type": "UPI_COLLECT"
        }
    }
}

Sample Failure Response

{
  "success": false,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

🚧

For UPI Collect, VPA have to be verified.

  • In UPI collect flow, users have to enter a Virtual Payment Address (VPA) to make the payment. The VPA can be verified using VPA Validate API.

  • The Collect Request will be valid for 8mins. Merchants can display the timer on the payment processing page to keep the user aware of the time left to complete the payment.

Pay Request for UPI QR

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "callbackUrl": "https://mykewlapp.com/callback",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "UPI_QR"
  }
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL2NhbGxiYWNrIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlVQSV9RUiIKICB9Cn0="
}

Request Field Details
For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
typeSTRINGType of instrument with which payment is being initiatedYesvalue = UPI_QR

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "OD620471739210623",
    "instrumentResponse": {
      "type": "UPI_QR",
      "qrData": "<Base64 encoded QR image string>",
      "intentUrl": "upi://[email protected]&pn=MERCHANTUAT&am=100.00&mam=100.00&tr=4bf0738a-e686-464f-87f5-b249d1e56c2a&tn=Payment%20for%204bf0738a-e686-464f-87f5-b249d1e56c2a&mc=5311&mode=04&purpose=00&utm_campaign=B2B_PG&utm_medium=JUSPAYUAT&utm_source=4bf0738a-e686-464f-87f5-b249d1e56c2a"
    }
  }
}

🚧

Generating QR Image

In the UPI QR response, either qrData or intentUrl can be converted to the QR Image and shown to the user.

Pay Request for NET BANKING

📘

  • To get the list of NetBanking Banks and it's current availability status, Payment Options API can be used.
  • To fetch the Bank or Default Netbanking Logo, refer here

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "redirectUrl": "https://webhook.site/redirect-url",
    "redirectMode": "POST",
    "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "NET_BANKING",
        "bankId": "SBIN"
  }
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKCSJyZWRpcmVjdE1vZGUiOiAiUE9TVCIsCgkiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIk5FVF9CQU5LSU5HIiwKCQkiYmFua0lkIjogIlNCSU4iCiAgfQp9"
}

Request Field Details

For Common request parameters, refer here

Parameter NameData TypeDescriptionMandatoryComments
typeSTRINGType of instrument with which payment is being initiatedYesvalue = NET_BANKING
bankIdSTRINGA short code to identify the bank selected by userYesExample value = HDFC
Id’s for all banks can be obtained from the Response of Options API > NetBanking > All banks list.

Sample Response

{
    "success": true,
    "code": "PAYMENT_INITIATED",
    "message": "Payment initiated",
    "data":
    {
        "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "MT7850590068188104",
        "transactionId": "T2208051605137945169863",
        "instrumentResponse":
        {
            "type": "NET_BANKING",
            "redirectInfo":
            {
                "url": "https://pg-uat.phonepe.com/pg-transport/v1/redirect/tib?id=670fac79-1ccc-42b4-b0b5-af36c6b6db09",
                "method": "GET"
            }
        }
    }
}

Response Details

Response Headers

Header NameHeader Value
Content-Typeapplication/json

Response Parameters

Parameter NameData TypeDescriptionComments
successBOOLEANSuccess/failure of request processing
codeSTRINGResponse code explaining reason for status.

For status SUCCESS, only one possible response code is present
- PAYMENT_INITIATED
For status FAILURE, following response codes are possible:
● BAD_REQUEST
● AUTHORIZATION_FAILED
● PAYMENT_ERROR
● INTERNAL_SERVER_ERROR
messageSTRINGMessage giving more information about the code.
merchantIdSTRINGMerchant id
merchantTransactionIdSTRINGTransaction id generated by merchant
transactionIdSTRINGTransaction id generated by PhonePeThis may not always be available in response of a pay call but will always be available in callback or status call after transaction completion
redirectInfoSTRINGPayload for redirecting user to bank page for authentication
urlSTRINGUrl on which user needs to be redirected for authentication
methodSTRINGhttp method for loading redirect url
headersMap<String, String>Request headers to be passed while loading redirect url
dataMap<String, String>Form data to be submitted to redirect url page

Error Codes

CodeDescription
PAYMENT_INITIATEDPayment is initiated successfully
PAYMENT_ERRORPayment initiation has failed
INTERNAL_SERVER_ERRORSomething went wrong
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect

Common errors related to X-Verify header

ScenarioError CodeResponse Body
X-Verify is not passed in request headers or passed in different format than expected400 (Bad Request)
Incorrect X-Verify header passed in request401{"success":false,"code":"401"}
Language
Click Try It! to start a request and see the response here!