Search- 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.
- Either Register your static callback URL with PhonePe. This is a one-time process.
- 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 Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64response + salt key) + ### + salt index |
Sample Callback Response – Success
Note: Not to have strict deserialization in the Check Status or Webhook response. If any unknown fields are received within the response, merchants should ignore.
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX1NVQ0NFU1MiLAogICJtZXNzYWdlIjogIllvdXIgcmVxdWVzdCBoYXMgYmVlbiBzdWNjZXNzZnVsbHkgY29tcGxldGVkLiIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJQR1RFU1RQQVlVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVDIxMTEyMjE0Mzc0NTYxOTAxNzAzNzkiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJzdGF0ZSI6ICJDT01QTEVURUQiLAogICAgInJlc3BvbnNlQ29kZSI6ICJTVUNDRVNTIiwKICAgICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICAgInR5cGUiOiAiVVBJIiwKICAgICAgInV0ciI6ICIyMDYzNzg4NjYxMTIiCiAgICB9CiAgfQp9Cg=="
}
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX1NVQ0NFU1MiLAogICJtZXNzYWdlIjogIllvdXIgcmVxdWVzdCBoYXMgYmVlbiBzdWNjZXNzZnVsbHkgY29tcGxldGVkLiIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJQR1RFU1RQQVlVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVDIxMTEyMjE0Mzc0NTYxOTAxNzAzNzkiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJzdGF0ZSI6ICJDT01QTEVURUQiLAogICAgInJlc3BvbnNlQ29kZSI6ICJTVUNDRVNTIiwKICAgICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICAgInR5cGUiOiAiQ0FSRCIsCiAgICAgICJjYXJkVHlwZSI6ICJERUJJVF9DQVJEIiwKICAgICAgInBnVHJhbnNhY3Rpb25JZCI6ICJiOTA5MDI0MmFjMTIwMDAyIiwKICAgICAgImJhbmtUcmFuc2FjdGlvbklkIjogImU1N2E2NThlOWUxMDExZWMiLAogICAgICAicGdBdXRob3JpemF0aW9uQ29kZSI6ICI5Y2YzZWY0OTMyYmY5ZTA1IiwKICAgICAgImFybiI6ICIzMzk0ODI3NzM5MjciLAogICAgICAiYmFua0lkIjogIlNCSU4iCiAgICB9CiAgfQp9"
}
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX1NVQ0NFU1MiLAogICJtZXNzYWdlIjogIllvdXIgcmVxdWVzdCBoYXMgYmVlbiBzdWNjZXNzZnVsbHkgY29tcGxldGVkLiIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJQR1RFU1RQQVlVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVDIyMDYyMDIwMjAzMjU1ODkxNDQ5MTEiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJzdGF0ZSI6ICJDT01QTEVURUQiLAogICAgInJlc3BvbnNlQ29kZSI6ICJTVUNDRVNTIiwKICAgICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICAgInR5cGUiOiAiTkVUQkFOS0lORyIsCiAgICAgICJwZ1RyYW5zYWN0aW9uSWQiOiAiMTg1Njk4MjkwMCIsCiAgICAgICJwZ1NlcnZpY2VUcmFuc2FjdGlvbklkIjogIlBHMjIwNzI4MTgxMTI3MTI2MzI3NDM4MCIsCiAgICAgICJiYW5rVHJhbnNhY3Rpb25JZCI6IG51bGwsCiAgICAgICJiYW5rSWQiOiAiU0JJTiIKICAgIH0KICB9Cn0="
}
Base64 Decoded Sample Response
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "PGTESTPAYUAT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2111221437456190170379",
"amount": 100,
"state": "COMPLETED",
"responseCode": "SUCCESS",
"paymentInstrument": {
"type": "UPI",
"utr": "206378866112"
}
}
}
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "PGTESTPAYUAT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2111221437456190170379",
"amount": 100,
"state": "COMPLETED",
"responseCode": "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": "PGTESTPAYUAT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2206202020325589144911",
"amount": 100,
"state": "COMPLETED",
"responseCode": "SUCCESS",
"paymentInstrument": {
"type": "NETBANKING",
"pgTransactionId": "1856982900",
"pgServiceTransactionId": "PG2207281811271263274380",
"bankTransactionId": null,
"bankId": "SBIN"
}
}
}
Sample Callback Response – Failure
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJQQVlNRU5UX0VSUk9SIiwKICAibWVzc2FnZSI6ICJQYXltZW50IEZhaWxlZCIsCiAgImRhdGEiOiB7CiAgICAibWVyY2hhbnRJZCI6ICJQR1RFU1RQQVlVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJNVDc4NTA1OTAwNjgxODgxMDQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVDIxMTEyMjE0Mzc0NTYxOTAxNzAzNzkiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJzdGF0ZSI6ICJGQUlMRUQiLAogICAgInJlc3BvbnNlQ29kZSI6ICJaVSIsCiAgICAicGF5bWVudEluc3RydW1lbnQiOiBudWxsCiAgfQp9"
}
Base64 Decoded Sample Response
{
"success": true,
"code": "PAYMENT_ERROR",
"message": "Payment Failed",
"data": {
"merchantId": "PGTESTPAYUAT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2111221437456190170379",
"amount": 100,
"state": "FAILED",
"responseCode": "ZU",
"paymentInstrument": null
}
}
- Success/Failure of the transaction should be dependent on the code in response parameters
- Validate the checksum received in the response of Server to Server callback with the checksum calculated at your end.
- Validate the amount which has been passed in the forward payment path(PAY API) with the response of Server to Server callback.