Server to Server Callback

  • Server to server callbacks are initiated from PhonePe server to the url provided by merchant when payment reaches to any terminal state (SUCCESS or FAIL)
  • There are two ways to enable server to server callbacks.
    1.Either Register your static callback url with PhonePe. This is a one time process.
    2.Or, Send the callback url along with each payment request.

The URL is specified in header X-CALLBACK-URL
HTTP mode for callback is specified in header X-CALL-MODE

If different callback url is present at each location, then preference will be given to second method.

Payload

The payload that is going to be sent to the merchant on the specified callback url will have a base64 encoded json.

Upon base64 decoding the response, you should get a json with format similar to the response returned by transaction status API.

This is the best case callback that would be sent from PhonePe server to the merchants' server. In the event of a callback failure, the onus is on the merchants to use the transaction status API and take the transaction to closure.

Callback headers

Following are the response headers sent with a callback.

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64response + salt key) + ### + salt index

Response Parameters

Parameter NameDescription
success
BOOLEAN
true/ false
code
ENUM
This parameter is used to decide if payment is success or failed (see list of codes below)
message
STRING
Descriptive message
transactionId
STRING
transactionId (if this is static QR then this will be generated by PhonePe)
merchantId
STRING
merchantId
amount
LONG
Amount in paisa
merchantOrderId
STRING
Merchant Order Id
Note: The merchantOrderId would be returned only when the merchantOrderId passed in API request is different from the transactionId.
providerReferenceId
STRING
PhonePe transactionId
paymentState
STRING
COMPLETED/ FAILED
payResponseCode
STRING
More granular error codes for failure.
(Optional parameter to be sent in response)
paymentModes

List
Please see below for schema
(Optional parameter to be sent in response)
transactionContext
Object
Please see below for schema
(Optional parameter to be sent in response)

Server to Server Callback Response Codes

CodeDescription
PAYMENT_SUCCESSPayment is successful for QR scan
PAYMENT_ERRORPayment failed for QR scan
PAYMENT_DECLINEDPayment declined by customer
PAYMENT_CANCELLEDPayment cancelled by merchant

Payment Modes (Optional parameter to be sent in response)

Parameter NameDescription
modeACCOUNT/ WALLET/
EXTERNAL_WALLET/ DEBIT_CARD/
CREDIT_CARD/ EXTERNAL_VPA/
EGV/ NET_BANKING
amountAmount in paisa
utrUTR for UPI payments. For Wallet refunds, UTR will not be available, providerReferenceId can be treated as the reference

Transaction Context (Optional parameter to be sent in response)

Parameter NameDescription
qrCodeIdVPA
storeIdStore Id
terminalIdTerminal Id
curl -X POST \
  https://api.merchant.com/response/phonepe \
  -H 'content-type: application/json' \
  -H 'x-verify: 2abaa82a4810c57dcd6aa52680dd772173b1e40770afe028131f31ddbe5487a8###1' \
  -d '{
    "response":"eyAgCiAgICJzdWNjZXNzIjp0cnVlLAogICAiY29kZSI6IlBBWU1FTlRfU1VDQ0VTUyIsCiAgICJtZXNzYWdlIjoiWW91ciBwYXltZW50IGlzIHN1Y2Nlc3NmdWwuIiwKICAgImRhdGEiOnsgIAogICAgICAidHJhbnNhY3Rpb25JZCI6IlRYMzIzMjE4NDk2NDQyMzQiLAogICAgICAibWVyY2hhbnRJZCI6Ik0yMzA2MTYwNDgzMjIwNjc1NTc5MTQwIiwKICAgICAgInByb3ZpZGVyUmVmZXJlbmNlSWQiOiJQMTgwNjE1MTMyMzA5MzkwMDU1NDk1NyIsCiAgICAgICJhbW91bnQiOjEwMDAsCiAgICAgICJtZXJjaGFudE9yZGVySWQiOiAiT0QxNjI3NjMxMzIwNTUzMzgiCiAgICAgICJwYXltZW50U3RhdGUiOiJDT01QTEVURUQiLAogICAgICAicGF5UmVzcG9uc2VDb2RlIjoiU1VDQ0VTUyIsCiAgICAgICJwYXltZW50TW9kZXMiOlsgIAogICAgICAgICB7ICAKICAgICAgICAgICAgIm1vZGUiOiJBQ0NPVU5UIiwKICAgICAgICAgICAgImFtb3VudCI6MTAwMCwKICAgICAgICAgICAgInV0ciI6IjgxNjYyNjUyMTYxNiIKICAgICAgICAgfQogICAgICBdCiAgIH0KfQ=="
}'
{
  "response": "eyAgCiAgICJzdWNjZXNzIjp0cnVlLAogICAiY29kZSI6IlBBWU1FTlRfU1VDQ0VTUyIsCiAgICJtZXNzYWdlIjoiWW91ciBwYXltZW50IGlzIHN1Y2Nlc3NmdWwuIiwKICAgImRhdGEiOnsgIAogICAgICAidHJhbnNhY3Rpb25JZCI6IlRYMzIzMjE4NDk2NDQyMzQiLAogICAgICAibWVyY2hhbnRJZCI6Ik0yMzA2MTYwNDgzMjIwNjc1NTc5MTQwIiwKICAgICAgInByb3ZpZGVyUmVmZXJlbmNlSWQiOiJQMTgwNjE1MTMyMzA5MzkwMDU1NDk1NyIsCiAgICAgICJhbW91bnQiOjEwMDAsCiAgICAgICJtZXJjaGFudE9yZGVySWQiOiAiT0QxNjI3NjMxMzIwNTUzMzgiCiAgICAgICJwYXltZW50U3RhdGUiOiJDT01QTEVURUQiLAogICAgICAicGF5UmVzcG9uc2VDb2RlIjoiU1VDQ0VTUyIsCiAgICAgICJwYXltZW50TW9kZXMiOlsgIAogICAgICAgICB7ICAKICAgICAgICAgICAgIm1vZGUiOiJBQ0NPVU5UIiwKICAgICAgICAgICAgImFtb3VudCI6MTAwMCwKICAgICAgICAgICAgInV0ciI6IjgxNjYyNjUyMTYxNiIKICAgICAgICAgfQogICAgICBdCiAgIH0KfQ=="
}
{  
   "success":true,
   "code":"PAYMENT_SUCCESS",
   "message":"Your payment is successful.",
   "data":{  
      "transactionId":"TX32321849644234",
      "merchantId":"M2306160483220675579140",
      "providerReferenceId":"P1806151323093900554957",
      "amount":1000,
      "merchantOrderId": "OD162763132055338"
      "paymentState":"COMPLETED",
      "payResponseCode":"SUCCESS",
      "paymentModes":[  
         {  
            "mode":"ACCOUNT",
            "amount":1000,
            "utr":"816626521616"
         }
      ]
   }
}

🚧

  1. Success/Failure of the transaction should be dependent on the code in response parameters
  2. Cross-check the amount and checksum which has been passed in forward payment path(Accept payment API) and in the response of Server to Server callback.