Overview

Retrieve information about a subscription.

Parameters

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

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.

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

Response

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: 

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:

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.

Overview

Use the issueRefund method to issue a total 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 to 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 Total price.

The order’s date cannot be older than a year from the current date.

To obtain 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 = [];

$amount = '241.49';
$comment = "This is a comment";
$reason = "Fraud";

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

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

var_dump ($totalRefund ); 

Response

Overview

Use the getTimezone method to retrieve information on the time zone used by your account for the 2Checkout API.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

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

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

Overview

Use the assignAdditionalField method to assign additional fields to a product.

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

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

try {
    $AssignedAdditionalField = $client->assignAdditionalField($sessionID, $FieldCode, $Required, $ProductCode);
}

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

var_dump("AssignedAdditionalField", $AssignedAdditionalField);

?>

Overview

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

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$AdditionalField                             = new stdClass();
$AdditionalField->Label                      = 'Do you agree with the new newsletter policy 2015?';
$AdditionalField->Type                       = 'LISTBOX';
$AdditionalField->Code                       = 'NewsletterPolicy1234576';
$AdditionalField->ApplyTo                    = 'ORDER';
$AdditionalField->Values                     = array();
$AdditionalField->Values[0]                  = 'YES';
$AdditionalField->Values[1]                  = 'NO';
$AdditionalField->ValidationRule             = null;
$AdditionalField->Translations               = array();
$AdditionalField->Translations[0]            = new stdClass();
$AdditionalField->Translations[0]->Label     = "Êtes-vous d'accord avec la politique de la newsletter?";
$AdditionalField->Translations[0]->Values    = array();
$AdditionalField->Translations[0]->Values[0] = 'Oui';
$AdditionalField->Translations[0]->Values[1] = 'Non';
$AdditionalField->Translations[0]->Language  = 'fr';
$AdditionalField->Translations[1]            = new stdClass();
$AdditionalField->Translations[1]->Label     = 'Haben Sie mit dem Newsletter Politik zu?';
$AdditionalField->Translations[1]->Values    = array();
$AdditionalField->Translations[1]->Values[0] = 'Ja';
$AdditionalField->Translations[1]->Values[1] = 'Nein';
$AdditionalField->Translations[1]->Language  = 'de';

try {
    $UpdateAdditionalField = $client->updateAdditionalField($sessionID, $FieldCode, $AdditionalField);
}

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

var_dump("UpdateAdditionalField", $UpdateAdditionalField);

Overview

Use the GetPriceMatrix API call to retrieve details that are used to add or update a special price promotion.

Request parameters

Response

Request sample 

<?php

require('PATH_TO_AUTH');


$priceMatrixRequestObject1 = new stdClass;
$priceMatrixRequestObject1->productCode = "474FF7C0FD"
$priceMatrixRequestObject1->pricingConfigurationCode = "514EE48419"

$requestBody = [
    $priceMatrixRequestObject1
]

$promotionObject->PriceMatrix = [$priceMatrixDefinition1];


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

$result = callRPC((object)$jsonRpcRequest, $host);
var_dump($result);