post https://api-preprod.phonepe.com/apis/merchant-simulator/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 38 characters. | Yes | |
amount | LONG | Transaction amount in Paise | Yes | |
merchantUserId | STRING | Unique UserID of the users generated by the merchant.Note: Avoid passing email/mobile number. | 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 | GET / POST modes for redirectUrl | Yes | Possible values: ● GET ● 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 | No |
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 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 |
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 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 Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
type | STRING | Type of instrument with which payment is being initiated | Yes | value = UPI_COLLECT |
vpa | STRING | VPA 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 Name | Data Type | Description | Mandatory | Comments |
|---|---|---|---|---|
type | STRING | Type of instrument with which payment is being initiated | Yes | value = 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 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 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": "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 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": "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 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": "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 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 | Cryptogram which is generated in the get transaction data call | 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
- 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 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"} |