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

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

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

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

Sample Payload for Base64 Decoding- 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.

Sample Request - Pay Page
{
	"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

Sample Response

Sample Response - Web Flow
{
  "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 Details

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

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

HEADERS

Content-Type string required

X-VERIFY string required

SHA256(base64 encoded payload + "/pg/v1/pay" + salt key) + ### + salt index

BODY PARAMS

request string required

base64 encoded payload

RESPONSES

Sequence

Request Details

Request Headers

Request Parameters

Sample Request for Pay Page

How to Calculate X-Verify/Checksum header

Sample Response

Response Details

Response Headers

Response Parameters

Response Codes

Common errors related to X-Verify header

Updated on Nov 10, 2023