Skip to main content
knowledgecenter.avangate.com

Instant Delivery Notification (IDN)

Overview

Use Instant Delivery Notifications (IDN) to automate the confirmation of order fulfillment/delivery to Avangate 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 Avangate which logs them at order level.

Availability

All Avangate accounts. 

Workflow

  1. Shoppers purchase your products/subscription plans.
  2. Avangate handles the transaction, collects the payment and generates Instant Payment Notifications (IPNs). 
  3. Avangate 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 Avangate either manually in the Control Panel or by creating a script that automatically sends a POST request to Avangate.
  5. Avangate 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. Avangate finalizes order processing after receiving your fulfillment/delivery confirmation. 

Requirements

  • Authenticate for each  request. Authenticate each HTTPS POST by using a HMAC_MD5 signature based on the data contained in the POST and your account's merchant code and secret key
  • As soon as Avangate confirms your orders through IPN or via email, send standalone HTTPS POST requests to Avangate 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).

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 Avangate 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 Avangate API by editing system settings under Account settings, then the IDN_DATE will be calculated according to your custom configuration. Avangate 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 Avangate API time zone is GMT+02:00.

ORDER_HASH

Represents the requests signature, a HMAC_MD5 built from all fields above.

REF_URL*

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

LICENSE_CODE

OPTIONAL - the Avangate License Reference - the unique identifier for a license/subscription (maximum 50 characters) in the Avangate system.

Can be used to confirm fulfillment/delivery only for partner orders. Send the Avangate 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 MD5 value 3d37f0d7819dbde48ff4c8910bb153ec

 

Response example

Avangate 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 MD5 HASH value d317bb75d8f1d7fd203314914621c17c
 

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

The INLINE reply from the Avangate 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

 Avangate 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
 
function hmac ($key, $data){
       $b = 64; // byte length for md5
       if (strlen($key) > $b) {
           $key = pack("H*",md5($key));
       }
       $key  = str_pad($key, $b, chr(0x00));
       $ipad = str_pad('', $b, chr(0x36));
       $opad = str_pad('', $b, chr(0x5c));
       $k_ipad = $key ^ $ipad ;
       $k_opad = $key ^ $opad;
       return md5($k_opad  . pack("H*",md5($k_ipad . $data)));
    }
               
$merchantCode = 'YourMerchantCode';
$key = "YourSecretKey_12345" ;
               
$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 = hmac($key, $string);
 
 
                $idn = array(
            'MERCHANT' => $merchantCode,               
            'ORDER_REF' => $orderref,
            'ORDER_AMOUNT' => $amount,
            'ORDER_CURRENCY' => $eur,
            'IDN_DATE' => date('Y-m-d H:i:s')
                );
 
       
    $idn['ORDER_HASH'] = $hash;
 
                  $dataels = array();
        foreach (array_keys($idn) as $thiskey) {
            array_push( $dataels, urlencode($thiskey) ."=". urlencode($idn[$thiskey]) );
        }
        $data = implode("&",$dataels);
                               
                                var_dump ($data);
                                
        $connectionToUrl = curl_init();
        curl_setopt($connectionToUrl, CURLOPT_URL, "https://secure.avangate.com/order/idn.php");
        curl_setopt($connectionToUrl, CURLOPT_HEADER, FALSE);
        curl_setopt($connectionToUrl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($connectionToUrl, CURLOPT_SSL_VERIFYHOST, 0);
        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);