Request Payment

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",
   "subMerchantId":"DemoMerchant",
   "storeId":"store1",
   "terminalId":"terminal1"
}
{
  "request": "eyJtZXJjaGFudE9yZGVySWQiOiAiT0QxMjM0IiwgInN1Yk1lcmNoYW50IjogIkRlbW9NZXJjaGFudCIsICJhbW91bnQiOiAxMDAsICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIiwgIm1vYmlsZU51bWJlciI6ICI5eHh4eHh4eHh4IiwgInNob3J0TmFtZSI6ICJBbWl0IiwgInRyYW5zYWN0aW9uSWQiOiAiVFgxMjM0NTY3ODkiLCAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsICJtZXJjaGFudElkIjogIkRlbW9NZXJjaGFudCIsICJlbWFpbCI6ICJhbWl0eHh4NzVAZ21haWwuY29tIn0"
}

Request Parameters

Parameter Name

Type

Description

Mandatory

merchantId

String

Unique Merchant ID assigned to the merchant by PhonePe

Yes

transactionId

String

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.

Yes

merchantOrderId

String

Unique Order ID generated by the merchant
merchantOrderId length should be less than 48 characters.

Yes

amount

Long

Amount in Paisa

Yes

instrumentType

ENUM

Has the value MOBILE

Yes

instrumentReference

String

Mobile number of the user

Yes

expiresIn

Long

expire time of payment completion.Payment should be completed with in this time else will be markedfailed. (default 30 days)

Yes

message

String

Recommended to pass transaction id, order id and invoice number.

No

email

String

Email Id of User

No

shortName

String

Customer Name

No

subMerchantId

String

Sub-category of the merchant

No

storeId

String

Store Id of store. Should be unique across.

Yes

terminalId

String

Terminal Id of store. Should be unique for a store.

No

Response Parameters

Parameter Name

Type

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

Sample Codes##

Sample code can be downloaded from the link mentioned below:-

URL: https://phon.pe/8jmk2kny,
Password: ULG1vOBHxU

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 POST 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!