Request Headers
Header Name | Header Value |
---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload + “/v4/credit/backToSource” + salt key) + ### + salt index |
X-CALLBACK-URL | Dynamic callback URI for server-to-server callback |
X-CALLBACK-MODE | HTTP mode to be used for server-to-server callback |
Sample Request
{
"merchantId": "UATMERCHANT",
"transactionId": "TXTEST1294",
"providerReferenceId": "PPXXXXX",
"amount": 100,
"merchantOrderId": "OD1234",
"subMerchantId": "DemoMerchant",
"message": "refund for cancelled order"
}
{
"request": "ewogICAgIm1lcmNoYW50SWQiOiAiVUFUTUVSQ0hBTlQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVFhURVNUMTI5NCIsCiAgICAicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQUFhYWFhYIiwKICAgICJhbW91bnQiOiAxMDAsCiAgICAibWVyY2hhbnRPcmRlcklkIjogIk9EMTIzNCIsCiAgICAic3ViTWVyY2hhbnRJZCI6ICJEZW1vTWVyY2hhbnQiLAogICAgIm1lc3NhZ2UiOiAicmVmdW5kIGZvciBjYW5jZWxsZWQgb3JkZXIiCn0="
}
{
"merchantId": "UATMERCHANT",
"transactionId": "TXTEST1294",
"originalTransactionId": "TXTEST9891",
"amount": 100,
"merchantOrderId": "OD1234",
"subMerchantId": "DemoMerchant",
"message": "refund for cancelled order"
}
{
"request": "ewogICAgIm1lcmNoYW50SWQiOiAiVUFUTUVSQ0hBTlQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVFhURVNUMTI5NCIsCiAgICAib3JpZ2luYWxUcmFuc2FjdGlvbklkIjogIlRYVEVTVDk4OTEiLCAgICAKICAgICJhbW91bnQiOiAxMDAsCiAgICAibWVyY2hhbnRPcmRlcklkIjogIk9EMTIzNCIsCiAgICAic3ViTWVyY2hhbnRJZCI6ICJEZW1vTWVyY2hhbnQiLAogICAgIm1lc3NhZ2UiOiAicmVmdW5kIGZvciBjYW5jZWxsZWQgb3JkZXIiCn0="
}
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. This should be different from transaction ID of debit transaction. | Yes |
originalTransactionId | STRING | Merchant transaction Id of forward transaction which needs to be reversed. | Yes |
providerReferenceId | STRING | PhonePe transaction id of the original forward payment. Note : use only one of originalTransactionId, providerReferenceId only | Yes |
amount | LONG | Reversal amount in paise. Upto a max of amount of original payment transaction. | Yes |
merchantOrderId | STRING | Order ID for the merchant transaction | Yes |
subMerchantId | STRING | Tag to categorize merchant transaction | No |
message | STRING | Short message | Yes |
Sample Response
{
"success": true,
"code": "PAYMENT_PENDING",
"message": "Your request is in pending state.",
"data": {
"merchantId": "UATMERCHANT",
"amount": 100,
"providerReferenceId": "P2204061257259693373320",
"status": "PENDING",
"transactionId": "TXREFUND1045"
}
}
{
"success": false,
"code": "PAYMENT_ERROR",
"message": "Payment Failed",
"data": {
"merchantId": "UATMERCHANT",
"amount": 10000,
"providerReferenceId": "",
"payResponseCode": "EXCESS_REFUND_AMOUNT",
"status": "FAILED",
"transactionId": "TXREFUND1046"
}
}
S2S Callback Response
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your payment is successful.",
"data":
{
"merchantId": "HOTSTARONLINE",
"transactionId": "TXREFUND1047",
"providerReferenceId": "P2204061317483647785587",
"amount": 100,
"paymentState": "COMPLETED",
"payResponseCode": "SUCCESS",
"paymentModes":
[
{
"mode": "WALLET",
"amount": 100
}
],
"transactionContext":
{
"qrCodeId": null,
"posDeviceId": null,
"storeId": null,
"terminalId": null
}
}
}
Response Parameters
Parameter Name | Type | Description |
---|---|---|
success | BOOLEAN | Success status of the request |
code | ENUM | See list of response codes below |
message | STRING | Short message about code |
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 |
status | STRING | Status of the request |
mobileNumber | STRING | Mobile number of the user |
providerReferenceId | STRING | PhonePe payment transaction id against which the reversal is to be done |
payResponseCode | STRING | PhonePe internal status code |
Refund API Response Codes
Code | Description |
---|---|
BAD_REQUEST | Invalid request |
AUTHORIZATION_FAILED | X-VERIFY header is incorrect |
TRANSACTION_NOT_FOUND | Original transaction not found |
INTERNAL_SERVER_ERROR | Something went wrong. Refund might get initiated (need to check status with check transaction status API before retrying the refund) |
PAYMENT_SUCCESS | Payment is successful |
PAYMENT_ERROR | Payment failed |
PAYMENT_PENDING | Payment is pending. It does not indicate failed payment. Refund might get initiated (need to check status with check transaction status API before retrying the refund) |
TIMED_OUT | Refund timed out. Refund might get initiated (need to check status with check transaction status API before retrying the refund) |
REVERSAL_WINDOW_EXCEEDED | The time window for refunding the transaction has been breached. Please process the refund manually |
{“method”:”post”,”url”:”/v4/credit/backToSource “,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_PENDING\”,\n \”message\”: \”Your request is in pending state.\”,\n \”data\”: {\n \”merchantId\”: \”UATMERCHANT\”,\n \”amount\”: 100,\n \”providerReferenceId\”: \”P2204061257259693373320\”,\n \”status\”: \”PENDING\”,\n \”transactionId\”: \”TXREFUND1045\”\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{ \n \”success\”:false,\n \”code\”:\”BAD_REQUEST\”,\n \”message\”:\”Please check the inputs you have provided.\”,\n \”data\”:{}\n}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”62b185fdf7565b0023b7837e”},{“name”:”Content-type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837d”},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v4/credit/backToSource\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837c”},{“name”:”X-CALLBACK-URL”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Dynamic callback URI for server to server callback”,”required”:false,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837b”},{“name”:”X-CALLBACK-MODE”,”type”:”string”,”enumValues”:””,”default”:”POST”,”desc”:”HTTP mode to be used for server to server callback. Default Values are POST/PUT”,”required”:false,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837a”}],”apiSetting”:”5a1563aec32b6d002a16fb67″,”examples”:{“codes”:[]}}
https://api-preprod.phonepe.com/apis/pg-sandbox