This API initiates a payment transaction.
Request Headers
Header Name | Header Value |
---|---|
| application/json |
| SHA256(base64 encoded payload + "/pg/v1/pay" + |
Request Parameters - Common Parameters
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Unique |
| |
|
| Unique |
| |
|
| Transaction amount in Paise |
| |
|
| Unique
|
| |
|
| The url where the user will be redirected after transaction completion. |
| |
|
| GET / POST modes for redirectUrl |
| Possible values: |
|
| The url where server to server callback will be posted. Always POST |
| 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. |
|
| Customer details |
| |
|
| Product information |
| |
|
| Payment details |
| |
|
| Payment instrument type |
| Possible values: |
|
| Device Context Details |
| |
|
| Device Operating System |
| Possible values: |
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
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| 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": 69213,
"cardHolderName": "Carlos Sainz",
"expiry": {
"month":"06",
"year":"2025"
},
"cvv": "420",
"billingAddress": {
"line1": "Unit No.001, Ground Floor, Boston House",
"line2": "Suren Road, Andheri(East)",
"city": "Mumbai",
"state": "Maharashtra",
"zip": "400093",
"country": "India"
}
}
}
}
{
"request":"ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICAgImFtb3VudCI6IDEwMDAwLAogICAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgICAgICJ0eXBlIjogIkNBUkQiLAogICAgICAgICJhdXRoTW9kZSI6ICIzRFMiLAogICAgICAgICJzYXZlQ2FyZCI6IHRydWUsCiAgICAgICAgImNhcmREZXRhaWxzIjogewogICAgICAgICAgICAiZW5jcnlwdGVkQ2FyZE51bWJlciI6ICI8ZW5jcnlwdGVkX2NhcmRfbnVtYmVyPiIsCiAgICAgICAgICAgICJlbmNyeXB0aW9uS2V5SWQiOiA2OTIxMywKICAgICAgICAgICAgImNhcmRIb2xkZXJOYW1lIjogIkNhcmxvcyBTYWlueiIsCiAgICAgICAgICAgICJleHBpcnkiOiB7CiAgICAgICAgICAgICAgICAibW9udGgiOiIwNiIsCiAgICAgICAgICAgICAgICAieWVhciI6IjIwMjUiCiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJjdnYiOiAiNDIwIiwKICAgICAgICAgICAgImJpbGxpbmdBZGRyZXNzIjogewogICAgICAgICAgICAgICAgImxpbmUxIjogIlVuaXQgTm8uMDAxLCBHcm91bmQgRmxvb3IsIEJvc3RvbiBIb3VzZSIsCiAgICAgICAgICAgICAgICAibGluZTIiOiAiU3VyZW4gUm9hZCwgQW5kaGVyaShFYXN0KSIsCiAgICAgICAgICAgICAgICAiY2l0eSI6ICJNdW1iYWkiLAogICAgICAgICAgICAgICAgInN0YXRlIjogIk1haGFyYXNodHJhIiwKICAgICAgICAgICAgICAgICJ6aXAiOiAiNDAwMDkzIiwKICAgICAgICAgICAgICAgICJjb3VudHJ5IjogIkluZGlhIgogICAgICAgICAgICB9CiAgICAgICAgfQogICAgfQp9"
}
Request Field Details
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| Values = CARD |
|
| Authorisation mode with PG for payment validation |
| |
|
| true if merchant wants to save token on phonepe platform |
| |
|
| KeyId of key which merchant uses to encrypt card number |
| |
|
| Card number of user encrypted using RSA 4096 with merchant key |
| |
|
| Name of holder printed on card |
| |
|
| Card Expiry Month |
| |
|
| Card Expiry Year |
| |
|
| CVV of the card with which payment is being initiated |
| |
|
| Billing address details to be passed to the PG |
|
Sample Response
{
"success": true,
"code": "PAYMENT_INITIATED",
"message": "Payment initiated",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2204071334465821320730",
"instrumentResponse": {
"type": "CARD",
"redirectInfo": {
"url": "https://pg-uat.phonepe.com/pg-transport/v1/redirect/dummy?id=d085d94a-8d58-4043-a73f-31e9de41af46",
"method": "GET"
}
}
}
}
Sample S2S Callback after Card Tokenization is Success
{
"success": true,
"code": "TOKENIZATION_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"state": "COMPLETED",
"responseCode": "TOKENIZATION_SUCCESS",
"cardId": "C34081038691063664100",
"cardMetaData": {
"cardType": "CREDIT_CARD",
"cardIssuer": "VISA",
"bankCode": "ICICI",
"cardSuffix": "5544",
"expiry": {
"month": "12",
"year": "2030"
}
},
"tokenMetaData": {
"panReferenceNumber": "qzyezl9ocsw42m3tckli",
"tokenBin": "456234",
"expiry": {
"month": "12",
"year": "2030"
},
"tokenState": "ACTIVE"
}
}
}
Sample S2S Callback after Card Tokenization is Failed
{
"success": false,
"code": "TOKENIZATION_ERROR",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"state": "FAILED",
"responseCode": "AUTH_TRANSACTION_FAILED"
}
}
Pay Request For UPI Open Intent Flow
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"merchantUserId": "MU933037302229373",
"amount": 10000,
"callbackUrl": "https://webhook.site/callback-url",
"mobileNumber": "9999999999",
"deviceContext": {
"deviceOS": "ANDROID"
},
"paymentInstrument": {
"type": "UPI_INTENT"
}
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKIAkibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJQT1NUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgImRldmljZU9TIjogIkFORFJPSUQiCiAgfSwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJVUElfSU5URU5UIgogIH0KfQ=="
}
Request Field Details
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| value = UPI_INTENT |
|
| Target app for intent. |
| Possible values: |
Sample Response
{
"success": true,
"code": "PAYMENT_INITIATED",
"message": "Payment Initiated",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "OD620471739210623",
"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"
}
}
}
Sample Failure Response
{
"success": false,
"code": "INTERNAL_SERVER_ERROR",
"message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}
Pay Request with Card Id
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "OD620471739210623",
"merchantUserId": "MU933037302229373",
"amount": 10000,
"redirectUrl": "https://mykewlapp.com/redirect",
"redirectMode": "POST",
"callbackUrl": "https://mykewlapp.com/callback",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "SAVED_CARD",
"authMode": "3DS",
"cardDetails": {
"cardId": "C903889349294273423",
"cvv": "223"
}
}
}
{
"request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL3JlZGlyZWN0IiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiU0FWRURfQ0FSRCIsCiAgICAiYXV0aE1vZGUiOiAiM0RTIiwKICAgICJjYXJkRGV0YWlscyI6IHsKICAgICAgImNhcmRJZCI6ICJDOTAzODg5MzQ5Mjk0MjczNDIzIiwKICAgICAgImN2diI6ICIyMjMiCiAgICB9CiAgfQp9"
}
Request Field Details
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| Values = SAVED_CARD |
|
| Authorisation mode with PG for payment validation |
| value = 3DS |
|
| CardId for the user as sent by phonepe when the card was saved on phonepe platform |
| |
|
| CVV of the card with which payment is being initiated |
|
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": "OD620471739210623",
"amount": 10000,
"redirectUrl": "https://mykewlapp.com/redirect",
"redirectMode": "POST",
"callbackUrl": "https://mykewlapp.com/callback",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "TOKEN",
"authMode": "3DS",
"tokenDetails": {
"tokenInfo": {
"encryptedToken": "Oux+POgtcxarT8pQ8hZzx7tzGeYDdnpTQCpdtYh+XYI=",
"encryptionKeyId": 49574,
"expiry": {
"month": "12",
"year": "2030"
}
},
"cvv": "223",
"cryptogramInfo": {
"cryptogram": "AgAAAAoASLWQsd8AAAA5gx4AAAA=",
"eci": "07",
"atc": "72"
}
}
}
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vbXlrZXdsYXBwLmNvbS9yZWRpcmVjdCIsCiAgInJlZGlyZWN0TW9kZSI6ICJQT1NUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL2NhbGxiYWNrIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlRPS0VOIiwKICAgICJhdXRoTW9kZSI6ICIzRFMiLAogICAgInRva2VuRGV0YWlscyI6IHsKICAgICAgInRva2VuSW5mbyI6IHsKICAgICAgICAiZW5jcnlwdGVkVG9rZW4iOiAiT3V4K1BPZ3RjeGFyVDhwUThoWnp4N3R6R2VZRGRucFRRQ3BkdFloK1hZST0iLAogICAgICAgICJlbmNyeXB0aW9uS2V5SWQiOiA0OTU3NCwKICAgICAgICAiZXhwaXJ5IjogewogICAgICAgICAgIm1vbnRoIjogIjEyIiwKICAgICAgICAgICJ5ZWFyIjogIjIwMzAiCiAgICAgICAgfQogICAgICB9LAogICAgICAiY3Z2IjogIjIyMyIsCiAgICAgICJjcnlwdG9ncmFtSW5mbyI6IHsKICAgICAgICAiY3J5cHRvZ3JhbSI6ICJBZ0FBQUFvQVNMV1FzZDhBQUFBNWd4NEFBQUE9IiwKICAgICAgICAiZWNpIjogIjA3IiwKICAgICAgICAiYXRjIjogIjcyIgogICAgICB9CiAgICB9CiAgfQp9"
}
Request Field Details
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| Values = TOKEN |
|
| Encrypted token number which merchant passes to process card transaction |
| |
|
| KeyId of key which merchant uses to encrypt token |
| |
|
| Token expiry month |
| |
|
| Token expiry year |
| |
|
| Cryptogram which is generated in the get transaction data call |
| |
|
|
| ||
|
|
|
Sample Response
{
"success": true,
"code": "PAYMENT_INITIATED",
"message": "Payment initiated",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "OD620471739210623",
"instrumentResponse": {
"type": "TOKEN",
"redirectInfo": {
"url": "https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224",
"method": "GET"
}
}
}
}
Pay Request for UPI Collect
Sample Request
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "OD620471739210623",
"merchantUserId": "MUID123",
"amount": 10000,
"callbackUrl": "https://mykewlapp.com/callback",
"mobileNumber": "9999999999",
"paymentInstrument": {
"type": "UPI_COLLECT",
"vpa": "[email protected]"
}
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVVJRDEyMyIsCiAgImFtb3VudCI6IDEwMDAwLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0NPTExFQ1QiLAogICAgInZwYSI6ICJ0ZXN0LXZwYUB1cGkiCiAgfQp9"
}
Request Field Details
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| value = UPI_COLLECT |
|
| 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."
}
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
Parameter Name | Data Type | Description | Mandatory | Comments |
---|---|---|---|---|
|
| Type of instrument with which payment is being initiated |
| value = UPI_QR |
Sample Response
{
"success": true,
"code": "PAYMENT_INITIATED",
"message": "Payment Initiated",
"data": {
"merchantId": "MERCHANTUAT",
"transactionId": "OD620471739210623",
"qrData": "<Base64 encoded QR image string>"
}
}
Response Details
Response Headers
Header Name | Header Value |
---|---|
| application/json |
Response Parameters
Parameter Name | Data Type | Description | Comments |
---|---|---|---|
|
| Success/failure of request processing | |
|
| Response code explaining reason for status. For status SUCCESS, only one possible response code is present
| |
|
| Message giving more information about the code. | |
|
| Merchant id | |
|
| Transaction id generated by merchant | |
|
| 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 |
|
| Payload for redirecting user to bank page for authentication | |
|
| Url on which user needs to be redirected for authentication | |
|
| http method for loading redirect url | |
|
| Request headers to be passed while loading redirect url | |
|
| 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 |