Instant Delivery Notification (IDN)

Overview

Use Instant Delivery Notifications (IDN) to automate the confirmation of order fulfillment/delivery to 2Checkout for products and subscriptions plans which you configured by opting for the Fulfillment made by you option. IDNs facilitate automatic delivery confirmations from your system directly into 2Checkout which logs them at the order level.

Availability

All 2Checkout accounts.

Workflow

1

Step

Shoppers purchase your products/subscription plans.

2

Step

2Checkout handles the transaction, collects the payment, and generates Instant Payment Notifications (IPNs).

3

Step

2Checkout stops processing the order reflected in the order status: in progress until you fulfill/deliver the purchase.

4

Step

Once you finalize fulfillment/delivery, you can confirm the action to 2Checkout either manually in the Control Panel or by creating a script that automatically sends a POST request to 2Checkout.

5

Step

2Checkout provides an answer to your POST request either inline or using GET at a URL on your server where you can place a listener to interpret the result.

6

Step

2Checkout finalizes order processing after receiving your fulfillment/delivery confirmation.

Requirements

• Authenticate each HTTPS POST by using an HMAC_SHA256 signature based on the data contained in the POST and your account's merchant code and secret key.

• As soon as 2Checkout confirms your orders through IPN or via email, send standalone HTTPS POST requests to 2Checkout to the IDN URL for the orders you fulfill/deliver yourself, confirming that shoppers received their product files/activation key/access to your service/etc. Include identification data for the order fulfillment/delivery you're confirming (details below).

Method and URL

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

POST Operation Data

The identification data contained in the POST is sent in the following exact order:

Parameter	Description
MERCHANT	Your merchant code.
ORDER_REF	Unique, system-generated 2Checkout order reference.
ORDER_AMOUNT	The total order value of the purchase for which you're confirming fulfillment/delivery.
ORDER_CURRENCY	Order currency ISO 4217 code.
IDN_DATE	The date when you're sending the delivery confirmation request. Format: Y-m-d H:i:s Y - year (4 digits). M - month (2 digits). D - day (2 digits). H - hour (00–24, 2 digits). I - minute (2 digits). S - second (2 digits). If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the IDN_DATE will be calculated according to your custom configuration. 2Checkout will use your custom set time zone for the IDN_DATE when calculating the HASH, and it's important that you also use the same datetime stamp per the custom time zone. The default 2Checkout API time zone is GMT+02:00.
ORDER_HASH	Represents the request's signature, an HMAC_SHA256 built from all fields above.
SIGNATURE_ALG	Required. The hashing algorithm used to authenticate the request. To use SHA2 or SHA3 for auth, pass SHA2 or SHA3 as value for the SIGNATURE_ALG parameter.
REF_URL*	Optional. To get the 2Checkout response inline do not include this parameter in the POST or leave it empty. Otherwise, populate it with the URL address where you placed a listener on your server capable of interpreting the 2Checkout response delivered using GET. The URL address must begin with http:// or https://.
LICENSE_CODE	OPTIONAL - the 2Checkout License Reference - unique identifier for a license/subscription (max 50 chars) in the 2Checkout system. Can be used to confirm fulfillment/delivery only for partner orders. Send the 2Checkout License Reference string for which you're confirming fulfillment/delivery. Confirmation of partner orders can be done one subscription at a time. Note: If used, LICENSE_CODE is also included when the HASH signature is calculated. Not available for eStore.

ORDER_HASH example

Field Name	Length	Field Value
MERCHANT	4	Test
ORDER_REF	7	1000500
ORDER_AMOUNT	6	225000
ORDER_CURRENCY	3	ROL
IDN_DATE	19	2004-12-16 17:46:56
Secret key for this example	—	AABBCCDDEEFF
The source string for the MAC calculation is given by adding the string length at the beginning of the field:	—	4TEST7100050062250003ROL192004-12-16 17:46:56
Final SHA256 value	—	3d37f0d7819dbde48ff4c8910bb153ec

Response example

2Checkout calculates the response for the data in the ORDER_HASH example similarly but with less information. The source string data:

Field Name	Length	Field Value
ORDER_REF	7	1000500
RESPONSE_CODE	1	1
RESPONSE_MSG	9	Confirmed
IDN_DATE	19	2004-12-16 17:46:58
Resulting string	—	71000500119Confirmed192004-12-16 17:46:58
Resulting SHA256 HASH value	—	d317bb75d8f1d7fd203314914621c17c

The HASH fields can contain both lowercase and uppercase characters (hexadecimal string).

The INLINE reply from the 2Checkout server:

Inline reply example

<EPAYMENT>1000500|1|Confirmed|2004-12-16 17:46:58|d317bb75d8f1d7fd203314914621c17c</EPAYMENT>

The GET reply:

GET reply example

https://www.mysite.com/prel.php?ORDER...NSE_CODE=1&RESPONSE_MSG=Confirmed&IDN_DATE=2004-12-16 17:46:58&ORDER_HASH=d317bb75d8f1d7fd203314914621c17c

IDN Response Codes and Messages

2Checkout does not log orders as confirmed when you receive an invalid reply.

Response code	Response message
1	Confirmed
2	ORDER_REF missing or incorrect
3	ORDER_AMOUNT missing or incorrect
4	ORDER_CURRENCY is missing or incorrect
5	IDN_DATE is not in the correct format
6	Error confirming order
7	Order already confirmed
8	Unknown error
9	Invalid ORDER_REF
10	Invalid ORDER_AMOUNT
11	Invalid ORDER_CURRENCY

Working example

PHP example

<?php

$algo = 'sha256'; // or sha3-256
$merchantCode = 'merchant';
$key = "secret_key";

$orderref = 1234567;
$date = date('Y-m-d H:i:s');
$eur = 'EUR';
$amount = 99.99;

$string = strlen($merchantCode) . $merchantCode . strlen($orderref) . $orderref . strlen($amount) . $amount . strlen(
        $eur
    ) . $eur . strlen($date) . $date;
$hash = hash_hmac($algo, $string, $key);

$idn = array(
    'MERCHANT'       => $merchantCode,
    'ORDER_REF'      => $orderref,
    'ORDER_AMOUNT'   => $amount,
    'ORDER_CURRENCY' => $eur,
    'SIGNATURE_ALG'  => $algo,
    'IDN_DATE'       => date('Y-m-d H:i:s')
);

$idn['ORDER_HASH'] = $hash;

$dataels = array();
foreach (array_keys($idn) as $thiskey) {
    $dataels[] = urlencode($thiskey) . "=" . urlencode($idn[$thiskey]);
}
$data = implode("&", $dataels);

var_dump($data);

$connectionToUrl = curl_init();
curl_setopt($connectionToUrl, CURLOPT_URL, "https://secure.2checkout.com/order/idn.php");
curl_setopt($connectionToUrl, CURLOPT_HEADER, false);
curl_setopt($connectionToUrl, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($connectionToUrl, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($connectionToUrl, CURLOPT_SSLVERSION, 0);
curl_setopt($connectionToUrl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($connectionToUrl, CURLOPT_VERBOSE, 0);
curl_setopt($connectionToUrl, CURLOPT_POST, 1);
curl_setopt($connectionToUrl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($connectionToUrl, CURLOPT_POSTFIELDS, $data);

$returnConnectionPost = curl_exec($connectionToUrl);
curl_close($connectionToUrl);

var_dump($returnConnectionPost);