Request Headers
Header Name | Header Value |
---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload + “/v3/charge” + salt key) + ### + salt index |
X-CALLBACK-URL | Callback Url where a request will be made once user responds to collect request. Click here to see about this request. |
Sample Payload for Base64{
"merchantId":"DemoMerchant",
"transactionId":"TX123456789",
"merchantOrderId":"M123456789",
"amount":100,
"instrumentType":"MOBILE",
"instrumentReference":"9xxxxxxxxxx",
"message":"collect for XXX order",
"email":"amitxxx75@gmail.com",
"expiresIn":180,
"shortName":"DemoCustomer",
"subMerchant":"DemoMerchant",
"storeId":"store1",
"terminalId":"terminal1"
}
Sample Request{
"request": "eyJtZXJjaGFudE9yZGVySWQiOiAiT0QxMjM0IiwgInN1Yk1lcmNoYW50IjogIkRlbW9NZXJjaGFudCIsICJhbW91bnQiOiAxMDAsICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIiwgIm1vYmlsZU51bWJlciI6ICI5eHh4eHh4eHh4IiwgInNob3J0TmFtZSI6ICJBbWl0IiwgInRyYW5zYWN0aW9uSWQiOiAiVFgxMjM0NTY3ODkiLCAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsICJtZXJjaGFudElkIjogIkRlbW9NZXJjaGFudCIsICJlbWFpbCI6ICJhbWl0eHh4NzVAZ21haWwuY29tIn0"
}
Request Parameters
Parameter Name | Description | ||
---|---|---|---|
merchantId String Mandatory | Unique Merchant ID assigned to the merchant by PhonePe | ||
transactionId String Mandatory | Unique Transaction ID generated by the merchant to track this request to PhonePe transactionId length Should be unique for each collect request.should be less than 38 characters. | ||
merchantOrderId String Mandatory | Unique Order ID generated by the merchant merchantOrderId length should be less than 48 characters. | ||
amount Long Mandatory | Amount in Paisa | ||
instrumentType Enum Mandatory | Has the value MOBILE | ||
instrumentReference String Mandatory | Mobile number of the user | ||
expiresIn Long Mandatory | expire time of payment completion.Payment should be completed with in this time else will be markedfailed . (default 30 days) | ||
message String Optional | Recommended to pass transaction id, order id and invoice number . | ||
email String Optional | Email Id of User | ||
shortName String Optional | Customer Name | ||
subMerchant String Optional | Sub-category of the merchant | ||
storeId String Mandatory | Store Id of store. Should be unique across. | ||
terminalId String Mandatory | Terminal Id of store. Should be unique for a store. |
Response Parameters
Parameter Name | Description | |
---|---|---|
success Boolean | Success status of the request | |
code Enum | See below section for list of codes | |
message String | Short message about status of request | |
transactionId String | Unique Transaction ID generated by the merchant to track this request to PhonePe | |
merchantId String | Unique Merchant ID assigned to the merchant by PhonePe | |
amount Long | Transaction amount in paise | |
providerReferenceId String | PhonePe transaction Id | |
mobileNumber String | Mobile Number |
Response Codes
The code in the above API response could be:
SUCCESS
: Collect was successfully sent to VPAINTERNAL_SERVER_ERROR
: Something went wrong. Need to validate through check transaction status API first to know the payment status.INVALID_TRANSACTION_ID
: TransactionId in request was duplicateBAD_REQUEST
: Some mandatory parameter was missingAUTHORIZATION_FAILED
: Checksum sent in header was not valid
Charge Callback
When the user responds to the collect request sent by the merchant, a request is sent to either the URL provided in X-CALLBACK-URL or the merchant’s registered callback URL. By default, this is a PUT request.
Note:
- The callback would be sent only for success/Failed scenarios. For pending cases, there won’t be any callback. For such transactions payment status should be checked with below API.
- If payment is in pending state, Merchant should display a message “Payment is in progress, please wait for sometime.”
- The payment will always be closed within the expiry time passed in the collect request.
{“method”:”post”,”url”:”/v3/charge/”,”auth”:”required”,”results”:{“codes”:[{“code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”:{\n \”transactionId\”: \”TX123456789\”,\n \”amount\”: 100,\n \”merchantId\”: \”DemoMerchant\”,\n \”mobileNumber\”: \”9xxxxxxxxxx\”,\n \”providerReferenceId\”: \”C161XXXXXXXXXX2210\”\n }\n}”,”language”:”json”,”status”:200,”name”:”Success Response”},{“code”:”{\n \”success\”: false,\n \”code\”: \”INTERNAL_SERVER_ERROR\”,\n \”message\”: \”There was some error with the request. Please try again.\”,\n \”data\”: {}\n}”,”language”:”json”,”status”:400,”name”:”Failure Response”}]},”params”:[{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a1e9d7a4ab624001e3c8d10″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v3/charge\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a1e9d7a4ab624001e3c8d0f”},{“name”:”X-CALLBACK-URL”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Callback Url where a request will be made once user responds to collect request.”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a1e9d7a4ab624001e3c8d0e”},{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”5a1e9d7a4ab624001e3c8d0d”}],”apiSetting”:”5ce68ac4d3a82d0051af9e17″,”examples”:{“codes”:[]}}
https://mercury-uat.phonepe.com/enterprise-sandbox