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:
- If you are using a personalized Chrome tab within their Android app, hindering URL retrieval. Please use SDK integration to resolve this issue.
- 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.
- 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.
Environment | Base URL |
---|---|
Test | https://api-preprod.phonepe.com/apis/pg-sandbox/pg/v1/pay |
Production | https://api.phonepe.com/apis/hermes/pg/v1/pay |
API End Point | /pg/v1/pay |
Sequence
- Request Headers
- Request Parameters
- Sample Request for Pay Page
- How to Calculate X-Verify/Checksum header
- 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: | 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
| 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
Response Details
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 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. Merchant will use this parameter later to check the status of the payment in Check Status API. |
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 |
Common errors related to X-Verify header
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