Overview

The list below contains the values accepted in the EXPORT_TIMEZONE_REGION parameter for Instant Order Search Export (ISE). Find more about ISE here.

Column "Timezone region value" holds the strings allowed in the ISE service, as a value for the EXPORT_TIMEZONE_REGION parameter. Use column "Offset hour from UTC" to check the difference in timezone between each region and UTC (Coordinated Universal Time). Column "Country / State timezone" references the country / state / capital from each respective timezone region.  

Overview

Use the ProductGroup object to create/add and update/edit product groups.

Parameters

Structure

Overview

Use this method to add products to cart, during the current cart session.

Requirements

This method requires you to set a specific partner using setPartner.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner

$productId = 'YOUR_PRODUCT_ID';
$pricingListCode = 'YOUR_PRICING_LIST_CODE';
$quantity = YOUR_PRODUCT_QUANTITY;
$priceOptions = array(
'PRICING_OPTION_1',
'PRICING_OPTION_2'
);

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'addProduct',
'params' => array($sessionID, $productId, $quantity, $priceOptions, $pricingListCode)
);

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

Errors

Overview

Learn how to tackle the common errors that may arise when issuing refunds via 2Checkout API.

Common error codes 

Overview

Use the issueRefund method to issue a partial refund for an order processed by 2Checkout.

Requirements 

The payment for the refundable order needs to be collected.

You cannot issue a refund for an amount higher than the total order amount.

We recommend you create a new order with placeOrder to have one that can be refunded.

The order’s status must be ’COMPLETE’ and it should have a TotalPrice > 0.

The OrderDate cannot be older than a year from the current date.

To obtain the LineItemReference, use the getOrder method: https://knowledgecenter.2checkout.com/API-Integration/JSON-RPC_API_6.0/Reference/14Retrieve-an-order

Request

<?php

/**
 * @throws JsonException
 */
function callRPC($Request, $host) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
    curl_setopt($curl, CURLOPT_VERBOSE, false);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
    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, JSON_THROW_ON_ERROR);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);

    $ResponseString = curl_exec($curl);

    if (!empty($ResponseString)) {
        echo($ResponseString);
        $Response = json_decode($ResponseString, false, 512, JSON_THROW_ON_ERROR);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            echo("Method: {$Request->method}" . PHP_EOL);
            echo("Error: {$Request->error}" . PHP_EOL);
        }
    } else {
        return null;
    }
    return null;
}

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

$merchantCode = "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 = "SECRET_KEY"; // your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$algo = "sha256";
$hash = hash_hmac($algo, $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, $algo);
$jsonRpcRequest->id = $i++;

try {
    $sessionID = callRPC($jsonRpcRequest, $host);
    echo("Auth token: {$sessionID}" . PHP_EOL);
} catch (JsonException $e) {
    echo("Error: {$e->getMessage()}" . PHP_EOL);
}

$orderReference = "73152871";

$items = [];
$item = new stdClass();
$item->Quantity = 1;
$item->LineItemReference = "a439c84a4b1e8ad1d7bf38407f5ea7473433ce7b";
$item->Amount = 29.99;

$items[] = $item;

$comment = "This is a comment";
$reason = "Fraud";

$jsonRpcRequest          = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method  = 'issueRefund';
$jsonRpcRequest->params  = array($sessionID, $orderReference, null, $items, $comment, $reason);
$jsonRpcRequest->id      = $i++;

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

var_dump ($partialRefund); 

Response

Overview

Use the unassignAdditionalField method to update additional fields for your account.

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductCode = 'YOUR_PRODUCT_CODE';
$FieldCode = 'YOUR_FIELD_CODE';

try {
    $UnassignedAdditionalField = $client->unassignAdditionalField($sessionID, $FieldCode, $ProductCode);
}

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

var_dump("UnassignedAdditionalField", $UnassignedAdditionalField);

Overview

Place a test order using catalog products defined in your Merchant Control Panel.

Set the Payment details type to TEST in order to create an order with a test credit card or a 2Pay.js token generated with a test credit card in a test environment.

For the full list of test credit card details, check this article.

Parameters 

Response 

Test order request with credit cards

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$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 = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = 'us';
$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 = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->PaymentDetails->PaymentMethod->Vendor3DSReturnURL = "http://yoursuccessurl.com"; // used for 3DS ordering
$Order->PaymentDetails->PaymentMethod->Vendor3DSCancelURL = "http://yourcancelurl.com"; // used for 3DS ordering

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}

var_dump("newOrder", $newOrder);

 Test order request with 2Pay.js tokens

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$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 = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = 'us';
$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 = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->EesToken = “90007562-681b-4df5-9797-53faf8abbc92”;
$Order->PaymentDetails->PaymentMethod->Vendor3DSReturnURL = "https://example.com";
$Order->PaymentDetails->PaymentMethod->Vendor3DSCancelURL = "https://example.com";

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}

var_dump("newOrder", $newOrder);

Overview

Take advantage of External Order Tracking to keep track of sales generated by members of the 2Checkout Affiliate Network for services/products that you sell using multiple payment processors and different affiliate networks or a third-party ecommerce platform, in addition to those sold through the 2Checkout system, if any.

External Order Tracking ensures that 2Checkout rewards Affiliates for referred orders sold outside the 2Checkout platform. The 2Checkout Affiliate Network currently features over 40,000 affiliates working on a pay-per-sale commission-based model. According to the data in our system, companies selling mainstream software can experience an average jump in sales of 10%-15% simply by leveraging the 2Checkout Affiliate Network.

This technology is based on two types of pixel tracking implementations. While both implementations have the same behavior, their inner workings are quite different.

Image pixel

An invisible image pixel to track shopper actions once they buy a product/subscription after being redirected via a link from an 2Checkout Affiliate. 2Checkout uses the recorded data to provide you with reports and to pay the affiliates who generate sales of your products/services.

iFrame pixel

The most common way of tracking conversions. Tests have shown that iFrame pixels are much more accurate than image pixels. Additionally, iFrame pixels offer more room for further developments, if necessary.

External Order Tracking Requirements

Image pixel requirements

Should you choose to use the image pixel technology, you must meet the following requirements:

• Enable the 2Checkout Affiliate Network for your account.
• Use a custom domain with 2Checkout(e.g. store.merchant.com).
• Use a custom domain with third-party ecommerce providers(e.g. store.merchant.com).
• Configure products sold through a third-party platform within the 2Checkout platform.
• Assign the products to commissions lists associated with 2Checkout affiliates. Make sure to specify a commission you're willing to pay for affiliate referrals.
• Contact your 2Checkout account manager for details on legal / financial requirements.

iFrame pixel requirements

Should you choose to use the iFrame pixel technology, you must meet the following requirements:

• Enable the 2Checkout Affiliate Network for your account.
• Configure products sold through a third-party platform within the 2Checkout platform.
• Assign the products to commissions lists associated with 2Checkout affiliates. Make sure to specify a commission you're willing to pay for affiliate referrals.
• Contact your 2Checkout account manager for details on legal / financial requirements.

Important: iFrame pixel tracking does not require you to create a custom domain with 2Checkout.

Integrating Image Pixel Tracking

Provided that you meet all the requirements mentioned above you can now move to the integration stage.

1. Go to Affiliate Network -> Build your network and select the External Orders Tracking tab.
2. Copy the JavaScript code available on this page into the source code of the Thank You pages that you use outside 2Checkout
3. Replace the UPPER-CASE values with the corresponding order variables in the external ordering platform. Depending on whether or not you're using a custom domain, you will need to configure the tracking.type parameter accordingly
   
   • tracking.type='image' or tracking.type='iframe' if you are using a custom domain
   • tracking.type='iframe' if you are not using a custom domain

Integrate the modified JavaScript code into the source code of the Thank you page displayed to shoppers at the end of a successful sale. This area is designed to offer a range of details, including an external order reference, info on the products sold, their value, etc.

External Order Tracking relies on cookies to track the activity of the shopper during the purchase process. Essentially, when users click links from 2Checkout affiliates, 2Checkout records the clicks and places tracking cookies on their machines. 2Checkout affiliate links can point to a specific product or multiple offerings from you, or redirect to your website.

External Order Tracking comes into play when users complete an order with the third-party payment provider you're using, reaching the confirmation screen at the end of the ordering process. This page features the tracking script (an invisible 1x1 pixel image or iFrame) set up to record the details of the sale.

You can see completed sales tracked with Pixel Tracking in the External orders area of your Control Panel, under Affiliate Network.

Confirm external orders to credit 2Checkout Affiliates

For affiliates to be credited and paid for the referred purchases, even if the commission is warranted, you need to first approve external orders manually. Make sure to check the validity of external orders with purchases made through the third-party platform you're using.

The information recorded contains the external reference of products, the date when the order was placed, the affiliate whose link was used, the names of theexternal products and the number of units purchased, as well as the price paid by the shopper and the associated currency.

Before confirming external orders, match the products tracked via Pixel Tracking with those you defined in the 2Checkout platform. Once an external product is matched with one defined in the 2Checkout platform, subsequent matches involving the same two items will be done automatically by the system. Note: You cannot match multiple products from the same external order with a single product in the 2Checkout system.

The commission that 2Checkout Affiliates receive is calculated based on the price recorded when the External Order is placed successfully, and is not impacted by the pricing schemes you configure in the 2Checkout platform.

External orders in the 2Checkout platform can show the following status messages:

• Pending
• Processing
• Rejected
• Confirmed

You can edit and confirm both Pending and Rejected orders. When you confirm an external order, a new order is also generated in the 2Checkout platform, which will be available in the Order search area, under Orders & customers.

You can approve external orders either one by one, or selecting multiple items at once. Note that once you confirm an external order, its details are locked and can no longer be modified. For unconfirmed external orders, any changes will be reflected real-time across all items in this area, if the modifications impact additional orders than the one being edited.

Rejected orders will be ignored by 2Checkout and affiliates will not receive any commission.

When do 2Checkout affiliates receive a commission?

2Checkout's Affiliate Network is based exclusively on a pay-per-sale model. This means that affiliates receive a commission, a percentage out of the price for all shopper purchases that they refer. You alone control the value of the commission paid to affiliates in the 2Checkout Network when a visitor referred by them purchases a product or a service on your website.

Do affiliates automatically receive commission for ever sale they generate?

No. You first need to confirm the sales reported by our External Tracking technology as valid.

Under which conditions can I reject sales?

You can reject all invalid or erroneously reported sales if identified as such. For example, you can reject an order to avoid duplicate crediting of an affiliate that works with both 2Checkout Affiliate Network and another affiliate network.

What does the Other message stand for?

Orders can contain additional costs on top of the price of the products purchased. When 2Checkout identifies such costs, including taxes (VAT, sales tax), shipping taxes, etc., they're featured in a manner designed to make it clear that they cannot be matched with a product in the 2Checkout system.

How does 2Checkout calculate the affiliate commission?

2Checkout calculates the affiliate commission only according to the price of the products shoppers acquire from you, disregarding any additional costs they pay.

Why is the commission of some external orders zero (0) even if they're valid sales?

The affiliate commission for the selected 2Checkout match is 0 because the affiliate initially promoted a different product than the one purchased by the shopper. As such, the 2Checkout system has determined that the commission is not warranted.

You should reject orders for which the commission's value is zero (0). However, even if you try to approve them, the 2Checkout system is designed to disregard them, since there's no commission to pay affiliates.

Can the commission for an External Order be modified?

Only for Pending External Orders, by modifying the commission settings for affiliates, which will be applied automatically.

What values can be sent for the parameters market as optional in the JavaScript code?

Either the first and last name, company, email, postal code, etc. in the case of setContact, for example, when they exist, or null otherwise. Replace each optional parameter with NULL. Alternativelly, the entire line: tracking.setContact('FIRST_NAME', 'LAST_NAME', 'COMPANY', 'EMAIL', 'POSTAL_CODE', 'CITY', 'STATE', 'FISCAL_CODE', 'ISO_COUNTRY_CODE', 'ADDRESS'); can be removed.

What happens when the "none" option is selected when matching products?

2Checkout will not pay Affiliates a commission for External Products which you don't match with items configured in 2Checkout (their equivalents) and select noneinstead.

What data does the external order tracking mechanism captures?

We only capture data that we receive from the after sales page in the 3rd party ecommerce platform.

The mandatory values that we need in order for External Order Tracking to function are:

1. Order ID (from 3rd party eCommerce solution, for sync purposes - e.g. if one of their orders gets refunded, the merchant will be able to reject the order in 2Checkout also);
2. Currency - the currency that was used in the order;
3. Total Price - price paid by the customers;
4. Product details:
   
   • Product name - name of product from 3rd party eCommerce solution
   • Unit price - unit price in 3rd party eCommerce solution
   • Quantity - quantity
   • Product ID - product ID in 3rd party eCommerce solution

There are some optional variables also that the merchant can send: First name, last name, company, email, postal code, city, state, fiscal code, country code (ISO), address.

Overview

Use the updatePromotionCoupon method to add single or multiple coupons to a promotion.

Updating a promotion with multiple coupons causes any existing single coupon to be removed.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

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

// Define single coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'SINGLE';
$promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'MULTIPLE';
$promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

try {
    $updatedPromotion = $client->addPromotionCoupon ($sessionID, $promotionCode, $promotionCoupon);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);