Request Payment APIs are used when the merchant wants to send a collect payment request to user's PhonePe app against an order.

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.

{  
   "merchantId":"DemoMerchant",
   "transactionId":"TX123456789",
   "merchantOrderId":"M123456789",
   "amount":100,
   "instrumentType":"MOBILE",
   "instrumentReference":"9xxxxxxxxxx",
   "message":"collect for XXX order",
   "email":"[email protected]",
   "expiresIn":180,
   "shortName":"DemoCustomer",
   "subMerchant":"DemoMerchant",
   "storeId":"store1",
   "terminalId":"terminal1"
}
{
  "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 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.
Language
Click Try It! to start a request and see the response here!