post https://api-preprod.phonepe.com/apis/pg-sandbox/pg/v1/pay
This API initiates a payment transaction.
Quick Links
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 PhonePeNote: merchantId length will be less than 38 characters. | Yes | |
merchantTransactionId | STRING | Unique TransactionID generated by the merchant to track request to PhonePeNote: - merchantTransactionId length should be less than 36 characters. - No Special characters allowed except underscore "_" and hyphen "-" | 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: - merchantUserId length should be less than 36 characters - No Special characters allowed except underscore "_" and hyphen "-" | Conditional | Mandatory if paymentInstrument.type is: ● PAY_PAGE ● CARD ● SAVED_CARD Optional for if paymentInstrument.type is: ● UPI_INTENT ● UPI_COLLECT ● UPI_QR ● TOKEN ● NET_BANKING |
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, refer here
| 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: Android package name (For example: ● com.phonepe.app for PHONEPE ● net.one97.paytm for PAYTM) |
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, refer here
| 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, refer here
| 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, refer here
| 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
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": 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"
}
}
}
}
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":"ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICAgImFtb3VudCI6IDEwMDAwLAogICAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAgICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiLAogICAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAgICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICAgICAidHlwZSI6ICJDQVJEIiwKICAgICAgICAiYXV0aE1vZGUiOiAiM0RTIiwKICAgICAgICAic2F2ZUNhcmQiOiB0cnVlLAogICAgICAgICJjYXJkRGV0YWlscyI6IHsKICAgICAgICAgICAgImVuY3J5cHRlZENhcmROdW1iZXIiOiAiPGVuY3J5cHRlZF9jYXJkX251bWJlcj4iLAogICAgICAgICAgICAiZW5jcnlwdGlvbktleUlkIjogMTAsCiAgICAgICAgICAgICJjYXJkSG9sZGVyTmFtZSI6ICJDYXJsb3MgU2FpbnoiLAogICAgICAgICAgICAiZXhwaXJ5IjogewogICAgICAgICAgICAgICAgIm1vbnRoIjoiMDYiLAogICAgICAgICAgICAgICAgInllYXIiOiIyMDI1IgogICAgICAgICAgICB9LAogICAgICAgICAgICAiZW5jcnlwdGVkQ3Z2IjogIjxlbmNyeXB0ZWRfY3Z2X251bWJlcj4iLAogICAgICAgICAgICAiYmlsbGluZ0FkZHJlc3MiOiB7CiAgICAgICAgICAgICAgICAibGluZTEiOiAiVW5pdCBOby4wMDEsIEdyb3VuZCBGbG9vciwgQm9zdG9uIEhvdXNlIiwKICAgICAgICAgICAgICAgICJsaW5lMiI6ICJTdXJlbiBSb2FkLCBBbmRoZXJpKEVhc3QpIiwKICAgICAgICAgICAgICAgICJjaXR5IjogIk11bWJhaSIsCiAgICAgICAgICAgICAgICAic3RhdGUiOiAiTWFoYXJhc2h0cmEiLAogICAgICAgICAgICAgICAgInppcCI6ICI0MDAwOTMiLAogICAgICAgICAgICAgICAgImNvdW50cnkiOiAiSW5kaWEiCiAgICAgICAgICAgIH0KICAgICAgICB9CiAgICB9Cn0="
}
Request Field Details
For Common request parameters, refer here
| 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 | true if merchant wants to save token on phonepe platform | 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"
}
}
}
}
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 with Card Id
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "OD620471739210623",
"merchantUserId": "MU933037302229373",
"amount": 10000,
"redirectUrl": "https://mykewlapp.com/redirect",
"redirectMode": "REDIRECT",
"callbackUrl": "https://mykewlapp.com/callback",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "SAVED_CARD",
"authMode": "3DS",
"cardDetails": {
"cardId": "C903889349294273423",
"encryptedCvv": "<encrypted_cvv_number>",
"encryptionKeyId": 10
}
}
}
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":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL3JlZGlyZWN0IiwKICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL2NhbGxiYWNrIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlNBVkVEX0NBUkQiLAogICAgImF1dGhNb2RlIjogIjNEUyIsCiAgICAiY2FyZERldGFpbHMiOiB7CiAgICAgICJjYXJkSWQiOiAiQzkwMzg4OTM0OTI5NDI3MzQyMyIsCiAgICAgICJlbmNyeXB0ZWRDdnYiOiAiPGVuY3J5cHRlZF9jdnZfbnVtYmVyPiIsCiAgICAgICJlbmNyeXB0aW9uS2V5SWQiOiAxMAogICAgfQogIH0KfQ=="
}
Request Field Details
For Common request parameters, refer here
| Parameter Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
paymentInstrument.type | ENUM | Type of instrument with which payment is being initiated | Yes | Values = SAVED_CARD |
authMode | STRING | Authorisation mode with PG for payment validation | Yes | value = 3DS |
cardId | STRING | CardId for the user as sent by phonepe when the card was saved on phonepe platform | Yes | |
encryptedCvv | STRING | Encrypted CVV of the card with which payment is being initiated. Encryption Method: RSA 4096 | Yes | |
encryptionKeyId | LONG | KeyId of key which merchant uses to encrypt cvv | Yes |
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": "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, refer here
| 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": "SBIN"
}
}
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": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIk5FVF9CQU5LSU5HIiwKICAgICJiYW5rSWQiOiAiU0JJTiIKICB9Cn0="
}
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": "SBIN",
"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": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlJFRElSRUNUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIk5FVF9CQU5LSU5HIiwKICAgICJiYW5rSWQiOiAiU0JJTiIsCiAgICAiYWNjb3VudENvbnN0cmFpbnRzIjogWyAvL09wdGlvbmFsLiBSZXF1aXJlZCBvbmx5IGZvciBUUFYgRmxvdy4KICAgICAgewogICAgICAgICJhY2NvdW50TnVtYmVyIjogIjQyMDIwMDAwMTg5MiIsCiAgICAgICAgImlmc2MiOiAiSUNJQzAwMDAwNDEiCiAgICAgIH0KICAgIF0KICB9Cn0="
}
Request Field Details
For Common request parameters, refer here
| 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 - PAYMENT_INITIATED For status FAILURE, following response codes are possible: ● BAD_REQUEST ● AUTHORIZATION_FAILED ● PAYMENT_ERROR ● INTERNAL_SERVER_ERROR | |
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"} |