Search- Server to server callbacks are initiated from PhonePe server to the url provided by merchant when payment reaches to any terminal state (SUCESS or FAIL)
Callback url can be send along with each payment request in initiateTransactionRequest() API
The URL is specified in header X-CALLBACK-URL
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 Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(response + salt key) + ### + salt index |
Response Parameters
| Parameter Name | Type | Description |
|---|---|---|
success | BOOLEAN | true/ false |
code | ENUM(see list of codes below) | This parameter is used to decide if payment is success or failed |
transactionId | STRING | transactionId (if this is static QR then this will be generated by PhonePe) |
merchantId | STRING | merchantId |
amount | LONG | Amount in paisa |
providerReferenceId | STRING | PhonePe transactionId |
paymentState | STRING | COMPLETED/ FAILED |
payResponseCode | STRING | More granular error codes for failure. |
Server to Server Callback Response Codes
| Code | Description |
|---|---|
PAYMENT_SUCCESS | Payment is successful for QR scan |
PAYMENT_ERROR | Payment failed for QR scan |
PAYMENT_DECLINED | Payment declined by customer |
PAYMENT_CANCELLED | Payment cancelled by merchant |
Payment Modes
| Parameter Name | Description |
|---|---|
amount | Amount in paisa |
utr | UTR for UPI payments. |
curl -X POST \
https://api.merchant.com/response/phonepe \
-H 'content-type: application/json' \
-H 'x-verify: 2abaa82a4810c57dcd6aa52680dd772173b1e40770afe028131f31ddbe5487a8###1' \
-d '{
"response":"ewoJInN1Y2Nlc3MiOiB0cnVlLAoJImNvZGUiOiAiUEFZTUVOVF9TVUNDRVNTIiwKCSJkYXRhIjogewoJCSJ0cmFuc2FjdGlvbklkIjogImY2MjI0MjBmLTJmNTgtNGYyZS04MzJmIiwKCQkibWVyY2hhbnRJZCI6ICJNSURURVNUIiwKCQkiYW1vdW50IjogMTAwMCwKCQkicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQMTkxMjE4MTIxMDM1NzQyMTc1Njc1NSIsCgkJInBheW1lbnRTdGF0ZSI6ICJDT01QTEVURUQiLAoJCSJwYXlSZXNwb25zZUNvZGUiOiAiU1VDQ0VTUyIKCX0KfQ=="
}'
{
"response": "ewoJInN1Y2Nlc3MiOiB0cnVlLAoJImNvZGUiOiAiUEFZTUVOVF9TVUNDRVNTIiwKCSJkYXRhIjogewoJCSJ0cmFuc2FjdGlvbklkIjogImY2MjI0MjBmLTJmNTgtNGYyZS04MzJmIiwKCQkibWVyY2hhbnRJZCI6ICJNSURURVNUIiwKCQkiYW1vdW50IjogMTAwMCwKCQkicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQMTkxMjE4MTIxMDM1NzQyMTc1Njc1NSIsCgkJInBheW1lbnRTdGF0ZSI6ICJDT01QTEVURUQiLAoJCSJwYXlSZXNwb25zZUNvZGUiOiAiU1VDQ0VTUyIKCX0KfQ=="
}
{
"success": true,
"code": "PAYMENT_SUCCESS",
"data": {
"transactionId": "f622420f-2f58-4f2e-832f",
"merchantId": "MIDTEST",
"amount": 1000,
"providerReferenceId": "P1912181210357421756755",
"paymentState": "COMPLETED",
"payResponseCode": "SUCCESS"
}
}
- Success/Failure of transaction should be dependent on the code in response parameters
- Cross-check the amount which has been passed in forward payment path(Accept payment API) and in the response of Server to Server callback.