Request Payment

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 Response will be sent to this URL once the user responds to the collect request.
Click here to see about this response.

{  
   "merchantId":"MERCHANTUAT",
   "transactionId":"TX123456789",
   "merchantOrderId":"M123456789",
   "amount":100,
   "instrumentType":"VPA",
   "instrumentReference":"[email protected]",
   "message":"Collect for the XXX order",
   "email":"[email protected]",
   "expiresIn":180,
   "shortName":"Customer",
   "subMerchantId":"DemoMerchant"
}
{
  "request": "eyAgCiAgICJtZXJjaGFudElkIjoiTUVSQ0hBTlRVQVQiLAogICAidHJhbnNhY3Rpb25JZCI6IlRYMTIzNDU2Nzg5IiwKICAgIm1lcmNoYW50T3JkZXJJZCI6Ik0xMjM0NTY3ODkiLAogICAiYW1vdW50IjoxMDAsCiAgICJpbnN0cnVtZW50VHlwZSI6IlZQQSIsCiAgICJpbnN0cnVtZW50UmVmZXJlbmNlIjoidGVzdHZwYUB5YmwiLAogICAibWVzc2FnZSI6IkNvbGxlY3QgZm9yIHRoZSBYWFggb3JkZXIiLAogICAiZW1haWwiOiJhbWl0eHh4NzVAZ21haWwuY29tIiwKICAgImV4cGlyZXNJbiI6MTgwLAogICAic2hvcnROYW1lIjoiQ3VzdG9tZXIiLAogICAic3ViTWVyY2hhbnRJZCI6IkRlbW9NZXJjaGFudCIKfQ=="
}

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 VPA

Yes

instrumentReference

String

VPA address entered by the user

Yes

expiresIn

Long

The expiry time of the collect request (in seconds). Payment should be completed with in this time else will be markedfailed. (Default expiry value is 30 days)

Yes

message

String

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

Optional

email

String

Email Id of User

Optional

shortName

String

Customer Name

Optional

subMerchant

String

Sub-category of the merchant

Optional

Sample Response

{
    "success": true,
    "code": "SUCCESS",
    "message": "Your request has been successfully completed.",
    "data":{
        "transactionId": "TX123456789",
        "amount": 100,
        "merchantId": "MERCHANTUAT",
        "providerReferenceId": "C161XXXXXXXXXX2210"
    }
}

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

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

S2S 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, Check Status API should be called.
  • If payment is in the pending state, the 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!