Refund Transaction API

API Command: cancel_refund_transaction

The Refund Transaction API (cancel_refund_transaction) can be used for the following purposes:

  • Cancel a transaction that is in ‘auth’ state at the moment.
  • Refund a transaction that is in a ‘captured’ state at the moment.

To learn more about different payment states, refer to Payment States Explanations.

In this API: var1 is the Payu ID (mihpayid) of the transaction, var2 should contain the Token ID (unique token from the merchant), and var3 parameter should contain the amount that needs to be refunded.

Environment

Sample request

Simple sample request

curl -X POST "https://test.payu.in/merchant/postservice?form=2
-H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d

"key=JP***g&command=cancel_refund_transaction&var1=403993715521937565&var2=20201105secrettokenaturend&hash=10"

Sample request with split information JSON

curl -X POST "https://test.payu.in/merchant/postservice?form=2" \
-H "accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=JP***g&command=cancel_refund_transaction&var1=403993715521937565&var2=20201105secrettokenaturend&hash=10&var9=child_merchant_key_1:{\"amount\": 100,\"aggregatorRefundAmount\": 40 }"

Sample response

Success Scenarios

  • On successful processing from PayU, the response is similar to the following:
Array 
(
      [status] => 1
      [msg] => Cancel Request Queued 
      [txn_update_id] => <Request ID> 
      [bank_ref_num] => <Bank Reference Number> 
      [mihpayid] => <PayU Transaction ID>
)
  • On successful processing from PayU end for captured transactions, the response is similar to the following:
Array 
(
     [status] => 1
     [msg] => Refund Request Queued 
     [request_id] => Request ID 
     [bank_ref_num] => <Bank Reference Number> 
     [mihpayid] => <PayU Transaction ID>
)

On successful processing at PayU end for auth transactions, the response is similar to the following:

Array 
(
    [status] => 1
    [msg] => Cancel Request Queued 
    [txn_update_id] => <Request ID> 
    [bank_ref_num] => <Bank Reference Number>
)

Failure scenarios

  • If token is missing, the response is similar to the following:
{
      "status": 0,
      "msg": "token is empty",
      "mihpayid": "403993715521937565"
}
  • If amount is missing, the response is similar to the following:
Array 
(
[status] => 0
[msg] => amount is empty 
)
  • If the transaction is not found, the response is similar to the following:
Array 
(
[status] => 0
[msg] => transaction not exists 
)
  • If failed to refund, the response is similar to the following:
Array 
(
       [status] => 0
       [msg] => Refund request failed
)
  • If capture is done on the same day, the response is similar to the following:
Array 
(
    [status] => 1
    [msg]=> Capture is done today, please check for refund status tomorrow 
    [request_id] => Request ID
    [bank_ref_num] => Bank Reference Number
    [mihpayid] => PayU ID
)
  • If the token is invalid, the response is similar to the following:
(
    [status] => 0
    [msg] => token already used or request pending 
)
  • If failed to cancel a transaction, the response is similar to the following:
Array 
(
     [status] => 0
     [msg] => Cancel request failed
)

📘

Notes:

  • The response for Refund Transaction API in Test Environment is similar to the following as it is the limitation with Test Environment:
    • Regular Merchant
      (
          [status] => 1
          [msg] => Refund Request Queued
          [request_id] => 136409872
          [bank_ref_num] => 
          [mihpayid] => 403993715530925893
          [error_code] => 102
      )
      
    • Merchant with Split transaction enabled
{
  "status": 236,
  "msg": "Refund Split Info must be of JSON format",
  "mihpayid": "403993715521937565"
}
Response parameters
ParameterFieldsSample Value
statusThe status can be any of the following:
1 if API call is a success
0 if the API has failed
1
msgThis parameter contains a response message description.Refund Request Queued
request_idThis parameter contains a unique refund ID generated by PayU.6582898821
bank_ref_numThis parameter contains a bank reference number is returned from bank.IRN6601148
mihpayidThis parameter contains a unique transaction ID generated by PayU during sale.7043873219
error_codeThis parameter contains the code for response. For a list of error codes and their description, refer to Refund Error Codes.102

📘

Note:

The error_code ​value 102​ should be treated as success; the rest are failures. To learn more about the possible error codes and their description, refer to Error Codes.

The Refund Details parameter of the response is in JSON format and the parameters in this JSON are described in the following table:

JSON FieldDescriptionExample
Payu_IDThis field contains a unique reference number created for each transaction at PayU’s end. You must note this transaction ID as this will be used as a reference for all the future actions on this transaction like Inquiry or Refund.403993715521937565
RequestIDThis field contains the request ID value posted by the merchant during the transaction request.

- failure - If the API command failed.

- success - If the API command succeeded.
131278422
RefundTokenThis field contains the refund token from bank.20201105secrettokenatur
Payment GatewayThis parameter gives information on the payment gateway used for the transaction.AXISPG
AmountThis parameter contains the original amount which was sent in the transaction request by the merchant.10.00
StatusThis parameter contains any of the the following status based on whether the API command was successful or failed to get response:success
Refund_CreationDateThis parameter contains the time stamp of refund initiation from PayU when the merchant requested. The format of the time stamp is YYYY-MM-DD HH:MM:SS.2020-11-05 01:23:19
bank_ref_numFor each successful transaction – this parameter contains the bank reference number generated by the bank.527013524405
bank_arnThis parameter contains the Acquirer Reference Number (ARN) is a unique number is generated by the bank. This ARN is generated within 24-72 business hours of initiating the refund.0084129821
settled_atThis parameter contains the transaction settlement time stamp. The format of the time stamp is YYYY-MM-DD HH:MM:SS.2020-11-05 01:24:04

Request parameters

Reference information and other request parameters
ParameterReference
keyFor more information on how to generate the Key and Salt, refer to any of the following:

- Production: Generate Merchant Key and Salt

- Test: Generate Test Merchant Key and Salt
hashHash logic for this API is:
sha512(key|command|var1|salt)
sha512

Other request parameters

Other request parameters used for Refund Transaction API (which are not in the below form for Try It experience) are listed in the following table:

ParameterDescription
var2This 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.
var3For captured transaction:
This parameter must contain the amount which needs to be refunded. Both partial and full refunds are allowed.

For a partial refund, this var3 value would be less than the amount with which the transaction was made.

- For a full refund: The var3 value would be equal to the amount with which the transaction was made.


- For pre-auth transaction: 
If the transaction is in a pre-auth state currently, the full cancellation is allowed. The amount must be the same as the auth amount. A partial amount would not be allowed.
var5If a refund callback for a transaction is required on a specific URL, the URL must be specified in this parameter.
var6This parameter must contain the details of customer and funds need to be credited in a JSON format.
Note: This parameter is mandatory for instant refunds where the JSON format is similar to the following:
{"refund_mode":"2","be neficiary_full_name":""," beneficiary_account":"", "beneficiary_ifsc":""}
var8:
mandatory for split
Refund split information provided by merchant in a JSON format. This is applicable only with the Split transactions. The JSON format is described in the next able.

The var8 parameter is in a JSON format that contains the fields described in the following table:

FieldDescriptionExample
Split 1 DetailsThe child merchant key, amount and aggregator refund amount is specified in the following format:
child_merchant_key_1":{ "amount": 100, aggregatorRefundAmount: 40 }
Note: The aggregator refund amount is optional in this field.
child_merchant_key_1": { "amount": 100, aggregatorRefundAmount: 40 }
Split 2 DetailsThe child merchant key, amount and aggregator refund amount is specified similar to Split 1 details.child_merchant_key_2": {"amount": 20, aggregatorRefundAmount: 0 }

Sample JSON for var8

{ "child_merchant_key_1": { "amount": 100, aggregatorRefundAmount: 40 }, "child_merchant_key_2": {"amount": 20, aggregatorRefundAmount: 0 }}

📘

Reference:

var5, var6 and var8 are optional parameters and not included in the following Try It experience. For more information on description with examples, refer to the Other request parameters subsection.

Example values

Use the following sample values while trying out the API:

  • var1 (mihpayid): 403993715521937565
  • var2 (reference number for a refund provided by merchant): 20201105secrettokenaturend
Language
Click Try It! to start a request and see the response here!