Request Payment
post https://mercury-uat.phonepe.com/enterprise-sandbox/v3/charge/

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload +
“/v3/charge” + salt key) + ### + salt index
X-CALLBACK-URLCallback 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 NameDescription
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 NameDescription
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 VPA
  • INTERNAL_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 duplicate
  • BAD_REQUEST : Some mandatory parameter was missing
  • AUTHORIZATION_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

HEADERS
Content-Type string required
X-VERIFY string required
SHA256(base64 encoded payload + "/v3/charge" + salt key) + ### + salt index
X-CALLBACK-URL string required
Callback Url where a request will be made once user responds to collect request.

BODY PARAMS
request string required
base64 encoded payload

RESPONSES
Code 200
200
Code 400
400