Overview

Cross-selling allows you to recommend additional products to customers and increase the average order value. The 2Checkout Public API supports classic cross-sell campaigns which means you can recommend more products from your own product catalog to your shoppers.

CrossSell Object for the placeOrder API method

Use the CrossSell object below to recommend additional products to customers via the SOAP API 6.0.

Parameter name	Type	Required/Optional	Description
ParentCode	String	Required	Product code of the product to be recommended to the shopper.
CampaignCode	String	Required	The upsell campaign code.

Request Example

{ 
  "Currency": "USD", 
  "Language": "EN", 
  "Country": "US", 
  "CustomerIP": "10.10.10.10", 
  "Source": "sourceAPI.net", 
  "CustomerReference": 421820775, 
  "Items": [ 

    { 
      "Code": "15", 
      "Quantity": 1 
    }, 
    { 
      "Code": "34924C876E", 
      "Quantity": 1, 
      "CrossSell":{ 
        "ParentCode" : "15", 
        "CampaignCode" : "2Xrl83KSkemCv3G3dL%2B9eA%3D%3D" 
      } 
    } 
  ], 

   "BillingDetails":{ 

      "FirstName":"Customer First Name", 
      "LastName":"Customer Last Name", 
      "CountryCode":"US", 
      "State":"California", 
      "City":"San Francisco", 
      "Address1":"Example Street", 
      "Zip":"90210", 
      "Email":"example@email.com" 

   }, 

  "PaymentDetails": { 
    "Type": "CC", 
    "Currency": "USD", 
    "CustomerIP": "10.10.10.10", 
    "PaymentMethod": { 

      "Vendor3DSReturnURL": "https:\/\/example.com", 
      "Vendor3DSCancelURL": "https:\/\/example.com", 
      "CardNumber": "4111111111111111", 
      "CardType": "VISA", 
      "ExpirationYear": "2020", 
      "ExpirationMonth": "12", 
      "CCID": "123", 
    } 
  } 
} 

Response

Using the same structure, the getContents method will take into account the discount associated with the cross-sell campaign and display the appropriate prices and taxes.

{ 
    "Country": "DE", 
    "Currency": "EUR", 
    "Items": [ 
        { 
            "Code": "NIQRPI0GTU", 
            "Quantity": 1 
        }, 

        { 
            "Code": "0XICS3OVDK", 
            "Quantity": 1, 

"CrossSell":{ 
        "ParentCode" : " NIQRPI0GTU ", 
        "CampaignCode" : "2Xrl83KSkemCv3G3dL%2B9eA%3D%3D" 
      } 

        } 
    ], 

    "BillingDetails": { 
        "FirstName": "Customer First Name", 
        "LastName": "Customer Last Name", 
        "CountryCode": "DE", 
        "City": "Bucharest", 
        "Address1": "Example Street", 
        "Zip": "73331", 
        "Email": "example@email.com" 
    } 
} 

 

Overview

You can implement Google Universal Analytics and Google Tag Manager tracking tools to help you track and monitor your ConvertPlus and InLine checkout orders to improve the shopping experience and increase the conversion rate.

Availability

Google Universal Analytics and Google Tag Manager can be set for all 2Checkout accounts.

Google Universal Analytics Settings

Implement Google Universal Analytics

To implement Google Universal Analytics through Google Tag Manager (GTM) for your ConvertPlus and InLine Checkout, follow these steps:

1. In your browser window, navigate to Tag manager → All accounts.

2. Click on the Create Account button.

3. Fill in all the required fields:

• Account Name
• Country
• Container name
• Target platform → Web

4. Click on the Create button.

5. Copy the Google Tag Manager Container ID. It will be used in the 2Checkout Merchant Control Panel for the Google Tag Manager set-up.

Create a Google Universal Analytics Settings variable in Google Tag Manager

If you already have a Google Universal Analytics Settings variable with your Google Universal Analytics Tracking ID, then skip to step 5.

If you do not have a Google Universal Analytics Settings variable created for your website tracking, you will need to create one to add the Google Universal Analytics property to which you want to send data by following these steps:

1. In your Google Tag Manager account, navigate to Variables → User-Defined Variables → New.

2. From the list provided by Google, select the Google Universal Analytics Settings option as Variable Type. Name your variable “Google Analytics Settings”, so you can easily identify it.

3. Under Tracking ID add the Google Universal Analytics Tracking ID to which you wish to send data.

4. To get your Google Universal Analytics Tracking ID, navigate to Google Universal Analytics → Admin → Tracking Info → Tracking Code. You will find the code under Tracking ID. Copy and add it to your variable.

5. For cross-domain tracking between your website and the 2Checkout shopping cart, you need to configure cross-domain settings in the Google Universal Analytics variable. This set-up is needed so that Google Universal Analytics counts a shopper coming from your website to the 2Checkout shopping cart, as the same visitor.

Go to More Settings → Cross Domain Tracking and type the following domains separated by a comma in the field named Auto Link Domains: secure.2checkout.com,tracking.avangate.net.

6. Append flags to the Google Universal Analytics cookie with “secure” and “samesite=none”. To do this, in the Google Universal Analytics Settings variable, click on Fields to set, add a new field and type cookieFlags as Field Name and samesite=none as Value secure, as in the example below.

7. Click Save.

Create the trigger for the Google Universal Analytics Convert Plus Tag

1. In Google Tag Manager, click on the Triggers section and then click to add a new trigger.

2. Create two triggers to track the Convert Plus and InLine shopping carts:

• One for non-interactive events: checkout and purchase.
• One for interactive events: removeFromCart (for the removeFromCart type of event, the user interacts with an element on the page by clicking the Remove from cart button. This is why this type of event is considered an interactive event by Google Universal Analytics) and addToCart.

Create the non-interactive event trigger

1. Name your trigger Event Ecommerce Non-interactive.
2. From the list provided, choose Custom event as Trigger Type.
3. In the field Event name, type  .*  and check the box Use RegEx matching.
4. For the "This trigger fires on" section, select Some custom events.
5. As rule, fill in the boxes with Event matches RegEx (Ignore case) checkout|purchase.
6. Click Save.

 

Create the interactive event trigger

1. Name your trigger Event Ecommerce Interactive.
2. From the list provided, choose Custom event as Trigger Type.
3. In the field Event name, type  .*  and check the box Use RegEx matching.
4. For the "This trigger fires on" section, select Some custom events.
5. As rule, fill in the boxes with Event matches RegEx (Ignore case) addToCart|removeFromCart .
6. Click Save.

Create the tag for ConvertPlus eCommerce tracking in Google Tag Manager

1. In the Google Tag Manager interface, click on New Tag.
2. Create two tags to track the ConvertPlus & InLine shopping carts.

• One tag for non-interactive events: checkout and purchase
• One tag for interactive events: removeFromCart

Create the tag for Non-interactive events

1. Name your tag "Google Analytics Convert Plus – Event Type Non-Interactive”, to keep track of your tags easier.
2. From the list provided by Google, select the option “Google Analytics: Universal Analytics” as Tag Type.
3. For Category type Ecommerce, select Event as Track Type.
4. For Action, select Event from the list provided by Google.
5. In the Non-Interaction Hit field, select True.
6. For the “Google Universal Analytics Settings” section, select your Google Universal Analytics Settings variable that contains the Google Analytics ID of your account.
7. Check the box Enable overriding settings in this tag.

8. Under More Settings → Ecommerce → Enable Enhanced Ecommerce Features, select True.

9. Check the Use Data Layer box to capture eCommerce information from the data layer provided by 2Checkout.

10. In the Triggering section, select the previously configured trigger for non-interactive events: Event Ecommerce Non-interactive.

11. Click Save.

Create the tag for Interactive events

1. Name your tag “Google Analytics Convert Plus – Event Type Interactive”, to keep track of your tags easier.
2. From the list provided by Google, select the Google Analytics: Universal Analytics option as Tag Type.
3. Select Event as Track Type.
4. Select Ecommerce for Category type.
5. From the list provided by Google, select Event for Action.
6. In the Non-Interaction Hit field, select False.
7. For the Google Universal Analytics Settings section, select your Google Universal Analytics Settings variable that contains the Google Analytics ID of your account.
8. Check the Enable overriding settings in this tag box.

 9. Under More Settings → Ecommerce → Enable Enhanced Ecommerce Features, select True.

10. Check the Use Data Layer box to capture eCommerce information from the data layer provided by 2Checkout.

11. In the Triggering section, select the previously configured trigger for Interactive events: Event Ecommerce Interactive.

12. Click Save.

Enable Enhanced Ecommerce in your Google Universal Analytics account

1. To enable Enhanced Ecommerce in your Google Universal Analytics account, go to Admin → View Settings → Ecommerce settings.

2. Make sure the settings for Enable Ecommerce & Enable Enhanced Ecommerce Reporting are both ON.

This information applies to Google Universal Analytics without GTM as well.

Exclude the 2Checkout domains from the referral list

To exclude the 2Checkout domains from the referral list in your Google Universal Analytics account, follow these steps:

 1. Go to Admin → Property settings → Tracking info → Referral Exclusion List.

 2. Add your website’s domain and the following 2Checkout domains: secure.2checkout.com and tracking.avangate.net.

 

This information applies to Google Universal Analytics without GTM as well.

Test your Google Universal Analytics Settings

To test if your Google Universal Analytics settings are correct, follow the steps below (make sure your browser is not set to Incognito mode):

 1. Download and install the Tag Assistant Companion browser extension found here.

 2. Click on Preview.

3. Delete all existing domains.

4. Click on Add domain.

5. Add https://tracking.avangate.net/ and click Start.

6. Go back to the Google Tag Manager tab but DON’T close the tab with tracking.avangate.local.

7. Click on X in the top-left corner.

8. In the Tag Assistant Tab, click on Add domain.

9. Enter the buy-link you want to debug and click Start.

10. Go back to the Google Tag Manager debugger tab.

11. Click on the Enable button behind the “Connecting this window to avangate.net” pop-up.

12. Click on Continue.

13. You are now debugging tracking.avangate.net, but this domain receives tags from the shopping cart.

Submit and publish your settings

Merchant Control Panel Settings

The Analytics section in your Merchant Control Panel allows you to integrate Google Universal Analytics or/and Google Tag Manager in the ConvertPlus or InLine ordering engines and thus track the behavior of your shoppers on the 2Checkout pages.

Follow these steps to complete your analytics integration:

1. Log into your Merchant Control Panel.
2. Navigate to Setup → Ordering options.
3. Click on the Analytics tab.
4. Click on the ConvertPlus and InLine Checkout tab.

 

5. In the Google Tag Manager box, click on Set up.

 

6. Fill in the Google Tag Manager code (Here is how you obtain it) and click Save.

7. Complete the integration by using the slider to activate Google Tag Manager. It is not recommended to activate both Universal Analytics and Google Tag Manager to send data to the same Google Universal Analytics view, otherwise, duplicate data will occur.

1. 2Checkout data layer for tracking through Google Tag Manager is placed in an iFrame. This data layer has an eCommerce object, that contains eCommerce information built on the structure required by Google Universal Analytics reporting for the following events: checkout, add to cart, product impressions (for cross-sells), purchase, and remove from cart. 2. For fully enhanced eCommerce reporting in Google Universal Analytics, it is recommended that you send information to Google Universal Analytics from your website that includes product impression, product detail, and add to cart. More information on enhanced eCommerce reporting and how to send Product View and Add to Cart data to Google Universal Analytics can be found here: https://developers.google.com/tag-manager/enhanced-ecommerce 3. In addition to the eCommerce object, the data layer also contains an event called cartUpdated that includes additional parameters with information on the shopping cart. These parameters can be used to capture further information in custom dimensions. Refer to the Google Documentation on how to build custom dimension through Google Tag Manager: https://support.google.com/tagmanager/answer/6164990?hl=en .

Overview

Use the updateSubscriptionEndUser method to update the details of a subscription’s end user. This method changes per-subscription end user data and not customer details.

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.
SubscriptionReference	Required (string)
	Unique, system-generated subscription identifier.
EndUser	Required (Object)
	Use this object to update end user information.

Response

Parameter	Type/Description
Boolean	true or false depending on whether the changes were successful or not.

Request

<?php
 
 
function callRPC($Request, $hostUrl, $Debug = true) {
    $curl = curl_init($hostUrl);
    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, 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)) {
        $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.0/';
 
$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; // counter for api calls
// call login
$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);
 
var_dump($sessionID);
$subscriptionReference = '8F749B63E7';
$EndUser = new stdClass ();
$EndUser->Address1 = 'Address line 1';
$EndUser->Address2 = 'Address line 2';
$EndUser->City = 'LA';
$EndUser->Company = 'Company Name';
$EndUser->CountryCode = "US";
$EndUser->Email = 'customerAPI@avangate.com';
$EndUser->FirstName = 'New Customer 2.0';
$EndUser->Language = 'en';
$EndUser->LastName = 'Avangate';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Zip = '90210';
$EndUser->Fax = null;

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

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

 

Overview

Apply discount coupons to products added to the shopping cart.

Requirements

Parameters

Parameter	Type/Description
sessionID	Required (String)
	Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
coupon	Required (String)
	The coupon/voucher code for a promotion impacting a product added to cart.

Response

Parameter	Type/Description
Result	Boolean
	True or false

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
require ('PATH_TO_ADD_PRODUCT'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/08Place_an_order/00Add_product_to_cart

$couponCode = 'YOUR_COUPON_CODE';

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

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

Errors

Error	Description
EMPTY_CART	The shopping cart is empty.
INVALID_COUPON_CODE	The coupon code is empty or invalid.

 

Overview

Use this method to add information about a reseller in the 2Checkout system.

Requirements

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

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, output of the Login method. An exception will be thrown if the values are incorrect.
Reseller	Required (object)

Response

Parameters	Type/Description
ResellerCode	String
	Unique code identifying a specific reseller.

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

$reseller = new stdClass();
$reseller->ResellerCode = '1234565';
$reseller->Company = 'Avangate';
$reseller->FirstName = 'John';
$reseller->LastName = 'Doe';
$reseller->Email = 'johndoe@example.com';
$reseller->Phone = '123456789';
$reseller->Fax = '12345';
$reseller->Country = 'US';
$reseller->State = 'CA';
$reseller->City = 'Palo Alto';
$reseller->Address = 'Street';
$reseller->PostaCode = '90210';

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

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

Errors

Error	Description
NOT_FOUND_PARTNER	A partner must be set first.
EMPTY_RESELLER_FIRST_NAME	Reseller first name is mandatory.
EMPTY_RESELLER_LAST_NAME	Reseller last name is mandatory.
EMPTY_RESELLER_COMPANY	Reseller company is mandatory.
INVALID_RESELLER_EMAIL	Reseller email is mandatory.
INVALID_RESELLER_EMAIL	Invalid reseller email provided.
INVALID_COUNTRY	Invalid reseller country code.
INTERNAL_ERROR	Reseller information could not be saved.

 

Overview

Place an order for catalog products defined in your Control Panel and collect the payment using WeChat Pay.

Requirements

Only Chinese shoppers are able to purchase using WeChat Pay. Make sure the billing country code is set to CN.

Supported currencies

• USD
• HKD
• CNY

Workflow

1. Shoppers select WeChat as payment option in the interface you provide to them.
2. Create the order object. Use WE_CHAT_PAY as the type of the PaymentDetails object, and include ReturnURL and CancelURL.
3. Use the placeOrder method to send the data to 2Checkout.
4. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING.
5. 2Checkout returns an Order object as the output of the placeOrder method. 
6. 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/we_chat_pay/authorize/?avng8apitoken=1abc7fd72d008428

7. After being redirected to WeChat Pay, shoppers need to scan the QR code provided, using the WeChat smartphone app.
8. After customers enter their payment password, WeChat notifies 2Checkout if the payment is approved, and the status of the order becomes COMPLETE.
9. Shoppers are redirected to the RedirectURL from the Order information object. In case the payment fails, shoppers are redirected to the CancelURL. 

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.
Order	Required (Object)
	Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details. To place an order with WeChat, use WE_CHAT_PAY as the type of the PaymentDetails object and provide a ReturnURL and a CancelURL as part of the PaymentMethod object. See code sample.

Response

Parameters	Type/Description
Order information	Object
	Object containing order information.

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'CN';
$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 = 'CN';
$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 = 'WE_CHAT_PAY';
$Order->PaymentDetails->Currency = 'USD';
$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->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

$wechatredirect = $newOrder->PaymentDetails->PaymentMethod->Authorize->Href."/?avng8apitoken=".$newOrder->PaymentDetails->PaymentMethod->Authorize->Params->avng8apitoken;

header('Location:' . $wechatredirect);

Overview

Retrieve information about a subscription.

Parameters

Parameters	Type/Description
ReferenceNo	String
	Unique, system-generated order reference number.
Type	String
	Purchase type: SALE RENEWAL UPGRADE
SubscriptionReference	String
	Unique, system-generated subscription reference.
StartDate	String
	Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration.
ExpirationDate	String
	Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration.
Lifetime	Boolean
	Possible values: True – the subscription is evergreen False – the subscription has a recurring billing cycle less than or equal to three years.
SKU	String
	Stock keeping unit you defined.
DeliveryInfo	Object
	Object with information about the delivery made to the customer - structure described below
PartnerCode	String
	Possible values: Empty = ecommerce order Partner Code

 

Overview

Use the getIdealIssuerBanks method to retrieve the information on the Avangate list of banks that support iDEAL payments for shoppers in the Netherlands. You will need banking information to place orders, enabling your shoppers to pay using iDEAL. Use the code parameter from the array returned by getIdealIssuerBanks, as a value of the BankCode parameter in the Order object, when you call placeOrder.

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect. The sessionID expires in 10 minutes.

Response

Method returns an array of objects, containing the bank code and bank name as parameters. The value of the Code parameter is used in the placeOrder call, in the BankCode parameter.

Parameters	Type/Description
Code	String
	String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
Name	String
	String contains the full bank name. E.q.: "Rabobank".

Request

<?php

// authentication script: https://knowledgecenter.avangate.com/Integration/SOAP_API/API_4.0/02Authentication

require ('PATH_TO_AUTH');

try {
    $getIdealBanks = $client->getIdealIssuerBanks($sessionID);
} catch (SoapFault $e) {
    echo "Error getIdealIssuerBanks: " . $e->getMessage() . $e->faultcode;
    exit;
}

$bankCodes=("getIdealIssuerBanks", $getIdealBanks);

?>

Overview

Use this method to extract information about orders in the Avangate platform.

Parameters

Parameters	Type/Description
sessionID	String
	Session identifier string, output of the Login method. An exception is thrown if the values are incorrect.
refNo	String
	Order reference number of an existing approved/paid order.

Response

Parameters	Type/Description
Order	Object

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication

$refNo = 'YOUR_ORDER_REFERENCE_NUMBER';

$jsonRpcRequest = array (
'method' => 'getOrder',
'params' => array($sessionID, $refNo),
'id' => $i++,
'jsonrpc' => '2.0'
);
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

Overview

Manage all aspects of usage billing either from your Merchant Control Panel or via the 2Checkout API.

Read here more info on how to manage and upload usage billing.

Upload usage for your subscriptions 

Timeframe to upload subscriptions usage  

You can upload usage data for the active billing cycle at any time throughout the billing cycle. However, not all usage might be available for billing by the time the subscription expires. That is why you should consider taking a few days buffer to allow usage to be uploaded for the current billing cycle for a subscription before any billing attempts are made.   

2Checkout will not attempt to automatically charge customers for recurring costs and additional metered usage fees (in arrears) during the “Usage billing interval”, thus allowing merchants time to upload any outstanding usage. Set the “Usage billing interval” to zero if you want to charge usage fees as soon as the subscription expires.

You can set a usage upload interval by editing the “Usage billing interval” settings: 

• Across all your products from your Merchant Control Panel → Setup → Renewal → Global Renewal Settings tab OR  
• For individual products from your Merchant Control Panel → Setup → Products → Renewal tab

These settings will impact only the subscriptions associated with the product you're configuring, and will override any global renewal settings.  Changes in Usage upload interval settings also impact subscriptions created prior to the update of the setting.  Because the usage upload interval cannot exceed the grace period, if you set the grace period value to a value smaller than the current usage billing interval, the usage billing interval setting will automatically be updated so that the new value does not exceed the grace period setting.

After the expiration date of one billing cycle, you can start uploading usage for the upcoming billing cycle, as long as the subscription is in Past Due status, and not Expired.  

Usage upload notifications 

For subscriptions with a usage billing price options group, the 2Checkout system will start notifying you via email that usage is due 5 days before the usage upload interval of the subscription. 2Checkout will continue to send notifications daily for the following 10 days, or until usage was uploaded for the subscription or the subscription expires.  

Example of the timeframe for uploading usage 

Assuming a subscription expires on August 31st, and there’s a usage billing interval of 2 days and a grace period of 5 days, this is the usage you can upload and when: 

	<= Aug 31st	Sep 1st	Sep 2nd	Sep 3rd	Sep 4th	Sep 5th	>=Sep 6th
Ability to upload usage from August	Yes	Yes	Yes	No (usage billing interval exceeded)
Ability to upload usage from September	No (outside of billing cycle)	Yes	Yes	Yes	Yes	Yes	Yes, if August cycle was paid.   Otherwise no.

Upload and manage usage records

There are a few ways you can upload and manage usage records in the 2Checkout platform.

Add, edit, delete and read usage records via API  

2Checkout provides an extensive set of API methods aimed to automate the management of usage without the use of physical files, all without rate limits. Read more about these in the API documentation. 

How to upload itemized, maximum or average usage  

2Checkout does not limit the number of usage records you can upload, which means that you can upload usage immediately after it happens, or with a certain frequency, or all usage together at the end of the billing cycle.  

2Checkout will sum up all your usage records in the billing cycle before billing it. The timeliness of when you upload usage may be impacted by how you want to bill usage. For example: 

• If you want to bill a sum of all usage, you can upload usage immediately as it happens, or upload an intermediate sum for a specific timeframe, or upload a sum of all usage throughout the billing cycle at the end of the cycle.  
• If you want to bill based on the usage peak in that bill cycle or an average usage throughout the billing cycle, you should ensure you perform this calculation outside of 2Checkout and have only one usage record uploaded for the entire billing cycle of the subscription

Import usage from a CSV file via your Merchant Control Panel  

You can upload usage from a CSV (comma-separated values) file by using the usage import tool located in your Merchant Control Panel → Setup → Renewal → Usage tab. To build your CSV file you can use the sample file provided, or you can create a file from scratch as long as you make sure it has the following structure, with the columns in this order:

Column name	Type	Description
LicenseUniqueId	string (250)	Your unique identifier for the subscription which is generated outside of 2Checkout but stored in 2Checkout so that it can subsequently be used for management tasks impacting subscriptions. If provided, it must match the external identifier associated with a subscription present in 2Checkout. Can be empty only when LicenceCode is populated . If both LicenceUniqueID and LicenceCode are provided, the combination must match a valid subscription for the merchant.
LicenceCode	string	2Checkout generated unique subscription reference which is stored in 2Checkout so that it can subsequently be used for management tasks impacting subscriptions. If provided, it must match the reference of a subscription present in 2Checkout. Can be empty only when LicenceUniqueId is populated. If both LicenceUniqueID and LicenceCode are provided, the combination must match a valid subscription for the merchant.
OptionCode	string	Unique code provided in the definition of the pay per usage price option group for the product associated with the subscription. Must match a valid pay per usage price option group associated with the product on the subscription.
Units	numeric	The number of units of the metered resources consumed on the subscription in the time interval mentioned.  Cannot be empty or negative, but you can upload 0 (zero) units.
StartDate	date   YYYY-MM-DD	Defines the beginning of the usage interval (for example, when the subscriber logged into your application). Cannot be empty, and has to be equal to or greater than the subscription Purchase date and less than EndDate on the same row. Date interval on one usage record cannot overlap with the date interval on another usage record.
EndDate	date   YYYY-MM-DD	Defines the end of the usage interval (for example, when the subscriber logged out of your application). Cannot be empty, has to be greater than the purchase date of the subscription, greater than the StartDate on the same row, and cannot be a date in the future. Date interval on one usage record cannot overlap with the date interval on another usage record.

2Checkout uploads CSV files and processes the usage data successfully only if no errors are encountered during the upload. Processing of usage uploaded via CSV files is done hourly, on the 17th minute of each hour.

The 2Checkout system sends out notifications if the usage upload process completed successfully, and when the processing of the CSV file with the usage data uploaded fails. Emails are sent automatically to the address under Customers Support Email (set in Account Information → Account Settings), specifying the lines in the CSV file for which usage processing was unsuccessful. If the process fails, correct the errors reported on the specific lines and re-upload the CSV file entirely for the data to be processed. 

As long as the usage uploaded in the file has not been processed, you can always delete the uploaded CSV files. Once the usage was processed by the 2Checkout system, you will only be able to download the CSV files, but not to remove them or the uploaded data.  

Importing usage from a CSV file via API  

You can automate the upload of the CSV file already mentioned in this documentation by using the 2Checkout API to upload the file. Read more about this in the API documentation.

Use the GMT+2 time zone for the StartDate and EndDatec columns when making the API call to the Usage Upload endpoint.

Billing of subscriptions with a pay-per-usage price option  

Initial purchase 

Pay-per-usage pricing does not impact new acquisition costs, but only their renewal price. When first purchasing products with usage pricing components, shoppers pay the costs of the first billing cycle in advance. 2Checkout charges metered resources consumed in arrears at the start of a new billing cycle when the subscription expires/renews for the previous billing cycle. 

Renewal billing 

Renewal notifications  

The 2Checkout system sends out renewal notifications to your customers according to the global or product-specific renewal notification settings on your account. For subscriptions with usage billing price option groups, the timing of the notification is calculated based on the expiration date + usage billing interval. This means that in some cases renewal notifications might be sent out before the usage billing period interval is over, and full usage is received for the subscription.

Billing amount calculation 

2Checkout charges the customer the recurring costs of the upcoming billing cycle and the fees for the unbilled metered resources consumed in the previous billing cycles together. To determine what the fees for the metered resources are, 2Checkout performs the following actions: 

1. Filters for the usage records which need to be billed for the Subscription and the billing cycle. These are all unbilled usage records where the record’s EndDate is less than or equal to the bill cycle Expiration Date. 

• If no usage is found, then Usage costs will be zero. 
• Any unbilled usage before the active billing cycle is going to be billed as part of the active billing cycle.

2. Sums up all usage records for the Subscription, Price Option Code, and the Billing Cycle. 

3. Looks up what the price of each usage unit is, in the Price Option setup of the product.  

• If the “Impact on price per unit” set-up on the scale is set to “Add” prices to the price per unit, then the unit price will be calculated by adding all values for all the previous scales, including the one usage falls in.  
• If the unit price is zero on any of the scales, then zero is what will be used in the calculations.  

4. Multiplies the units with the Price per unit to determine the usage costs.

Automatic billing of usage 

The first billing attempt for an automatic renewal usage billing subscription is set at Subscription Expiration Date + Usage Upload Interval. You can also mark that all usage for the subscription’s current billing cycle was received before the usage upload interval and trigger immediate billing of the subscription costs via API.

After the first attempt, retries are scheduled only within the Grace Period according to the 2Checkout retry logic, depending on your account settings and if you have activated the 2Recover add-on. Retries are as follows: 

• Without 2Recover add-on, 2Checkout will retry to bill usage up to 2 times, up to 9 days after the Usage upload interval has ended, but only within Grace Period 
• With 2Recover add-on, 2Checkout will retry to bill usage up to 6 times, up to 14 days after the Usage upload interval has ended, but only within Grace Period 

Manual billing of usage 

Subscribers can manually renew their pay-per-usage subscriptions only after the Usage Upload Interval has passed, or after the merchant has marked that all usage for the subscription’s current billing cycle was received via API. As is with all subscriptions, subscribers can only renew their pay-per-usage subscriptions within the subscription’s grace period. 

Report usage 

The number of usage units consumed, their cost and the status of their billing is visible in your Merchant Control Panel, in the Subscription Details page available for each subscription.  

Usage records can also be read via API. Read more about this in the dedicated API documentation.

FAQ

1. Do discounts apply to the entire value of renewal orders? 

Yes. Discounts apply to the entire value of the renewal order, usage costs included. 

2. Is there a maximum number of usage billing units that can be uploaded? 

The maximum limit for usage units is 999,999,999 units. 

3. What if the data for only a few subscriptions or a single item was incorrect? Will the rest of the usage data be processed? 

No. Please make sure that you deal with the errors reported by the 2Checkout system and re-upload the full CSV file. 

4. Can usage be updated once it is uploaded?

Yes, usage can be updated via API using the updateUsage method.