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.

PROD

PROD Host URL: https://api.phonepe.com/apis/hermes

UAT

UAT Host URL: https://api-preprod.phonepe.com/apis/pg-sandbox
API End Point: /pg/v1/pay

UAT PAY API URL: https://api-preprod.phonepe.com/apis/pg-sandbox/pg/v1/pay

Sequence

Request Details

Response Details

Request Details

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

Parameter Name	Data Type	Description	Mandatory
`merchantId`	`STRING`	Unique `MerchantID` assigned to the merchant by PhonePe Note: merchantId length will be less than 38 characters.	`Yes`
`merchantTransactionId`	`STRING`	Unique `Transaction ID` 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`
`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 “-“	`Yes`
`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`
`callbackUrl`	`STRING`	The 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`
`paymentInstrument`	`OBJECT`	Payment details	`Yes`
`paymentInstrument.type`	`ENUM`	Payment instrument type. Value will be: PAY_PAGE	`Yes`
`mobileNumber`	`STRING`	Mobile 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 Name	Header Value
`Content-Type`	application/json

Response Parameters

Parameter Name	Data Type	Description
`success`	`BOOLEAN`	Success/failure of request processing
`code`	`STRING`	Response code explaining reason for status
`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. 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.
`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

Response 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
INTERNAL_SECURITY_BLOCK_1	Mismatch in Transaction URL
INTERNAL_SECURITY_BLOCK_2	Mismatch in Transaction IP Address
INTERNAL_SECURITY_BLOCK_4	Mismatch in Transaction Package Name
INTERNAL_SECURITY_BLOCK_5	Missing or outdated Business Policy/s
INTERNAL_SECURITY_BLOCK_6	TPV Limit Reached

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″}

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

Sequence

Request Details

Request Headers

Request Parameters

Sample Request for Pay Page

How to Calculate X-Verify/Checksum header

Response Details

Sample Response

Response Headers

Response Parameters

Response Codes

Common errors related to X-Verify header

Updated on Nov 10, 2023