Refund Status API

The Refund Status API for Split Payments provides a specialized mechanism for tracking refund statuses in split payment scenarios. It's designed for aggregator merchants who process payments divided among multiple recipients. Unlike the v1 API, this enhanced version provides complete visibility into parent-child transaction relationships, refund actions, and settlement details.

Endpoint


Test Environment	https://test.payu.in/v2/refunds/status
Production Environment	https://info.payu.in/v2/refunds/status

Request headers

Parameter	Description
date	The current date and time. For example, format of the date is Wed, 28 Jun 2023 11:25:19 GMT.
authorization	The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to authorization fields description.

authorization fields description

Field	Description
username	Represents the username or identifier for the client or merchant, for example smsplus.
algorithm	Use SHA512 algorithm for hashing and send this as header value.
headers	Specifies which headers have been used in generating the hash, for example date.
signature	The HMAC signature generated using the specified algorithm. For more information, refer to hashing algorithm.

hashing algorithm

You must hash the request parameters using the following hash logic:

Hash logic: sha512(<Body data> + '|' + date + '|' + merchant_secret)

Where <Body data> contains the request body posted with the request.

Sample header code

var merchant_key = 'smsplus';
var merchant_secret = 'izF09TlpX4ZOwmf9MvXijwYsBPUmxYHD';
// date
var date = new Date();
date = date.toUTCString();

// authorization
var authorization = getAuthHeader(date);

function getAuthHeader(date) {
    var AUTH_TYPE = 'sha512';
    var data = isEmpty(request['data']) ? "" : request['data'];
    var hash_string = data + '|' + date + '|' + merchant_secret;
    var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
    return `hmac username="${merchant_key}", algorithm="${AUTH_TYPE}", headers="date", signature="${hash}"`;
}

Request body

📘
Note:
At least one of the following parameters must be provided: requestId, payuId, or tokenId.

Parameter	Description	Example
requestId `conditional`	`String Array` Array of request IDs for which the refund information is required.	`["11763053990", "11763053112"]`
payuId `conditional`	`String Array` Array of PayU transaction IDs or PayU ID for which the refund information is required. Payu ID (mihpayuid) that you receive in the response for a successful payment transaction.	`["11763053990"]`
tokenId `conditional`	`String Array` This parameter must contain the Token ID (unique token from the merchant) for the refund request. Token ID has to be generated at your end for each new refund request. It is an identifier for each new refund request which can be used for tracking it. It must be unique for every new refund request generated – otherwise the refund request would not be generated successfully. Token ID length should not be greater than 23 characters	`["TOKEN12345"]`

Sample request

curl --location 'http://info.payu.in/v2/refunds/status' \
--header 'mid: 8006653' \
--header 'Content-Type: application/json' \
--header 'Authorization: hmac username="KOEfPI", algorithm="sha512", headers="date", signature="33560cfbfe91d98dc4d395de8e212e9f9c8e8d88459c4ac2948962ad5e7ecdd0f23b695d4aacd1ac3a94bf912ece4f61fe9e0a8566b7b016c8a52fc1a0299d3c"' \
--data '{
    "payuId": [
        "999000000000462"
    ],
    "requestId": [
        "999000000000462"
    ]
}'

Response parameters

Parameter	Description	Example
message	Indicates the result of the API call	`"Success"`
status	Status of the API call (1 for success, 0 for failure)	`1`
result	Array containing the parent and split transaction details	See JSON example
payuId	The PayU ID of the parent transaction	`17253043342`
transactionDetails	Basic details of the parent transaction	Contains ID, status, amount, etc.
transactionActionDetails	Actions performed on the parent transaction	Contains action type, status, amount, etc.
splitTransactionDetails	Array of split transaction details	Contains payuId, transactionDetails, etc.
transactionActionDetails (in splits)	Actions performed on each split transaction	Contains refund actions and their details

Sample response

Success response

General use case

{
    "message": "Success",
    "status": 1,
    "result": [
        {
            "payuId": 17253043342,
            "transactionDetails": {
                "id": 17253043342,
                "transactionId": "PB35163007S",
                "status": "autoRefund",
                "discount": 0.0,
                "amount": 0.0,
                "transactionFee": 2259.0,
                "additionalCharges": 0.0,
                "mode": "CASH",
                "baseTxnId": 0,
                "firstName": "Masood",
                "lastName": "Masood Ahmed Wani",
                "addedOn": "2023-04-27 16:18:16",
                "phone": "8448480680",
                "email": "[email protected]",
                "productInfo": "PBProduct",
                "errorCode": "E000",
                "ibiboCode": "FREC",
                "merchantKey": "iDJYfd",
                "errorMessage": "No Error",
                "paymentSource": "payuS2S"
            },
            "transactionActionDetails": [
                {
                    "id": 12031063143,
                    "bankRefNo": "5jeF8wMyZ9jnZ9_17253043342_1",
                    "token": null,
                    "actionType": "capture",
                    "prevStatus": "failed",
                    "amount": 2259.0,
                    "status": "SUCCESS",
                    "bankArn": "5jeF8wMyZ9jnZ9_17253043342_1",
                    "updatedAt": "2023-04-28 10:09:04",
                    "createdAt": "2023-04-28 10:01:14",
                    "settlementId": null,
                    "amountSettled": null,
                    "refundMode": "-",
                    "settledOn": null,
                    "merchantUTR": null
                }
            ],
            "splitTransactionDetails": [
                {
                    "payuId": 12071315088,
                    "transactionDetails": {
                        "id": 12071315088,
                        "transactionId": "PB35163007S_1",
                        "status": "success",
                        "discount": 0.0,
                        "amount": 2259.0,
                        "transactionFee": 0.0,
                        "additionalCharges": 0.0,
                        "mode": "CASH",
                        "baseTxnId": 17253043342,
                        "firstName": "Masood",
                        "lastName": "Masood Ahmed Wani",
                        "addedOn": "2023-05-06 16:07:40",
                        "phone": "8448480680",
                        "email": "[email protected]",
                        "productInfo": "PBProduct",
                        "errorCode": "E000",
                        "ibiboCode": "FREC",
                        "merchantKey": "iDJYfd",
                        "errorMessage": "No Error",
                        "paymentSource": "payuS2S"
                    },
                    "transactionActionDetails": [
                        {
                            "id": 12071315088,
                            "bankRefNo": "5jeF8wMyZ9jnZ9_12031097474recon__1",
                            "token": "recon_17253043342",
                            "actionType": "refund",
                            "prevStatus": "requested",
                            "amount": 2259.0,
                            "status": "success",
                            "bankArn": "5jeF8wMyZ9jnZ9_12031097474recon__1",
                            "updatedAt": "2023-05-11 11:49:04",
                            "createdAt": "2023-05-06 16:07:40",
                            "settlementId": null,
                            "amountSettled": null,
                            "refundMode": "Back to Source",
                            "settledOn": null,
                            "merchantUTR": null
                        }
                    ]
                }
            ]
        }
    ]
}

Failure scenarios

Transaction not found for normal merchant

{    "message": "Success",    "status": 1,    "result": []}

Transaction not found for aggregator merchant

{    "message": "transaction does not exists",    "status": 0,    "traceId": "10.251.120.218-8081-1-24318369-1-1753192554.523"}

Bad request

{    "timestamp": "2025-07-22T13:56:21.488+00:00",    "status": 400,    "error": "Bad Request",    "path": "/v1/transaction"}

Invalid merchant

{    "message": "There is no merchant with this mid or key",    "request_id": "9d530d367c3b4e749c8f5c2f693d6e55"}

Authentication failure

{    "message": "Unauthorized",    "request_id": "44303808ec378607cdf3ab352d7d0845"}