Pay API

This API initiates a payment transaction.

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

Request Headers

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

Request Parameters – Common Parameters

Parameter NameData TypeDescriptionMandatoryComments
merchantIdSTRINGUnique MerchantID assigned to the merchant by PhonePe

 

Note: merchantId length will be less than 38 characters.

Yes 
merchantTransactionIdSTRINGUnique TransactionID generated by the merchant to track request to PhonePe

 

Note:
merchantTransactionId length should be less than 35 characters.

– No Special characters allowed except underscore “_” and hyphen “-“

Yes 
amountLONGTransaction amount in Paise.
Note: Amount should be greater than 100 (in Paise)
Yes 
merchantUserIdSTRINGUnique 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 “-“

ConditionalMandatory if paymentInstrument.type is:
● PAY_PAGE
● CARD
● SAVED_CARD

 

Optional for if paymentInstrument.type is:
● UPI_INTENT
● UPI_COLLECT
● UPI_QR
● TOKEN
● NET_BANKING

redirectUrlSTRINGThe url where the user will be redirected after transaction completion.Yes 
redirectModeENUMredirectMode should be:
● REDIRECT
● POST (Should be used only if the Merchant’s URL can handle the POST method)
YesPossible values:
● REDIRECT
● POST
callbackUrlSTRINGThe url where server to server callback will be posted. Always POSTYesThis callback will be of POST type and will contain the same payload as the status response. The callback will contain an X-VERIFY header which the merchant should verify.
paymentInstrumentOBJECTPayment detailsYes 
paymentInstrument.typeENUMPayment instrument typeYesPossible values:
● PAY_PAGE
● CARD
● UPI_INTENT
● SAVED_CARD
● TOKEN
● UPI_COLLECT
● UPI_QR
● NET_BANKING
mobileNumberSTRINGMobile number of the 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 NameData TypeDescriptionMandatoryComments
paymentInstrument.typeSTRINGType of instrument with which payment is being initiatedYesvalue = UPI_INTENT
paymentInstrument.targetAppENUMTarget app for intent.
For iOS: If one needs to generate an intent url targeted at specific app on iOS, then the respective value should be passed.

For ANDROID: If one needs to open specific app on intent, then the respective package name needs to be passed.

YesPossible values for iOS:
● PHONEPE
● GPAY
● PAYTM

Possible values for Android:
Android package name
(For example:
● com.phonepe.app for PHONEPE
● net.one97.paytm for PAYTM)

deviceContext.deviceOSSTRINGDevice Operating SystemENUMPossible values for iOS:
● ANDROID
● IOS
paymentInstrument.accountConstraintsOBJECTTo be passed only for TPV FlowOptionalTo 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 NameData TypeDescriptionMandatoryComments
typeSTRINGType of instrument with which payment is being initiatedYesvalue = UPI_COLLECT
YesSTRINGVPA of user initiating paymentYes 
paymentInstrument.accountConstraintsOBJECTTo be passed only for TPV FlowOptionalTo 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 NameData TypeDescriptionMandatoryComments
typeSTRINGType of instrument with which payment is being initiatedYesvalue = UPI_QR
paymentInstrument.accountConstraintsOBJECTTo be passed only for TPV FlowOptionalTo 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 NameData TypeDescriptionMandatoryComments
paymentInstrument.typeENUMType of instrument with which payment is being initiatedYesValues = PAY_PAGE

Sample Response

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

Pay Request For Card Flow

Sample Request

{
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "OD620471739210623",
    "merchantUserId": "MU933037302229373",
    "amount": 10000,
    "redirectUrl": "https://webhook.site/redirect-url",
    "redirectMode": "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 NameData TypeDescriptionMandatoryComments
paymentInstrument.typeENUMType of instrument with which payment is being initiatedYesValues = CARD
authModeSTRINGAuthorisation mode with PG for payment validationYes 
saveCardBOOLEANfalse for the Guest Card FlowYes 
encryptionKeyIdLONGKeyId of key which merchant uses to encrypt card number & cvvYes 
encryptedCardNumberSTRINGEncrypted 16-Digit Card Number entered by the user.
Encryption Method: RSA 4096
Yes 
cardHolderNameSTRINGName of holder printed on cardYes 
expiry.monthSTRINGCard Expiry MonthYes 
expiry.yearSTRINGCard Expiry YearYes 
encryptedCvvSTRINGEncrypted CVV of the card with which payment is being initiated.

Encryption Method: RSA 4096

Yes 
billingAddressOBJECTBilling address details to be passed to the PGNo 

Sample Response

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

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

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

Encryption Method: RSA 4096

Yes 
encryptedTokenSTRINGEncrypted TOKEN number which merchant passes to process card transaction

Encryption Method: RSA 4096

Yes 
encryptionKeyIdLONGKeyId of key which merchant uses to encrypt token and cvvYes 
expiry.monthSTRINGToken expiry monthYes 
expiry.yearSTRINGToken expiry yearYes 
cryptogramSTRINGThe cryptogram fetched from the gateway where the card was tokenized.Yes 
panSuffixSTRINGLast four digits of cardNumberYes 
cardHolderNameSTRINGCard Holder NameNo 
merchantUserIdSTRINGMerchant User Id unique for the customerNo 

Sample Response

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

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

Sample Response

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

Response Details

Response Headers

Header NameHeader Value
Content-Typeapplication/json

Response Parameters

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

For status SUCCESS, only one possible response code is present
PAYMENT_INITIATED
For status FAILURE, following response codes are possible:
BAD_REQUEST
AUTHORIZATION_FAILED
PAYMENT_ERROR
INTERNAL_SERVER_ERROR

 
messageSTRINGMessage giving more information about the code. 
merchantIdSTRINGMerchant id 
merchantTransactionIdSTRINGTransaction id generated by merchant 
transactionIdSTRINGTransaction id generated by PhonePeThis may not always be available in response of a pay call but will always be available in callback or status call after transaction completion
redirectInfoSTRINGPayload for redirecting user to bank page for authentication 
urlSTRINGUrl on which user needs to be redirected for authentication 
methodSTRINGhttp method for loading redirect url 
headersMap<String, String>Request headers to be passed while loading redirect url 
dataMap<String, String>Form data to be submitted to redirect url page 

Error Codes

CodeDescription
PAYMENT_INITIATEDPayment is initiated successfully
PAYMENT_ERRORPayment initiation has failed
INTERNAL_SERVER_ERRORSomething went wrong
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect
ScenarioError CodeResponse Body
X-Verify is not passed in request headers or passed in different format than expected400 (Bad Request) 
Incorrect X-Verify header passed in request401{“success”:false,”code”:”401″}
{“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