Last update: Jan 14th, 2015
Instant Refund/Reverse Notification (IRN) makes it possible for you to automate the sending of reverse/refund requests for orders paid through PayU, directly from the order management application/platform.
The process requires the sending of the order information through HTTP POST, validated with a HMAC_MD5, to the following URL: https://secure.payu.ro/order/irn.php
This process has to be executed for each order where an order reversal, partial refund or total refund of the paid amount is required.
The PayU server expects the data packed in the following structure, strictly adhering to the below specified order:
| Parameter | Description |
| MERCHANT | Merchant's ID. Available in the PaVU administration interface, in the "Account administrator" / "Account settings" sections |
| ORDER_REF | Reference number for the order in the PayU system. |
| ORDER_AMOUNT | The order amount that is to be reversed/refunded as it was received by PayU. If this amount ORDER_AMOUNT is smaller than the total amount of the order, a PARTIAL REFUND will be requested. If the ORDER_AMOUNT is equal with the value of the order, a TOTAL REFUND/REVERSE will be issued. |
| ORDER_CURRENCY | The currency in which the order's amount was specified. |
| IRN_DATE | The date when the reverse/refund request is issued, in the following format Y-m-d H:i:s (Ex: 2012-04-26 14:30:56) |
| ORDER_HASH | HMAC_MD5 signature for the sent data. (HMAC defined at: RFC 2104) |
| AMOUNT | Numeric value that states the value of the reverse/refund (sum of all the PRODUCTS_IDS*PRODUCTS_QTY element value). Must include VAT and taxes. Amount should be a strict positive number. |
| MERCHANT_REFUND_REFERENCE | Optional. String value that could be filled with an identifier for the request. |
| LOYALTY_POINTS_AMOUNT | Optional. Numeric value or array that states the value of the reverse/refund in loyalty points. This is available only if the bank supports partial loyalty points payments. (Ex: Garanti Bank) |
| USE_FAST_REFUND |
Optional. Possible values: yes, try, no (default).
Value "yes" means the Fast Refund feature will be used if the merchant and the order terminal support this feature, otherwise an error message will be returned. Value "try" is similar to value "yes" only that it will not return the error. In case the merchant and/or the terminal do not support Fast Refund, the IRN will be registered as a regular refund request. Value "no" is also the default when this parameter is not sent. It will register the IRN as a regular refund request, no matter what settings for Fast Refund exist on the merchant and terminal. This parameter is also included in the request signature calculation. |
| Parameter | Description |
| ORDER_MPLACE_MERCHANT[] | Array filled with merchant codes of each child. |
| ORDER_MPLACE_AMOUNT[] | Array filled with amount that is to be refunded for each child. |
$irn = [
'MERCHANT' => 'MERCHANT',
'ORDER_REF' => 3954142,
'ORDER_AMOUNT' => 39.99,
'ORDER_CURRENCY' => 'USD',
'AMOUNT' => 12.56,
'IRN_DATE' => '2015-06-08 12:10:36',
'ORDER_HASH' => 'da8d210e5be71f16e502164013d9a0ac'
];
$irn = [ 'MERCHANT' => 'MERCHANT', 'ORDER_REF' => 3954142, 'ORDER_AMOUNT' => 39.99, 'ORDER_CURRENCY' => 'USD', 'AMOUNT' => 12.56, 'IRN_DATE' => '2015-06-08 12:10:36', 'LOYALTY_POINTS_AMOUNT' => 10, 'ORDER_HASH' => '26d08f11feedb8c0fb12197542ef370c' ];
$irn = [
'MERCHANT' => 'IRNTEST',
'ORDER_REF' => 162,
'ORDER_AMOUNT' => 200,
'ORDER_CURRENCY' => 'TRY',
'AMOUNT' => 150,
'IRN_DATE' => '2017-03-15 11:30:42',
'LOYALTY_POINTS_AMOUNT' => [
'FBB' => '0.3',
'BNS' => '0.2',
],
'ORDER_HASH' => '6e47053a6d89a603d549b11bf41fb58e'
];
$irn = [
'MERCHANT' => 'MERCHANT',
'ORDER_REF' => 3954142,
'ORDER_AMOUNT' => 39.99,
'ORDER_CURRENCY' => 'USD',
'AMOUNT' => 10,
'IRN_DATE' => '2015-06-08 12:10:36',
'LOYALTY_POINTS_AMOUNT' => 10,
'ORDER_MPLACE_MERCHANT' => [
312,
3345
],
'ORDER_MPLACE_AMOUNT' => [
4,
6
],
'ORDER_HASH' => '50e7017da05cfacb590157fd9b569c4e'
];
REVERSE is the procedure to cancel an order before the moment when the delivery of the products has been confirmed by the Vendor and the products have been delivered to the final customer (Shopper).
In case of a REVERSE, the transaction amount that has been locked after the payment confirmation will get unlocked by PayU after approval by the financial department of the REVERSE procedure and the Vendor will not be charged with the PayU processing commission. The transaction will get a REVERSE status in the PayU administration interface and in the payment notifications. A REFUND is the procedure through which an order is cancelled after the delivery confirmation has been made by the Vendor.
Once the REVERSE/REFUND procedure has been approved for a specific payment, an IPN/email confirmation will be sent to the Vendor, containing the status of the order that has been cancelled [e.g. REVERSE or REFUND) and the total amount that has been cancelled, displayed with a negative value.
We assume to have the following data:
| Field name | Length (in bytes) | Field value |
| MERCHANT | 4 | TEST |
| ORDER_REF | 7 | 1000500 |
| ORDER_AMOUNT | 4 | 223 |
| ORDER_CURRENCY | 3 | RON |
| IRN_DATE | 19 | 2012-04-26 14:30:56 |
| AMOUNT | 5 | 12.56 |
We assume to have parameters for marketplace too:
| Field name | Length (in bytes) | Field value |
| MERCHANT | 4 | TEST |
| ORDER_REF | 7 | 1000500 |
| ORDER_AMOUNT | 4 | 223 |
| ORDER_CURRENCY | 3 | RON |
| IRN_DATE | 19 | 2012-04-26 14:30:56 |
| AMOUNT | 5 | 12.56 |
| ORDER_MPLACE_MERCHANT[0] | 4 | CODE |
| ORDER_MPLACE_MERCHANT[1] | 5 | CODE2 |
| ORDER_MPLACE_AMOUNT[0] | 4 | 12.4 |
| ORDER_MPLACE_AMOUNT[1] | 4 | 13.8 |
In order to validate the sent data, a HMAC_MD5 signature has to be calculated, that will be encoded with the secret key attached to your account. The Secret Key is available in Control Panel, at the "Account Administration" / "Account settings" section [click here].
The source string for the HMAC_MD5 signature is created by prepending each field value (converted to string), with its length, without
"new line" characters (for UTF-8 characters, the string length in bytes may be larger than the number of characters). The order of the fields that
compose the source string who's signature must be calculated, must be the same as in the tables above.
For the data above, the source string is: 4TEST71000500422.53RON192012-04-26 14:30:56512.56
The secret key for data validation is: 1231234567890123
The HMAC_MD5 signature calculated for the data above is: 9599c80ef0928054b5d9dd19cd2f1541
PayU validates the successful receive of the information you sent by putting an answer inline in the page that receives the information, like below:
<EPAYMENT>ORDER_REF|RESPONSE_CODE|RESPONSE_MSG|IRN_DATE|REFUND_REQUEST_ID|ORDER_HASH</EPAYMENT>
<EPAYMENT>3954142|9|Invalid ORDER_REF|2015-06-08 12:10:37|da8576ef2f33b2db095c80f7f4f7f7d1</EPAYMENT>
The parameters in the validation response sent by PayU are:
| ORDER_REF | Order reference in the PayU system received by IRN |
| RESPONSE_CODE | Response code for the reverse/refund request |
| RESPONSE_MSG | Response message for the reverse/refund request |
| IRN_DATE | The date when the order reverse/refund request response has been sent, in the following format: Y-m-d H:i:s (Ex: 2012-04-26 14:30:56) |
| REFUND_REQUEST_ID | Unique request identifier for IRN request. This field will not be sent unless your account is configured on our side to receive it. Please contact us for more information. |
| ORDER_HASH | HMAC_MD5 signature for data validation |
If the REF_URL parameter is sent through IRN and contains a valid URL, the response will be sent to the URL like below: REF_URL = http://www.mysite.com/callback.php
http://www.mysite.com/callback.php?ORDER_REF=value&RESPONSE_CODE=value&RESPONSE_MSG=value&IRN_DATE=value&REFUND_REQUEST_ID=value&ORDER_HASH=value
In case some API limit is defined in PayU system, we also return some specific headers with information about it (see API Limit documentation).
Response codes and messages:
| Code | Message |
| 1 | OK |
| 2 | ORDER_REF missing or format incorrect |
| 3 | ORDER_AMOUNT missing or format incorrect |
| 4 | ORDER_CURRENCY is missing or format incorrect |
| 5 | IRN_DATE is not in the correct format |
| 6 | Error cancelling order |
| 7 | Order already cancelled |
| 8 | Unknown error |
| 9 | Invalid ORDER_REF |
| 10 | Invalid ORDER_AMOUNT |
| 11 | Invalid ORDER_CURRENCY |
| 12 | PRODUCTS_IDS missing or format incorrect |
| 13 | PRODUCTS_QTY missing or format incorrect |
| 14 | Invalid PRODUCTS_QTY |
| 15 | Invalid REGENERATE_CODES |
| 16 | Invalid LICENSE_HANDLING |
| 17 | AMOUNT missing or format incorrect |
| 18 | Invalid AMOUNT |
| 19 | Invalid MERCHANT |
| 20 | IRN Disabled |
| 21 | Extra parameter ORDER_MPLACE_MERCHANT or ORDER_MPLACE_AMOUNT sent |
| 22 | ORDER_MPLACE_MERCHANT missing or format incorrect |
| 23 | ORDER_MPLACE_AMOUNT missing or format incorrect |
| 24 | Invalid ORDER_MPLACE_MERCHANT[] (invalid marketplace seller code) |
| 25 | Invalid ORDER_MPLACE_AMOUNT[] (invalid marketplace seller amount) |
| 26 | ORDER_MPLACE_MERCHANT[] and ORDER_MPLACE_AMOUNT[] not synchronized |
| 27 | Amount mismatch |
| 28 | ORDER_MPLACE_MERCHANT[] contains a duplicate value |
| 29 | Refund allowed time interval has expired for this Order |
| 30 | This payment method does not support refunds |
| 31 | Number of maximum refunds for this order reached |
| 32 | Multiple refund is not allowed for this order or the amount for refunds exceeded the total amount of the order |
| 33 | ORDER_MPLACE_MERCHANT or ORDER_MPLACE_AMOUNT can not be used with PRODUCT_IDS parameter. Refund by product is not allowed for Marketplace order |
| 34 | LOYALTY_POINTS_AMOUNT programs are invalid |
| 35 | Available loyalty points are insufficient to cover requested loyalty points amount for this order |
| 36 | Limit calls for IRN exceeded |
| 37 | Limit calls for IRN exceeded for this merchant |
| 38 | The partial IRN is not supported without products node |
| 39 | The terminal for this order is invalid. |
| 40 | Invalid product amount |
| 41 | Invalid request body |
| 42 | Product SKU does not exist |
| 43 | Product amount, included past refunds, exceeds original amount |
| 44 | Partial IRN is not allowed if order status is AUTHRECEIVED |
| 45 | Marketplace validation against number of products failed |
| 47 | Invalid commission currency for marketplace product |
| 48 | Commission amount exceeds original commission amount |
| 49 | Amount exceeds original amount |
| 50 | Invalid seller for marketplace product |
| 51 | Refund is not allowed because order status is invalid |
| 52 | Invalid marketplace products structure |
| 53 | Invalid installments return amount |
| 54 | Installments product must be specified on root level for this type of request. |
| 55 | Invalid value for Fast Refund parameter |
| 56 | Fast Refund feature is not available |
| 57 | marketplaceV1 and products nodes can't be used together |
| 58 | Invalid value for merchant refund reference parameter. |
| 59 | The additional details have to contain associative parameters |
| 60 | The maximum length for additional details have been exceeded |
| 61 | The maximum number of parameters available for additional details have been exceeded |
| 62 | The maximum length for an additional details field has been exceeded |