post https://api-preprod.phonepe.com/apis/merchant-simulator/pg/v1/refund
This API is used for initiating the refund
Request Headers
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload + "/pg/v1/refund" + salt key) + ### + salt index |
{
"merchantId": "MERCHANTUAT",
"merchantUserId": "User123",
"originalTransactionId": "OD620471739210623",
"merchantTransactionId": "ROD620471739210623",
"amount": 1000,
"callbackUrl": "https://webhook.site/callback-url"
}
{
"request": "ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VXNlcklkIjogIlVzZXIxMjMiLAogICAgIm9yaWdpbmFsVHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIlJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAiYW1vdW50IjogMTAwMCwKICAgICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiCn0="
}
Request Parameters
| Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| merchantId | STRING | Unique Merchant ID assigned to the merchant by PhonePe | Yes |
| merchantUserId | STRING | User Id passed in the debit request | No |
| merchantTransactionId | STRING | Unique Refund Transaction ID generated by the merchant. 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 |
| amount | LONG | Reversal amount in paise. Upto a max of amount of original payment transaction. | Yes |
| callbackUrl | STRING | The url where server to server callback will be posted. Always POST | This callback will be of POST type and will contain the same payload as the Status API Response of Refund transaction. The callback will contain an X-VERIFY header which the merchant should verify. |
Sample Response
{
"success": true,
"code": "PAYMENT_PENDING",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "ROD620471739210623",
"transactionId": "TR620471739210623",
"amount": 10000,
"state": "PENDING",
"responseCode": "PAYMENT_PENDING"
}
}
Refund API Response
Merchants should rely on the "code" parameter for the status of the Refund API.
Merchants should validate the status of the Refund API either using Check Status API or the S2S Callback Response.
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "ROD620471739210623",
"transactionId": "TR620471739210623",
"amount": 10000,
"state": "COMPLETED",
"responseCode": "SUCCESS"
}
}
{
"success": false,
"code": "INTERNAL_SERVER_ERROR",
"message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}
Response Parameters
| Parameter Name | Type | Description |
|---|---|---|
| success | BOOLEAN | Success status of the request |
| code | STRING | Response code explaining reason for status. For status SUCCESS, only one possible response code is present - PAYMENT_SUCCESS For status FAILURE, following response codes are possible: ● INTERNAL_SERVER_ERROR ● BAD_REQUEST ● AUTHORIZATION_FAILED ● TRANSACTION_NOT_FOUND ● PAYMENT_ERROR ● PAYMENT_PENDING ● PAYMENT_DECLINED ● REVERSAL_WINDOW_EXCEEDED |
| message | STRING | Message giving more information about the code. |
| merchantId | STRING | Unique Merchant ID assigned to the merchant by PhonePe |
| merchantTransactionId | STRING | Transaction id generated by the merchant |
| transactionId | STRING | Transaction Id generated by the Phonepe |
| amount | LONG | Refunded amount against the forwarded transaction in paise |
| state | STRING | Transaction State |
| responseCode | STRING | Response code |
Error Codes
| Code | Description |
|---|---|
| BAD_REQUEST | Invalid request |
| AUTHORIZATION_FAILED | X-VERIFY header is incorrect |
| INTERNAL_SERVER_ERROR | Something went wrong |
| PAYMENT_SUCCESS | Payment is successful |
| PAYMENT_ERROR | Payment failed Note: Merchants can retry initiating the Refund. |
| TRANSACTION_NOT_FOUND | The original Transaction id is incorrect. |
| PAYMENT_PENDING | Payment is pending. It does not indicate failed payment. Note: Merchants shouldn't retry initiating the Refund while the status is PAYMENT_PENDING. Instead, merchants need to call Check Transaction Status to verify the transaction status till the terminal Success/Failure status is reached. |
| REVERSAL_WINDOW_EXCEEDED | The time window for refunding the transaction has been breached. Please process the refund manually |
Sample Refund S2S Response
Callback headers
Following are the response headers sent with the callback.
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64response + salt key) + ### + salt index |
{
"response": "eyJzdWNjZXNzIjp0cnVlLCJjb2RlIjoiUEFZTUVOVF9TVUNDRVNTIiwibWVzc2FnZSI6IllvdXIgcGF5bWVudCBpcyBzdWNjZXNzZnVsLiIsImRhdGEiOnsibWVyY2hhbnRJZCI6Ik1FUkNIQU5UVUFUIiwibWVyY2hhbnRUcmFuc2FjdGlvbklkIjoiZDliODY5MTMtZjhlZS00NGM3LThhYjctM2IzNjYwZDY1YzAzIiwidHJhbnNhY3Rpb25JZCI6IlAyMjA2MjQxMDQyMTkwOTUyNzAxMjEzIiwiYW1vdW50IjoxMDAsInN0YXRlIjoiQ09NUExFVEVEIiwicmVzcG9uc2VDb2RlIjoiUEFZTUVOVF9TVUNDRVNTIiwicGF5bWVudEluc3RydW1lbnQiOm51bGx9fQ=="
}
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your payment is successful.",
"data":
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "d9b86913-f8ee-44c7-8ab7-3b3660d65c03",
"transactionId": "P2206241042190952701213",
"amount": 100,
"state": "COMPLETED",
"responseCode": "PAYMENT_SUCCESS",
"paymentInstrument": null
}
}
S2S Refund Response
This callback will be of POST type and will contain the same payload as the Status API Response of Refund transaction.
The callback will contain a checksum in the "X-VERIFY" header which the merchant should validate for the checksum.
Once the checksum is verified, validate the amount parameter.