SearchSequence
- Pay Request For UPI Open Intent Flow
- Pay Request for UPI Collect
- Pay Request for UPI QR
- Pay Request For New Card Flow
- Pay Request with Token
- Pay Request for NET BANKING
The API endpoint remains the same for all the payment instruments.
Request Headers
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload + “/pg/v1/pay” + salt key) + ### + salt index |
Request Parameters – Common Parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
merchantId | STRING | Unique MerchantID assigned to the merchant by PhonePe
Note: merchantId length will be less than 38 characters. | Yes | |
merchantTransactionId | STRING | Unique TransactionID generated by the merchant to track request to PhonePe
Note: | Yes | |
amount | LONG | Transaction amount in Paise. Note: Amount should be greater than 100 (in Paise) | Yes | |
merchantUserId | STRING | Unique UserID of the users generated by the merchant.
Note: | Conditional | Mandatory if paymentInstrument.type is: ● PAY_PAGE ● CARD ● SAVED_CARD Optional for if paymentInstrument.type is: |
redirectUrl | STRING | The url where the user will be redirected after transaction completion. | Yes | |
redirectMode | ENUM | redirectMode should be: ● REDIRECT ● POST (Should be used only if the Merchant’s URL can handle the POST method) | Yes | Possible values: ● REDIRECT ● POST |
callbackUrl | STRING | The url where server to server callback will be posted. Always POST | Yes | This 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. |
paymentInstrument | OBJECT | Payment details | Yes | |
paymentInstrument.type | ENUM | Payment instrument type | Yes | Possible values: ● PAY_PAGE ● CARD ● UPI_INTENT ● SAVED_CARD ● TOKEN ● UPI_COLLECT ● UPI_QR ● NET_BANKING |
mobileNumber | STRING | Mobile number of the user Note: There should not be any space. | No |
Pay Request For UPI Open Intent Flow
- For TPV Flow (UPI – Intent), accountConstraints should be passed within the paymentInstrument and multiple Account Details can be passed.
Merchants shoud display the Custom UI containing the list of UPI apps present on the user’s device on the checkout page.
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",
"merchantCallBackScheme": "iOSIntentIntegration"
},
"paymentInstrument": {
"type": "UPI_INTENT",
"targetApp": "PHONEPE"
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJBTkRST0lEIgogIH0sCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0lOVEVOVCIsCiAgICAidGFyZ2V0QXBwIjogImNvbS5waG9uZXBlLmFwcCIKICB9Cn0="
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKIAkibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJJT1MiLAogICAgIm1lcmNoYW50Q2FsbEJhY2tTY2hlbWUiOiAiaU9TSW50ZW50SW50ZWdyYXRpb24iCiAgfSwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJVUElfSU5URU5UIiwKICAgICJ0YXJnZXRBcHAiOiAiUEhPTkVQRSIKICB9Cn0="
}
Sample Request with TPV
{
"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",
"accountConstraints": [{ //Optional. Required only for TPV Flow.
"accountNumber": "420200001892",
"ifsc": "ICIC0000041"
}]
}
}
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "MU933037302229373",
"amount": 10000,
"callbackUrl": "https://webhook.site/callback-url",
"mobileNumber": "9999999999",
"deviceContext": {
"deviceOS": "IOS",
"merchantCallBackScheme": "iOSIntentIntegration"
},
"paymentInstrument": {
"type": "UPI_INTENT",
"targetApp": "PHONEPE",
"accountConstraints": [{ //Optional. Required only for TPV Flow.
"accountNumber": "420200001892",
"ifsc": "ICIC0000041"
}]
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJBTkRST0lEIgogIH0sCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0lOVEVOVCIsCiAgICAidGFyZ2V0QXBwIjogImNvbS5waG9uZXBlLmFwcCIsCiAgICAiYWNjb3VudENvbnN0cmFpbnRzIjogW3sKICAgIAkiYWNjb3VudE51bWJlciI6ICI0MjAyMDAwMDE4OTIiLAogICAgCSJpZnNjIjogIklDSUMwMDAwMDQxIgogICAgfV0KICB9Cn0="
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJJT1MiLAogICAgIm1lcmNoYW50Q2FsbEJhY2tTY2hlbWUiOiAiaU9TSW50ZW50SW50ZWdyYXRpb24iCiAgfSwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJVUElfSU5URU5UIiwKICAgICJ0YXJnZXRBcHAiOiAiUEhPTkVQRSIsCiAgICAiYWNjb3VudENvbnN0cmFpbnRzIjogW3sKICAgICAgImFjY291bnROdW1iZXIiOiAiNDIwMjAwMDAxODkyIiwKICAgICAgImlmc2MiOiAiSUNJQzAwMDAwNDEiCiAgICB9XQogIH0KfQ=="
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
paymentInstrument.type | STRING | Type of instrument with which payment is being initiated | Yes | value = UPI_INTENT |
paymentInstrument.targetApp | ENUM | Target 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. | Yes | Possible values for iOS: ● PHONEPE ● GPAY ● PAYTM
Possible values for Android: |
deviceContext.deviceOS | STRING | Device Operating System | ENUM | Possible values for iOS: ● ANDROID ● IOS |
paymentInstrument.accountConstraints | OBJECT | To be passed only for TPV Flow | Optional | To be passed ● accountNumber ● ifsc |
Sample Response
{
"success": true,
"code": "PAYMENT_INITIATED",
"message": "Payment Initiated",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"instrumentResponse": {
"type": "UPI_INTENT",
"intentUrl": "upi://pay?pa=MERCHANTUAT@ybl&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://pay?pa=MERCHANTUAT@ybl&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 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": "test-vpa@ybl"
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVVJRDEyMyIsCiAgImFtb3VudCI6IDEwMDAwLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0NPTExFQ1QiLAogICAgInZwYSI6ICJ0ZXN0LXZwYUB5YmwiCiAgfQp9"
}
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: 9999999999@ybl
Sample Request with TPV
- For TPV Flow (UPI – Collect), accountConstraints should be passed within the paymentInstrument
- Merchant should pass only one bank account as only one vpa will be tied to one account.
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "OD620471739210623",
"merchantUserId": "MUID123",
"amount": 10000,
"callbackUrl": "https://mykewlapp.com/callback",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "UPI_COLLECT",
"vpa": "test-vpa@ybl",
"accountConstraints": [{ //Optional. Required only for TPV Flow.
"accountNumber": "420200001892",
"ifsc": "ICIC0000041"
}]
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVVJRDEyMyIsCiAgImFtb3VudCI6IDEwMDAwLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0NPTExFQ1QiLAogICAgInZwYSI6ICJ0ZXN0LXZwYUB5YmwiLAogICAgImFjY291bnRDb25zdHJhaW50cyI6IFt7CiAgICAgICJhY2NvdW50TnVtYmVyIjogIjQyMDIwMDAwMTg5MiIsCiAgICAgICJpZnNjIjogIklDSUMwMDAwMDQxIgogICAgfV0KICB9Cn0="
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
type | STRING | Type of instrument with which payment is being initiated | Yes | value = UPI_COLLECT |
Yes | STRING | VPA of user initiating payment | Yes | |
paymentInstrument.accountConstraints | OBJECT | To be passed only for TPV Flow | Optional | To be passed ● accountNumber ● ifsc |
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"
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL2NhbGxiYWNrIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlVQSV9RUiIKICB9Cn0="
}
Sample Request with TPV
- For TPV Flow (UPI – QR), accountConstraints should be passed within the paymentInstrument and multiple Account Details can be passed.
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "MUID123",
"amount": 10000,
"callbackUrl": "https://mykewlapp.com/callback",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "UPI_QR",
"accountConstraints": [{ //Optional. Required only for TPV Flow.
"accountNumber": "420200001892",
"ifsc": "ICIC0000041"
}]
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL2NhbGxiYWNrIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlVQSV9RUiIsCiAgICAiYWNjb3VudENvbnN0cmFpbnRzIjogW3sKICAgICAgImFjY291bnROdW1iZXIiOiAiNDIwMjAwMDAxODkyIiwKICAgICAgImlmc2MiOiAiSUNJQzAwMDAwNDEiCiAgICB9XQogIH0KfQ=="
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
type | STRING | Type of instrument with which payment is being initiated | Yes | value = UPI_QR |
paymentInstrument.accountConstraints | OBJECT | To be passed only for TPV Flow | Optional | To be passed ● accountNumber ● ifsc |
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://pay?pa=MERCHANTUAT@ybl&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 Web Flow
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "MUID123",
"amount": 10000,
"redirectUrl": "https://webhook.site/redirect-url",
"redirectMode": "REDIRECT",
"callbackUrl": "https://webhook.site/callback-url",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "PAY_PAGE"
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlBBWV9QQUdFIgogIH0KfQ=="
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
paymentInstrument.type | ENUM | Type of instrument with which payment is being initiated | Yes | Values = 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
Important Note
- Merchant should be PCI/DSS certified to integrate the Custom Card Flow
- The Card Number and CVV should be Encrypted using Method: RSA 4096
- The encryptionKey and encryptionKeyId are shared on the MID Level
- If there are multiple MIDs, then the encryptionKey and encryptionKeyId will be different for different MID and hence don’t hardcode the value.
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "OD620471739210623",
"merchantUserId": "MU933037302229373",
"amount": 10000,
"redirectUrl": "https://webhook.site/redirect-url",
"redirectMode": "REDIRECT",
"callbackUrl": "https://webhook.site/callback-url",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "CARD",
"authMode": "3DS",
"saveCard": false,
"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"
}
}
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request":"ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICAgImFtb3VudCI6IDEwMDAwLAogICAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAgICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiLAogICAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAgICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICAgICAidHlwZSI6ICJDQVJEIiwKICAgICAgICAiYXV0aE1vZGUiOiAiM0RTIiwKICAgICAgICAic2F2ZUNhcmQiOiBmYWxzZSwKICAgICAgICAiY2FyZERldGFpbHMiOiB7CiAgICAgICAgICAgICJlbmNyeXB0ZWRDYXJkTnVtYmVyIjogIjxlbmNyeXB0ZWRfY2FyZF9udW1iZXI+IiwKICAgICAgICAgICAgImVuY3J5cHRpb25LZXlJZCI6IDEwLAogICAgICAgICAgICAiY2FyZEhvbGRlck5hbWUiOiAiQ2FybG9zIFNhaW56IiwKICAgICAgICAgICAgImV4cGlyeSI6IHsKICAgICAgICAgICAgICAgICJtb250aCI6IjA2IiwKICAgICAgICAgICAgICAgICJ5ZWFyIjoiMjAyNSIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgImVuY3J5cHRlZEN2diI6ICI8ZW5jcnlwdGVkX2N2dl9udW1iZXI+IiwKICAgICAgICAgICAgImJpbGxpbmdBZGRyZXNzIjogewogICAgICAgICAgICAgICAgImxpbmUxIjogIlVuaXQgTm8uMDAxLCBHcm91bmQgRmxvb3IsIEJvc3RvbiBIb3VzZSIsCiAgICAgICAgICAgICAgICAibGluZTIiOiAiU3VyZW4gUm9hZCwgQW5kaGVyaShFYXN0KSIsCiAgICAgICAgICAgICAgICAiY2l0eSI6ICJNdW1iYWkiLAogICAgICAgICAgICAgICAgInN0YXRlIjogIk1haGFyYXNodHJhIiwKICAgICAgICAgICAgICAgICJ6aXAiOiAiNDAwMDkzIiwKICAgICAgICAgICAgICAgICJjb3VudHJ5IjogIkluZGlhIgogICAgICAgICAgICB9CiAgICAgICAgfQogICAgfQp9"
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
paymentInstrument.type | ENUM | Type of instrument with which payment is being initiated | Yes | Values = CARD |
authMode | STRING | Authorisation mode with PG for payment validation | Yes | |
saveCard | BOOLEAN | false for the Guest Card Flow | Yes | |
encryptionKeyId | LONG | KeyId of key which merchant uses to encrypt card number & cvv | Yes | |
encryptedCardNumber | STRING | Encrypted 16-Digit Card Number entered by the user. Encryption Method: RSA 4096 | Yes | |
cardHolderName | STRING | Name of holder printed on card | Yes | |
expiry.month | STRING | Card Expiry Month | Yes | |
expiry.year | STRING | Card Expiry Year | Yes | |
encryptedCvv | STRING | Encrypted CVV of the card with which payment is being initiated.
Encryption Method: RSA 4096 | Yes | |
billingAddress | OBJECT | Billing address details to be passed to the PG | No |
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"
}
}
}
}
Pay Request with Token
Important Note
- Merchant should be PCI/DSS certified to integrate the Custom Card Flow
- The Token and CVV should be Encrypted using Method: RSA 4096
- The encryptionKey and encryptionKeyId are shared on the MID Level
- If there are multiple MIDs, then the encryptionKey and encryptionKeyId will be different for different MID and hence don’t hardcode the value.
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "U4909206497168257",
"amount": 10000,
"redirectUrl": "https://webhook.site/redirect-url",
"redirectMode": "REDIRECT",
"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"
}
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIlU0OTA5MjA2NDk3MTY4MjU3IiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJSRURJUkVDVCIsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJUT0tFTiIsCiAgICAiYXV0aE1vZGUiOiAiM0RTIiwKICAgICJ0b2tlbkRldGFpbHMiOiB7CiAgICAgICJlbmNyeXB0ZWRDdnYiOiAiPGVuY3J5cHRlZF9jdnZfbnVtYmVyPiIsCiAgICAgICJjcnlwdG9ncmFtIjogIjk1MDMxMTMxNTgyOTYyMDU3NzM3IiwKICAgICAgImVuY3J5cHRlZFRva2VuIjogIlNKazdTYXp1ODk0K2NIc3hzVE9MTUw1WllzZU16ZFEiLAogICAgICAiZW5jcnlwdGlvbktleUlkIjogMTAsCiAgICAgICJleHBpcnkiOiB7CiAgICAgICAgIm1vbnRoIjogIjExIiwKICAgICAgICAieWVhciI6ICIyMDM3IgogICAgICB9LAogICAgICAicGFuU3VmZml4IjogIjEyMTIiLAogICAgICAiY2FyZEhvbGRlck5hbWUiOiAiUHJhc2hhbnQiCiAgICB9CiAgfQp9"
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
paymentInstrument.type | ENUM | Type of instrument with which payment is being initiated | Yes | Values = TOKEN |
encryptedCvv | STRING | Encrypted CVV of the card with which payment is being initiated.
Encryption Method: RSA 4096 | Yes | |
encryptedToken | STRING | Encrypted TOKEN number which merchant passes to process card transaction
Encryption Method: RSA 4096 | Yes | |
encryptionKeyId | LONG | KeyId of key which merchant uses to encrypt token and cvv | Yes | |
expiry.month | STRING | Token expiry month | Yes | |
expiry.year | STRING | Token expiry year | Yes | |
cryptogram | STRING | The cryptogram fetched from the gateway where the card was tokenized. | Yes | |
panSuffix | STRING | Last four digits of cardNumber | Yes | |
cardHolderName | STRING | Card Holder Name | No | |
merchantUserId | STRING | Merchant User Id unique for the customer | No |
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 NET BANKING
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "MUID123",
"amount": 10000,
"redirectUrl": "https://webhook.site/redirect-url",
"redirectMode": "REDIRECT",
"callbackUrl": "https://webhook.site/callback-url",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "NET_BANKING",
"bankId": "HDFC"
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIk5FVF9CQU5LSU5HIiwKICAgICJiYW5rSWQiOiAiSERGQyIKICB9Cn0="
}
Sample Request with TPV
- 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
- For TPV Flow (NetBanking), accountConstraints should be passed in the paymentInstrument and only one Account Detail should be passed.
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "MUID123",
"amount": 10000,
"redirectUrl": "https://webhook.site/redirect-url",
"redirectMode": "REDIRECT",
"callbackUrl": "https://webhook.site/callback-url",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "NET_BANKING",
"bankId": "ICIC",
"accountConstraints": [ //Optional. Required only for TPV Flow.
{
"accountNumber": "420200001892",
"ifsc": "ICIC0000041"
}
]
}
}
Convert the JSON Payload to Base64 Encoded Payload
The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIk5FVF9CQU5LSU5HIiwKICAgICJiYW5rSWQiOiAiSUNJQyIsCiAgICAiYWNjb3VudENvbnN0cmFpbnRzIjogWwogICAgICB7CiAgICAgICAgImFjY291bnROdW1iZXIiOiAiNDIwMjAwMDAxODkyIiwKICAgICAgICAiaWZzYyI6ICJJQ0lDMDAwMDA0MSIKICAgICAgfQogICAgXQogIH0KfQ=="
}
Request Field Details
For Common request parameters
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
type | STRING | Type of instrument with which payment is being initiated | Yes | value = NET_BANKING |
bankId | STRING | A short code to identify the bank selected by user | Yes | Example 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 Name | Header Value |
|---|---|
Content-Type | application/json |
Response Parameters
| Parameter Name | Data Type | Description | Comments |
|---|---|---|---|
success | BOOLEAN | Success/failure of request processing | |
code | STRING | Response code explaining reason for status.
For status SUCCESS, only one possible response code is present | |
message | STRING | Message giving more information about the code. | |
merchantId | STRING | Merchant id | |
merchantTransactionId | STRING | Transaction id generated by merchant | |
transactionId | STRING | Transaction id generated by PhonePe | This may not always be available in response of a pay call but will always be available in callback or status call after transaction completion |
redirectInfo | STRING | Payload for redirecting user to bank page for authentication | |
url | STRING | Url on which user needs to be redirected for authentication | |
method | STRING | http method for loading redirect url | |
headers | Map<String, String> | Request headers to be passed while loading redirect url | |
data | Map<String, String> | Form data to be submitted to redirect url page |
Error Codes
| Code | Description |
|---|---|
| PAYMENT_INITIATED | Payment is initiated successfully |
| PAYMENT_ERROR | Payment initiation has failed |
| INTERNAL_SERVER_ERROR | Something went wrong |
| BAD_REQUEST | Invalid request |
| AUTHORIZATION_FAILED | X-VERIFY header is incorrect |
Common errors related to X-Verify header
| Scenario | Error Code | Response Body |
|---|---|---|
| X-Verify is not passed in request headers or passed in different format than expected | 400 (Bad Request) | |
| Incorrect X-Verify header passed in request | 401 | {“success”:false,”code”:”401″} |
{“method”:”post”,”url”:”/pg/v1/pay”,”auth”:”required”,”results”:{“codes”:[{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_INITIATED\”,\n \”message\”: \”Payment Initiated\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n \”merchantTransactionId\”: \”OD620471739210623\”,\n\t\t\”instrumentResponse\”: {\n\t\t\t\”type\”: \”UPI_INTENT\”,\n\t\t\t\”intentUrl\”: \”upi://pay?pa=MERCHANTUAT@ybl&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\”\n \t}\t\n \t}\n}”,”language”:”json”,”status”:200,”name”:”Sample Response – UPI Open Intent”},{“code”:”{\n \”success\”: false,\n \”code\”: \”INTERNAL_SERVER_ERROR\”,\n \”message\”: \”There is an error trying to process your transaction at the moment. Please try again in a while.\”\n}\n”,”language”:”json”,”status”:500},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_INITIATED\”,\n \”message\”: \”Payment initiated\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n \”merchantTransactionId\”: \”MT7850590068188104\”,\n \”transactionId\”: \”T2204071334465821320730\”,\n \”instrumentResponse\”: {\n \”type\”: \”CARD\”,\n \”redirectInfo\”: {\n \”url\”: \”https://pg-uat.phonepe.com/pg-transport/v1/redirect/dummy?id=d085d94a-8d58-4043-a73f-31e9de41af46\”,\n \”method\”: \”GET\”\n }\n }\n }\n}”,”language”:”json”,”status”:200,”name”:”Sample Response – With Card Number”},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_INITIATED\”,\n \”message\”: \”Payment Initiated\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n \”merchantTransactionId\”: \”MT7850590068188104\”,\n \”transactionId\”: \”OD620471739210623\”,\n \”instrumentResponse\”: {\n \t\t\”type\”: \”SAVED_CARD\”,\n\t\t\t\”redirectInfo\”: {\n\t\t\t\t\”url\”: \”https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224\”,\n\t\t\t\t\”method\”: \”GET\”\n\t\t\t}\n }\n }\n}”,”language”:”json”,”name”:”Sample Response – With Card Id”,”status”:200},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_INITIATED\”,\n \”message\”: \”Payment initiated\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n\t\t\”merchantTransactionId\”: \”MT7850590068188104\”,\n \”transactionId\”: \”T9693997646897938\”,\n\t\t\”instrumentResponse\”: {\n \t\t\”type\”: \”TOKEN\”,\n\t\t\t\”redirectInfo\”: {\n\t\t\t\t\”url\”: \”https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224\”,\n\t\t\t\t\”method\”: \”GET\”\n\t\t\t}\n\t\t}\n }\n}”,”language”:”json”,”name”:”Sample Response – With Token”,”status”:200},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_INITIATED\”,\n \”message\”: \”Payment initiated\”,\n \”data\”: {\n \”merchantId\”: \”RUMMYLEGENDSUAT\”,\n \”merchantTransactionId\”: \”d852fe13-a25e-4c49-82e1-27aab36b40e1\”,\n \”instrumentResponse\”: {\n \”type\”: \”UPI_COLLECT\”\n }\n }\n}”,”language”:”json”,”name”:”Sample Response – With UPI Collect”,”status”:200},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_INITIATED\”,\n \”message\”: \”Payment Initiated\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n \”merchantTransactionId\”: \”OD620471739210623\”,\n \”instrumentResponse\”: {\n \”type\”: \”UPI_QR\”,\n \”qrData\”: \”\”,\n \”intentUrl\”: \”upi://pay?pa=MERCHANTUAT@ybl&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\”\n }\n }\n}”,”language”:”json”,”name”:”Sample Response – With UPI QR”,”status”:200}]},”params”:[{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”62035ef5beaf290023225a37″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/pg/v1/pay\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”62035ef5beaf290023225a36″},{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”62fcac920181e502a9524a83″}],”examples”:{“codes”:[]},”apiSetting”:”63bb01b11abcf7046d98754c”}
https://api-preprod.phonepe.com/apis/pg-sandbox