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:

ORDER_HASH example

Response example

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

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:

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.

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, "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); 

Overview

Use the deleteSkuCodeByDetails method to remove an SKU based on its included details. 

When requesting to delete SKU by details, the 2Checkout system will delete all SKU defined under the specific product code or pricing configuration code. If the combination does not contain any SKU defined, the system will return an error with the result. The method supports multiple combinations of product code, pricing configuration code in one call.

Request Parameters

Request Example 

Response Parameters

Response Example

Overview

Retrieve information and manage subscriptions for your account. 

Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Parameters

Overview

Use the enableSubscription method to enable a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

$jsonRpcRequest = array (
'method' => 'enableSubscription',
'params' => array($sessionID, $subscriptionReference),
'id' => $i++,
'jsonrpc' => '2.0');

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

This guide provides some integration use cases for the 2Pay.js drop-in payments solution.

Overview

Use the savePrices method to update product prices for a specific pricing configuration.

Parameters

Response

bool(true)

<?php
require ('PATH_TO_AUTH');

/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Dynamic pricing configuration
 *
 * Send two prices, including the required one for the default currency
 * The method will append the prices for the sent entries, without removing the previous values
 *
 * If the quantities intervals were not defined then they will be set.
 * If the quantities overlap with existing defined intervals, an Exception will be thrown.
 */
 
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 140;
$Price->Currency = 'USD';
$Prices[] = $Price;
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 10;
 
$PriceOptions = array();
 
$PricingConfigurationCode = '5553603382';
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);

$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
// will output:
// bool(true)

 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the VOLTAGE pricing option group assigned and marked as required.
 * If prices are sent WITHOUT setting the pricing option group and options will set the price but without setting values for the options prices.
 */
 
// Call the login method for authentication
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
 
$i = 1; // counter for api calls
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
$sessionID = callRPC($jsonRpcRequest, $host);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
// if PricingOption group is not required, will set price for combination of QuantityInterval - no-pricing-option-value.
$PriceOptions = array();
 
// if PricingOption group is required, then send options by assigning a PriceOptionsAssigned object (group code and options)
// $optionAssigned = new stdClass(); // PriceOptionsAssigned
// $optionAssigned->Code = 'VOLTAGE';
// $optionAssigned->Options = array('220V'); // radio option group
// $PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the COLOR and scalenotmandatory pricing option group assigned and marked as required.
 */
// Call the login method for authentication
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
 
$i = 1; // counter for api calls
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
$sessionID = callRPC($jsonRpcRequest, $host);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 10;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'COLOR'; // checkbox pricing option group, multiple values are allowed
$optionAssigned->Options = array('cyan', 'magenta');
$PriceOptions = array($optionAssigned);
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'scalenotmandatory'; // interval pricing option group
$optionAssigned->Options = array('scalenotmandatory-1-5');
$PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PriceOptions = array();
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
?>

Overview

Use the searchCrossSellCampaigns method to extract information about the cross-sell campaigns you configured.

Parameters

Response

Request

<?php
declare(strict_types=1);

// Start clear CLI
echo chr(27).chr(91).'H'.chr(27).chr(91).'J';
// End clear CLI

$executionStartTime = microtime(true);

class Configuration
{
    public const MERCHANT_CODE = 'your_merchant_code';
    public const MERCHANT_KEY = 'your_merchant_key'';

    public const URL = 'http://api.avangate.local/rpc/6.0';
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private const GET_CROSS_SELL_CAMPAIGN = 'getCrossSellCampaign';

    private int $calls = 1;

    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);

        return compact('merchantCode', 'date', 'hash');
    }

    public function login()
    {
        $payload = $this->generateAuth();
        $response = $this->callForRpc(Configuration::URL, self::LOGIN_METHOD, array_values($payload));

        return $response['result'];
    }


    private function callForRpc(string $url, string $action, ?array $payload = null)
    {
        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);

        $headers = [
            'Content-Type: application/json',
            'Accept: application/json',
            'Cookie: XDEBUG_SESSION=PHPSTORM'
        ];

        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if (empty($response)) {
            die('Server unavailable');
        }

        echo "\n\r Method " . $action . " result: \n\r";
        echo $response . "\n\r";

        return json_decode($response, true);
    }

    public function getCrossSellCampaign($sessionId, $crossSellCampaignCode)
    {
        $response = $this->callForRpc(
            Configuration::URL,
            self::GET_CROSS_SELL_CAMPAIGN,
            [$sessionId, $crossSellCampaignCode]
        );

        return $response['result'];
    }
}

$crossSellCampaignCode = '2Xrl83J0k+qOr3W1ceTwZnHHr30=';
$client = new Client();

$sessionId = $client->login();

$result = $client->getCrossSellCampaign($sessionId, $crossSellCampaignCode);
var_dump("GET CROSS SELL CAMPAIGN BY CODE: \n\r", json_encode($result, JSON_PRETTY_PRINT));

$executionEndTime = microtime(true);

// The duration will be displayed in seconds and milliseconds.
$seconds = round($executionEndTime - $executionStartTime, 2);

// Print it out
echo "\n\rThis script took $seconds to execute.\n\r";

Overview

Use the cancelSubscription method to disable an active subscription. Avangate disabled the subscription immediately and no longer performs any recurring billing actions.

Parameters

Response

Request

<?php
$host   = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

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 = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$subscriptionReference = 'F27CFE06ED';
try {
    $disableSubscription = $client->cancelSubscription($sessionID, $subscriptionReference);
}
catch (SoapFault $e) {
    echo "disableSubscription: " . $e->getMessage();
    exit;
}
var_dump("disableSubscription", $disableSubscription);

Overview

Use the getInvoices method to extract shopper invoices from the Avangate system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).

getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.

In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$reference = 'ORDER_REFERENCE';

$jsonRpcRequest = array (
'method' => 'getInvoices',
'params' => array($sessionID, $Reference),
'id' => $i++,
'jsonrpc' => '2.0');

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

Response