Server to Server Callback

  • Server to server callbacks are initiated from the PhonePe server to the URL provided by the merchant when the payment reaches any terminal state (SUCCESS or FAIL)
  • There are two ways to enable the 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 the request parameter callbackUrl

If a different callback URL is present at each location, then preference will be given to the 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 a format similar to the response returned by transaction status API.

This is the best case callback that would be sent from the 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

Sample Callback Response

{
  "response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX1NVQ0NFU1MiLAogICJtZXNzYWdlIjogIllvdXIgcmVxdWVzdCBoYXMgYmVlbiBzdWNjZXNzZnVsbHkgY29tcGxldGVkLiIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJGS1JUIiwKICAgICJtZXJjaGFudFRyYW5zYWN0aW9uSWQiOiAiTVQ3ODUwNTkwMDY4MTg4MTA0IiwKICAgICJ0cmFuc2FjdGlvbklkIjogIlQyMTExMjIxNDM3NDU2MTkwMTcwMzc5IiwKICAgICJhbW91bnQiOiAxMDAsCiAgICAicGF5bWVudFN0YXRlIjogIkNPTVBMRVRFRCIsCiAgICAicGF5UmVzcG9uc2VDb2RlIjogIlBBWU1FTlRfU1VDQ0VTUyIsCiAgICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAgICJ0eXBlIjogIlVQSSIsCiAgICAgICJ1dHIiOiAiMjA2Mzc4ODY2MTEyIgogICAgfQogIH0KfQ=="
}
{
  "response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX1NVQ0NFU1MiLAogICJtZXNzYWdlIjogIllvdXIgcmVxdWVzdCBoYXMgYmVlbiBzdWNjZXNzZnVsbHkgY29tcGxldGVkLiIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJGS1JUIiwKICAgICJtZXJjaGFudFRyYW5zYWN0aW9uSWQiOiAiTVQ3ODUwNTkwMDY4MTg4MTA0IiwKICAgICJ0cmFuc2FjdGlvbklkIjogIlQyMTExMjIxNDM3NDU2MTkwMTcwMzc5IiwKICAgICJhbW91bnQiOiAxMDAsCiAgICAicGF5bWVudFN0YXRlIjogIkNPTVBMRVRFRCIsCiAgICAicGF5UmVzcG9uc2VDb2RlIjogIlBBWU1FTlRfU1VDQ0VTUyIsCiAgICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAgICJ0eXBlIjogIkNBUkQiLAogICAgICAiY2FyZFR5cGUiOiAiREVCSVRfQ0FSRCIsCiAgICAgICJwZ1RyYW5zYWN0aW9uSWQiOiAiYjkwOTAyNDJhYzEyMDAwMiIsCiAgICAgICJiYW5rVHJhbnNhY3Rpb25JZCI6ICJlNTdhNjU4ZTllMTAxMWVjIiwKICAgICAgInBnQXV0aG9yaXphdGlvbkNvZGUiOiAiOWNmM2VmNDkzMmJmOWUwNSIsCiAgICAgICJhcm4iOiAiMzM5NDgyNzczOTI3IiwKICAgICAgImJhbmtJZCI6ICJTQklOIgogICAgfQogIH0KfQ=="
}
{
  "response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX1NVQ0NFU1MiLAogICJtZXNzYWdlIjogIllvdXIgcmVxdWVzdCBoYXMgYmVlbiBzdWNjZXNzZnVsbHkgY29tcGxldGVkLiIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJGS1JUIiwKICAgICJtZXJjaGFudFRyYW5zYWN0aW9uSWQiOiAiTVQ3ODUwNTkwMDY4MTg4MTA0IiwKICAgICJ0cmFuc2FjdGlvbklkIjogIlQyMjA2MjAyMDIwMzI1NTg5MTQ0OTExIiwKICAgICJhbW91bnQiOiAxMDAsCiAgICAic3RhdGUiOiAiQ09NUExFVEVEIiwKICAgICJyZXNwb25zZUNvZGUiOiAiUEFZTUVOVF9TVUNDRVNTIiwKICAgICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICAgInR5cGUiOiAiTkVUX0JBTktJTkciLAogICAgICAicGdUcmFuc2FjdGlvbklkIjogIjE4NTY5ODI5MDAiLAogICAgICAicGdTZXJ2aWNlVHJhbnNhY3Rpb25JZCI6ICJQRzIyMDcyODE4MTEyNzEyNjMyNzQzODAiLAogICAgICAiYmFua1RyYW5zYWN0aW9uSWQiOiBudWxsLAogICAgICAiYmFua0lkIjogIlNCSU4iCiAgICB9CiAgfQp9"
}

Base64 Decoded Sample Response

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "FKRT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "paymentState": "COMPLETED",
    "payResponseCode": "PAYMENT_SUCCESS",
    "paymentInstrument": {
      "type": "UPI",
      "utr": "206378866112"
    }
  }
}
{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "FKRT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "paymentState": "COMPLETED",
    "payResponseCode": "PAYMENT_SUCCESS",
    "paymentInstrument": {
      "type": "CARD",
      "cardType": "DEBIT_CARD",
      "pgTransactionId": "b9090242ac120002",
      "bankTransactionId": "e57a658e9e1011ec",
      "pgAuthorizationCode": "9cf3ef4932bf9e05",
      "arn": "339482773927",
      "bankId": "SBIN"
    }
  }
}
{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "FKRT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2206202020325589144911",
    "amount": 100,
    "state": "COMPLETED",
    "responseCode": "PAYMENT_SUCCESS",
    "paymentInstrument": {
      "type": "NET_BANKING",
      "pgTransactionId": "1856982900",
      "pgServiceTransactionId": "PG2207281811271263274380",
      "bankTransactionId": null,
      "bankId": "SBIN"
    }
  }
}

🚧

  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(PAY API) and in the response of Server to Server callback.