PAY API


Note:

If you are utilizing a mobile app, we advise you to explore our mobile SDKs. Please note that API integration is exclusively supported for web apps. By opting for SDK integration, you can enhance the payment experience for your customers, minimizing unnecessary steps in the process.

To avoid transaction blocking in production, please keep a check on the below points:

  1. If you are using a personalized Chrome tab within their Android app, hindering URL retrieval. Please use SDK integration to resolve this issue.
  2. If you are launching PayPage in a new window/tab, resulting in the absence of a referrer, then either redirect or employ an iFrame for PayPage is essential.
  3. If you have implemented a no-referrer-policy then it leads to blank merchant URLs captured at our end. Please refrain from using it on the checkout page.

Note: Merchants must use their backend server to hit these APIs. If they attempt to hit the API from the frontend server, they will encounter a CORS policy error.

Payment Gateway End Points
EnvironmentBase URL
Testhttps://api-preprod.phonepe.com/apis/pg-sandbox/pg/v1/pay
Productionhttps://api.phonepe.com/apis/hermes/pg/v1/pay
API End Point/pg/v1/pay

Request Details

Response Details

Request Details

Request Headers

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

Request Parameters

Parameter NameData TypeDescriptionMandatory
merchantIdSTRINGUnique MerchantID assigned to the merchant by PhonePe

 

Note: merchantId length will be less than 38 characters.

Yes
merchantTransactionIdSTRINGUnique Transaction ID generated by the merchant to track request to PhonePe

 

Note:
merchantTransactionId length should be less than 35 characters

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

 

Yes
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)
Yes
callbackUrlSTRINGThe url where server to server callback will be posted. Always POST.

 

Note: 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 before decoding the response.

Yes
paymentInstrumentOBJECTPayment detailsYes
paymentInstrument.typeENUMPayment instrument type.
Value will be: PAY_PAGE
Yes
mobileNumberSTRINGMobile number of the user
Note: There should not be any space.
No

Sample Request for Pay Page

{
  "merchantId": "PGTESTPAYUAT",
  "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":"ewogICJtZXJjaGFudElkIjogIlBHVEVTVFBBWVVBVCIsCiAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICJtZXJjaGFudFVzZXJJZCI6ICJNVUlEMTIzIiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJSRURJUkVDVCIsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJQQVlfUEFHRSIKICB9Cn0="
}

How to Calculate X-Verify/Checksum header

Formula: SHA256(Base64 encoded payload + “/pg/v1/pay” + salt key) + ### + salt index

Base64 encoded payload:
ewogICJtZXJjaGFudElkIjogIlBHVEVTVFBBWVVBVCIsCiAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICJtZXJjaGFudFVzZXJJZCI6ICJNVUlEMTIzIiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJSRURJUkVDVCIsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJQQVlfUEFHRSIKICB9Cn0=

API Endpoint:
/pg/v1/pay

Sample Salt Key:
099eb0cd-02cf-4e2a-8aca-3e6c6aff0399

Sample Salt Index:
1

Final Computation:

SHA256 (ewogICJtZXJjaGFudElkIjogIlBHVEVTVFBBWVVBVCIsCiAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICJtZXJjaGFudFVzZXJJZCI6ICJNVUlEMTIzIiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJSRURJUkVDVCIsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJQQVlfUEFHRSIKICB9Cn0=/pg/v1/pay099eb0cd-02cf-4e2a-8aca-3e6c6aff0399) + ### + 1

Checksum Value :
d7a8e4458caa6fcd781166bbdc85fec76740c18cb9baa9a4c48cf2387d554180###1

Response Details

Sample Response

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

Response Headers

Header NameHeader Value
Content-Typeapplication/json

Response Parameters

Parameter NameData TypeDescription
successBOOLEANSuccess/failure of request processing
codeSTRINGResponse code explaining reason for status
messageSTRINGMessage giving more information about the code.
merchantIdSTRINGMerchant id
merchantTransactionIdSTRINGTransaction id generated by merchant. Merchant will use this parameter later to check the status of the payment in Check Status API.
transactionIdSTRINGTransaction id generated by PhonePe.
Note: 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.
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

Response 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
INTERNAL_SECURITY_BLOCK_1Mismatch in Transaction URL
INTERNAL_SECURITY_BLOCK_2Mismatch in Transaction IP Address
INTERNAL_SECURITY_BLOCK_4Mismatch in Transaction Package Name
INTERNAL_SECURITY_BLOCK_5Missing or outdated Business Policy/s
INTERNAL_SECURITY_BLOCK_6TPV Limit Reached
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″}

Only for UAT, merchants can try out the flow in PhonePe Developer Docs

{“method”:”post”,”url”:”/pg/v1/pay”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n \”merchantTransactionId\”: \”b7aa2cc7-cc5e-4d71-b98f-63ebf549010c\”,\n \”instrumentResponse\”: {\n \”type\”: \”PAY_PAGE\”,\n \”redirectInfo\”: {\n \”url\”: \”https://mercury-uat.phonepe.com/transact/pg?token=NGVjMzhjOWMzMGI5ODI2OWMwYmQ2MzUzYWE2ZDYzZGM0M2M0NjZkNjVjMWRmNzlmODk1YWEwNjViMTUwNjYyOTI4NDY1OWExYzNmMjQzNjYzZjgxOTQzYjVjMGUyMmYyZGZhMTg5ODRlZDM2MzEzNWYyZDViOTdkZmU2NjFjOGU3ZTdiMzNlNzpmM2ZkZDYwY2JmNGFiYTUxM2Y3OGJhNGVjOTQ5OWU1NQ\”,\n \”method\”: \”GET\”\n }\n }\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”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}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”6390671393c524001014e0b2″},{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”6390671393c524001014e0b1″},{“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”:”6390671393c524001014e0b0″}],”examples”:{“codes”:[]},”apiSetting”:”63bb01b11abcf7046d98754c”}
https://api-preprod.phonepe.com/apis/pg-sandbox