Overview

Starting with 2Checkout API 5.0, search methods are including the option of pagination. Pagination has been developed for decreasing the request loading time while allowing you to better handle the returning responses.

How does it work?

Pagination works on all the search methods existing on 2Checkout API 5.0. The default pagination behavior is to display page 1 with 10 results. The maximum number of items displayed on a single page is 200.

Parameters

To use pagination, include the Pagination object inside the search method call, using the parameters below:

Response

The response of search methods that are including pagination will contain a new object, with the following parameters:

Sample request

The below PHP sample includes a search method for subscriptions.

<?php

require('PATH_TO_AUTH');

$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'email@avangate.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default)
$SubscriptionSearch->Pagination = new stdClass();
$SubscriptionSearch->Pagination->Page = 1; // set the number of pages for the response
$SubscriptionSearch->Pagination->Limit = 200; // set the limit for the values from the response

try {
    $accountSubscriptions = $client->searchSubscriptions($sessionID, $SubscriptionSearch);
}
catch (SoapFault $e) {
    echo "accountSubscriptions: " . $e->getMessage();
    exit;
}
var_dump("accountSubscriptions", $accountSubscriptions);

Overview

The object below is returned directly or within a successful response from the following API requests:

Retrieve shipping price

Shipping price object

Overview

Use the addPromotionSources method to define new sources for an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to add sources to
$promotionCode = '';

// Sources array with the source values 
$sources = ['source1', 'source2'];

try {
    $updatedPromotion = $client->addPromotionSources($promotionCode,$sources);
}

catch (SoapFault $e) {
    echo "UpdatedPromotion: " . $e->getMessage();
    exit;
}

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

Place an order with catalog products defined in your Merchant Control Panel and collect the payment using iDEAL.

Requirements

Shoppers in the Netherlands can purchase using iDEAL. The billing country and the order country code have to be NL.

Supported currencies

• EUR

Accepted on other payment flows

One-click (1-click) purchase for iDeal is available in API 6.0.

Workflow

1. Use the getIdealIssuerBanks method for retrieving information on the 2Checkout list of banks that support iDEAL payments. More details about this method here.
2. Shoppers select iDEAL as a payment option in the interface you provide them and select their bank from the list.
3. Create the order object. Use IDEAL as the type of the PaymentDetails object, and include ReturnURL and CancelURL. The BankCode parameter should be added based on the bank selected by the customer, from the array obtained after calling method getIdealIssuerBanks.
4. Use the placeOrder method to send the data to 2Checkout.
5. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING.
6. 2Checkout returns an Order object as the output of the placeOrder method. 
7. Use the PaymentMethod object to create a redirect URL for the shoppers, concatenating the values of the Href and avng8apitoken parameters. Here's an example of the redirect URL:
   

   https://api.2checkout.com/4.0/scripts/ideal/authorize/?avng8apitoken=f56373d92ed6b153
   

8. Customers are directed to the iDEAL payment page, where they have to confirm their payment details before finishing the ordering process.
9. Shoppers are redirected to the RedirectURL from the Order information object. In case the payment fails, shoppers are redirected to the CancelURL. 

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'EUR';
$Order->Country = 'NL';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;

$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'Test Cosmin API';
$Order->BillingDetails->LastName = 'Cosmin API';
$Order->BillingDetails->CountryCode = 'NL';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'cosmin.deftu@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'IDEAL';
$Order->PaymentDetails->Currency = 'EUR';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '91.220.121.21';
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'http://yourreturnurl.com';
$Order->PaymentDetails->PaymentMethod->CancelURL= 'http://yourcancelurl.com';
$Order->PaymentDetails->PaymentMethod->BankCode='RABONL2U+RAB'; // value retrieved based on the bank selected by the customer, from the array obtained after calling method getIdealIssuerBanks.


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

$output = callRPC($jsonRpcRequest, $host);

$idealredirect = $output->PaymentDetails->PaymentMethod->Authorize->Href."/?avng8apitoken=".$output->PaymentDetails->PaymentMethod->Authorize->Params->avng8apitoken;

header('Location:' . $idealredirect);

Overview

3D Secure is a system designed to increase the security of online transactions using cards by checking customer identities before allowing them to finalize the purchase. 3D Secure works by redirecting your customers to pages provided by their banks, where they need to enter additional security tokens or password to trigger the completion of the charge.

By using 3D Secure, you get additional protection from liability for fraudulent card payments, with your customers having to go through an extra layer of authentication.

Introducing Dynamic 3D Secure via API

Starting with 2Checkout API 5.0, your orders placed via API are processed automatically through the Dynamic 3D Secure flow. Dynamic 3D Secure is a mechanism that allows us to evaluate a transaction in real-time based on a range of rule parameters that are able to determine if 3D Secure should be enabled or not.

Based on specific filters set in our backend system, 3D Secure will be enabled or not on a transaction basis in real-time. The list of filters includes:

• Credit card issuing country
• Billing country 
• IP country 
• Order amount

If one of these filters is not matching with the thresholds set in the 2Checkout system, 3D Secure will be enabled. Otherwise, the transaction is considered to be safe and can go through without 3D Secure.

Availability

Placing orders via API with the 3D Secure flow is available starting with version 5 of 2Checkout's API.

Benefits

Place orders via API starting with version 5, and let Dynamic 3D Secure mechanism bring you the following advantages:

• Increased authorization rates – we measured and observed that in specific countries the use of 3D Secure could have an overwhelmingly positive impact (United Kingdom, Russia) while in other countries it has a negative impact (United States, China).
• Mitigated fraud risks – 3D Secure significantly decreased the fraud rate for your incoming orders.
• Less chargeback – the use of 3D Secure can reduce the number of chargebacks in some cases (e.g. reasons like fraud/not recognized) as customers are not allowed to open a chargeback with their bank.

How it works

For credit card orders placed starting with 2Checkout API 5.0, you need to pass through additional parameters that support the Dynamic 3D Secure flow.

1. Once the order has been placed with the customer’s billing details, in order to confirm the payment, the shopper needs to be redirected to a 3D Secure confirmation page. 
2. The URL where the customer needs to be redirected is provided in the API response, in the PaymentMethod object, under the Authorize3DS object. 
3. Here, the redirect URL needs to be created by taking the Href attribute (the URL of the authorization page) and adding the parameters provided in the Params object. 
4. The key-value pairs are the parameters that need to be attached to the URL, where the key is the parameter name and the value is its value. 

For example, for the below parameters:

{
"PaymentMethod": {
    "Authorize3DS": {
    "Href": "https://api.avangate.com/5.0/scripts/credit_card/authorize",
    "Method": "GET",
    "Params": {
        "avng8apitoken": "1234567890abcdef",
            }
        }
    }
}    
    

The URL should be constructed as follows: https://api.avangate.com/5.0/scripts...34567890abcdef.

5. Once the shopper confirms the payment, they will be redirected to the URL provided by you in the Vendor3DSReturnURL. If the payment fails due to 3DS (order could not be validated), then the customer will be returned to the URL provided in Vendor3DSCancelURL.

Send the following parameters as part of the PaymentMethod object:

Overview

Use the disableRecurringBilling method to disable recurring billing for a subscription. When you disable recurring billing, the subscription status doesn’t change. Users continue to use subscriptions with recurring billing disabled until they expire, and 2Checkout provides them with the option to renew their subscription through manual payments.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.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.2checkout.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.2checkout.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;
}
$SubscriptionReferenceTest = '48F5AC7011';
try {
    $disabledRecurringBilling = $client->disableRecurringBilling($sessionID, $SubscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "disabledRecurringBilling: " . $e->getMessage();
    exit;
}
var_dump("disabledRecurringBilling", $disabledRecurringBilling);

Overview

Use the getCrossSellCampaign method to extract information about the cross-sell campaign identified by the provided campaign code.

Request parameters

Request sample

<?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 = 'your_merchant_code';
        $key = 'your_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";

Response

Overview

Use the setRenewalNotificationStatus method to subscribe or unsubscribe shoppers from subscription renewal notifications.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$status = false;

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

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

Overview

Use the updatePromotion method via JSON-RPC API 4.0 to alter the details of an existing promotion.

Parameters

Response

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
    if (!empty($ResponseString)) {
        var_dump($ResponseString);
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

$host = 'https://api.avangate.com/rpc/3.1/';

$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

$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;

$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);

// Retrieve promotion details

$promotionCode = 'PROMOTION_CODE'; // code of the promotion that you want to update

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getPromotion',
'params' => array($sessionID, $promotionCode)
);
//var_dump (callRPC((Object)$jsonRpcRequest, $host));

// Keep the promotion you want to update in $existingPromotion
$existingPromotion = callRPC((Object)$jsonRpcRequest, $host);
// Set the fields to update 
$existingPromotion->Description = 'Updated description';

// Update the promotion
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'updatePromotion',
'params' => array($sessionID, $existingPromotion)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));