Skip to main content

Instant Delivery Notification (IDN)

Instant Delivery Notification (IDN)

Last updated: 15-Mar-2024
Rate this article:

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. Shoppers purchase your products/subscription plans.
  2. 2Checkout handles the transaction, collects the payment, and generates Instant Payment Notifications (IPNs). 
  3. 2Checkout stops processing the order reflected in the order status: in progress until you fulfill/deliver the purchase. 
  4. 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. 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. 2Checkout finalizes order processing after receiving your fulfillment/delivery confirmation. 

Requirements

  • Authenticate for each  request. 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 the fact that shoppers received their product files/activation key/access to your service/etc. Include identification data for the order fulfillment/delivery you're confirming (read more below).

Method and URL

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

POST Operation Data

The identification data contained in the POST is found in the following table and it 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. 

IDN_DATE

The date when you're sending the delivery confirmation request. Format: Y-m-d H:i:s 

Y - Represent the year. 4 digit number.

M - Represents the month. 2 digit number.

D - Represents the day. 2 digit number.

H - Represents the hour. Values from 00 to 24. 2 digit number.

I - Represents the minute. 2 digit number.

S - Represents the second. 2 digit number.

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, also 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. In order to use SHA2 or SHA3 for auth, simply pass SHA2 or SHA3 as value for the SIGNATURE_ALG parameter.

REF_URL*

Optional. The 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 respponse delivered using GET. The URL address must begin with the http:// or https://.

LICENSE_CODE

OPTIONAL - the 2Checkout License Reference - the unique identifier for a license/subscription (maximum 50 characters) 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. The confirmation of the fulfillment/delivery 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:

Filed 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:

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

The GET reply:

http://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

$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, "http://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); 
Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo