Instant Refund Notification (IRN)

Overview

Use Instant Refund/Reverse Notifications (IRN) to automate the process of requesting:

• Transaction reversals

• Full refunds

• Partial refunds

The IRNs let you send refund and reversal requests directly from your own management interface/platform into the 2Checkout system.

Once 2Checkout approves the REVERSE/REFUND procedure, we send you an email and an IPN notification containing the status corresponding to the canceled transaction, REVERSE or REFUND, respectively. We display the total canceled amount as a negative value.

Reversal

A reversal involves 2Checkout unblocking the shopper's balance corresponding to the transaction that we authorized for future capture immediately after payment confirmation, following approval from the financial department. Reversals happen before 2Checkout captures the authorized amount and also precedes order fulfillment/delivery. 2Checkout does not charge transaction processing commissions for orders that we reverse. Such orders feature the REVERSED status in the 2Checkout Control Panel as well as in all notifications regarding the reversal.

Refund

2Checkout can only refund completed transactions associated with finalized orders (fulfilled/delivered).

Method and URL

POST: https://secure.2checkout.com/order/irn.php

Authentication

You're required to validate each request with a HASH (HMAC_SHA256 signature). To build the HMAC_SHA256 source string, prepend each required value with its own length in bytes.

• Use 0 for null or empty values without prepending their length. However, when the value is 0 (zero), you do need to prepend its length (1).

• Note that for UTF-8 characters the length in bytes can be longer than the string length.

IRN HASH example

For the purposes of this example, we assume that the values of the secret key are 123456789!@#$%^&*. Your secret key is available in the Account Settings area of your account.

Field name	Length	Field value
MERCHANT	8	MERCCODE
ORDER_REF	8	12345678
ORDER_AMOUNT	5	39.99
ORDER_CURRENCY	3	USD
IRN_DATE	19	2012-12-12 12:12:12
PRODUCTS_IDS	5	35386 and 35387 in an array
PRODUCTS_QTY	1	1 and 2 in an array
REGENERATE_CODES	19	1234-5678-9012-3456
LICENSE_HANDLING	6	CANCEL

Parameters to be included in the HASH signature

$params = array(
  'MERCHANT' => 'MERCCODE',
  'ORDER_REF' => 12345678,
  'ORDER_AMOUNT' => 39.99,
  'ORDER_CURRENCY' => 'USD',
  'IRN_DATE' => '2012-12-12 12:12:12',
  'PRODUCTS_IDS' => array(35386, 35387),
  'PRODUCTS_QTY' => array(1, 2),
  'REGENERATE_CODES' => array('1234-5678-9012-3456'),
  'LICENSE_HANDLING' => array('CANCEL')
);

Serialized string for hash

8MERCCODE812345678539.993USD192012-12-12 12:12:125353865353871112191234-5678-9012-34566CANCEL

Hash:

e24fe2f3a2fadcd375be2fc9410d48fe

Parameters

Include parameters in the request in the exact order featured below.

Field	Type/Required	Description	Used in HASH calculation
MERCHANT	String/Required	Merchant ID. This is available in the "Account administration" / "Account settings" section of the Control Panel	YES
ORDER_REF	String/Required	The unique reference number of the order from the 2Checkout system for which you’re initiating a refund request.	YES
ORDER_AMOUNT	Double/Required	The total value of the order (total costs customers incurred for the order) for which you’re requesting a reverse/refund. You can refund a different amount and not necessarily the entire value of the order, and you would specify the funds using the AMOUNT parameter.	YES
ORDER_CURRENCY	String/Required	The currency used for the order.	YES
IRN_DATE	String/Required	The date of the refund request in the following format: Y-m-d H:i:s (2008-05-10 17:30:56). If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then calculate the IRN_DATE according to your custom configuration. 2Checkout uses your custom time zone for the IRN_DATE when calculating the HASH, and it's important that you also use the same datetime stamp, also per the custom time zone. The default 2Checkout API time zone is GMT+02:00 (EET).	YES
ORDER_HASH	String/Required	The HMAC_SHA256 signature for the transmitted data.	-
SIGNATURE_ALG	String/Required	The hashing algorithm used to authenticate the request. In order to use SHA2 or SHA3 for auth, simply pass SHA2 or SHA3 as value for the SIGNATURE_ALG parameter	NO
REF_URL	String/Optional	You have the option of setting a URL where 2Checkout sends the response to your IRN request using GET. Make sure to host a listener capable of interpreting the response. (http://www.my-site.com/irn.php) If you do not use this parameter, 2Checkout displays the answer inline.	NO
PRODUCTS_IDS	Array/Optional for full refund/Required for partial refunds	When included, it cannot be empty. Array with the product(s) ID for which you send the reverse/refund request. Number of PRODUCTS_IDS array elements much match those of the PRODUCTS_QTY array. For total refunds, 2Checkout validates product identifiers, and they need to belong to the products purchased in the same order. Include identifiers for all products in the order. For partial refunds, include only the IDs for the products that you want to refund.	YES only if included in the request
PRODUCTS_QTY	Array/Optional/Required when you use PRODUCTS_IDS	When included, it cannot be empty. Array with corresponding quantities for product(s) mentioned in PRODUCTS_IDS. Number of PRODUCTS_QTY array elements much match those of the PRODUCTS_IDS array. Quantities cannot exceed those of items purchased as part of the order you’re refunding. For example, to refund $500 for 1 unit of product A (which was purchased 2 units at $1000), PRODUCTS_QTY needs to be 1. For total refunds, match the value of PRODUCTS_QTY to the total number of units per product purchased with that order.	YES only if included in the request
REGENERATE_CODES	String/Optional	Array with codes you want 2Checkout to reallocate to the static list associated with the product. Ignore if you use dynamic lists. For dynamic lists of activation codes/keys, 2Checkout does not generate an error if you include the parameter. This applies to HASH calculation as well.	YES only if included in the request.
LICENSE_HANDLING	Array/Optional	For regular products: array containing the action that 2Checkout should carry out regarding the subscriptions/licenses generated with the customer’s purchase. For bundles set to generate subscriptions/licenses for each bundled product, LICENSE_HANDLING should be an array of an array. Possible values: CANCEL (cancels the subscription/license immediately) or NONE (leave unchanged). If LICENSE_HANDLING is empty, the 2Checkout system interprets the value as NONE. 2Checkout correlates impact on subscriptions based on the values you send using LICENSE_HANDLING with the product identifiers you set using PRODUCTS_IDS. See the parameter description for examples.	YES only if included in the request
AMOUNT	Double or Array/Required	Double (Float) - a single value for total refunds ('AMOUNT' => '150.00') - in this case AMOUNT (equal to ORDER_AMOUNT) needs to match the total value of the order. Or, array with the specific amounts that will be refunded to customers only for partial refunds. When issuing partial refunds, PRODUCTS_IDS is mandatory. The amounts reimbursed to customers must match the products for which the refund/reverse is made. If AMOUNT is missing, then the entire value of the order (ORDER_AMOUNT) will be refunded. See examples in the parameter description.	YES
REFUND_REASON	String/Optional	Refund reason. Include one of the refund reasons predefined by our platform: Chargeback, Duplicate order, Not satisfied with the product, Product not received, Unwanted auto-renewal, Technical issue with the product, Other, No reason. If you have set your own refund reasons, you can include one of your custom reasons defined. An error is thrown if you send a refund reason which is not part of the list predefined by 2Checkout, or a reason customized by you. Can be null.	YES only if included in the request

Response

2Checkout validates your request by showing a response in the page that receives the information, under the following format:

<EPAYMENT>ORDER_REF|RESPONSE_CODE|RESPONSE_MSG|IRN_DATE|ORDER_HASH </EPAYMENT>

The parameters in the validation signature 2Checkout sends:

Parameter	Description
ORDER_REF	The order reference in the 2Checkout system, received through IRN
RESPONSE_CODE	The answer code for the order reverse request
RESPONSE_MSG	The answer to the order reverse request
IRN_DATE	The date of the answer to the order reverse request, in the following format: YYYY-MM-DD HH:mm:ss (24 hour format) (Ex: 2009-01-30 11:33:37). If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the IRN_DATE will be calculated according to your custom configuration. 2Checkout will use your custom set time zone for the IRN_DATE when calculating the HASH, and it's important that you also use the same datetime stamp, also per the custom time zone. Note: The default 2Checkout API time zone is GMT+02:00
ORDER_HASH	The HMAC_SHA256 data validation signature

If the 2Checkout response is set to be sent to a specific URL (the REF_URL parameter contains a valid URL), the reply will be sent as follows:

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&ORDER_HASH=value

Secret key example:

Secret key: 123456789!@#$%^&*

Example response:

<EPAYMENT>12345678|1|OK|2012-12-12 12:12:12</EPAYMENT>

Serialized string for hash:

812345678112OK192012-12-12 12:12:12

Hash:

e8324511d50f0f78a0a20aca28295290

IRN response codes and messages

Response code	Response 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 canceling order
7	Order already canceled
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	You have already placed a Total refund for this order.
20	You have already placed a refund for this order.
21	You already have a pending refund request.
22	The maximum refundable amount for this order has been exceeded.
23	You cannot place a refund request due to the order's current status.
24	You cannot place a refund request due to the order's payment details.
25	The allowed period to request a new refund for this order has expired.
26	Multiple refunds are not supported by this order's payment type.
27	Refunding not supported for this Cross Vendor Sale order.
28	Order total is negative.
29	You cannot place a refund request due to the order's approval status.
30	Multiple refunds are not supported by this order's terminal.
31	Partial reverse is not supported.
32	Invalid product type. Refunds are available only for the following product types: REGULAR / BUNDLE / MEDIA / DOWNLOAD_INSURANCE, but not for DISCOUNT / SHIPPING.
33	You cannot request a refund because a chargeback dispute was open for the order.
34	Invalid REFUND_REASON
*	Access not permitted!

*In some cases “Response message” does not have a “Response code”.

Batch refunds/reversals

Batch processing is not supported. You need to send standalone requests for every reverse or total/partial refund.

PHP code samples

Total refund

total_refund.php

<?php

function SerializeArray($myarray, $strip_slashes = true, $elementsToProcess = null)
{
    $retvalue = "";
    if ($elementsToProcess !== null && is_array($elementsToProcess)) {
        $_myarray = $myarray;
        $myarray = array();

        foreach ($elementsToProcess as $key) {
            if (!isset($_myarray[$key])) {
                continue;
            }
            $myarray[$key] = $_myarray[$key];
        }
    }
    foreach ($myarray as $val) {
        if (is_array($val)) {
            $retvalue .= SerializeArray($val, $strip_slashes);
        } else {
            $size = ($strip_slashes) ? strlen(StripSlashes($val)) : strlen($val);
            $retvalue .= ($strip_slashes) ? $size . StripSlashes($val) : $size . $val;
        }
    }

    return $retvalue;
}

$key = "SECRET_KEY";

$algo = "sha256"; // or sha3-256

$irn = array(
    'MERCHANT'       => 'MERCHANT',
    'ORDER_REF'      => 12345678,
    'ORDER_AMOUNT'   => 11.00,
    'ORDER_CURRENCY' => 'USD',
    'IRN_DATE'       => date('Y-m-d H:i:s'),
    'SIGNATURE_ALG'  => $algo,
    'REFUND_REASON'  => 'Other' // send one of the 2Checkout predefined reasons, or your customized reason
);

$process = array(
    'MERCHANT',
    'ORDER_REF',
    'ORDER_AMOUNT',
    'ORDER_CURRENCY',
    'IRN_DATE',
    'PRODUCTS_IDS',
    'PRODUCTS_QTY',
    'REGENERATE_CODES',
    'LICENSE_HANDLING',
    'AMOUNT'
);
$string = SerializeArray($irn, true, $process);

$hash = hash_hmac($algo, $string, $key);

$irn['ORDER_HASH'] = $hash;

$dataels = array();

$data = http_build_query($irn); $curl = curl_init("https://secure.2checkout.com/order/irn.php");
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl, CURLOPT_SSLVERSION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_PROXY, '');
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
$responseString = curl_exec($curl);

var_dump($responseString);

Multiple partial refunds

partial_refunds.php

<?php

function SerializeArray($myarray, $strip_slashes = true, $elementsToProcess = null)
{
    $retvalue = "";
    if ($elementsToProcess !== null && is_array($elementsToProcess)) {
        $_myarray = $myarray;
        $myarray = array();

        foreach ($elementsToProcess as $key) {
            if (!isset($_myarray[$key])) {
                continue;
            }
            $myarray[$key] = $_myarray[$key];
        }
    }
    foreach ($myarray as $val) {
        if (is_array($val)) {
            $retvalue .= SerializeArray($val, $strip_slashes);
        } else {
            $size = ($strip_slashes) ? strlen(StripSlashes($val)) : strlen($val);
            $retvalue .= ($strip_slashes) ? $size . StripSlashes($val) : $size . $val;
        }
    }

    return $retvalue;
}

$key = "SECRET_KEY";

$algo = "sha256"; // or sha3-256

$irn = array(
    'MERCHANT'       => 'MERCHANT',
    'ORDER_REF'      => 12345678,
    'ORDER_AMOUNT'   => 11.00,
    'ORDER_CURRENCY' => 'USD',
    'IRN_DATE'       => date('Y-m-d H:i:s'),
    'PRODUCTS_IDS'   => array(1119321, 2225673),
    'PRODUCTS_QTY'   => array(1, 1),
    'SIGNATURE_ALG'  => $algo,
    'AMOUNT'         => array('1.00', '5.00')
);

$process = array(
    'MERCHANT',
    'ORDER_REF',
    'ORDER_AMOUNT',
    'ORDER_CURRENCY',
    'IRN_DATE',
    'PRODUCTS_IDS',
    'PRODUCTS_QTY',
    'REGENERATE_CODES',
    'LICENSE_HANDLING',
    'AMOUNT'
);
$string = SerializeArray($irn, true, $process);

$hash = hash_hmac($algo, $string, $key);

$irn['ORDER_HASH'] = $hash;

$dataels = array();

$data = http_build_query($irn);

$curl = curl_init("https://secure.2checkout.com/order/irn.php"); curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl, CURLOPT_SSLVERSION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_PROXY, '');
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
$responseString = curl_exec($curl);

var_dump($responseString);