Overview

Generate a partner invoice for one or more orders, based on their unique reference numbers.

Requirements

You can include only confirmed/approved orders in partner invoices. To include multiple orders in the same partner invoice they must share the same currency.

Parameters

Response

Request

<?php

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

$sales = array(
'ORDER_REFERENCE_1',
'ORDER_REFERENCE_2'
);

try {
    $NewProforma= $client->createProforma($sessionID, $sales);
} catch (SoapFault $e) {
    echo "NewP: " . $e->getMessage();
    exit;
}
var_dump ("NewP ", $NewProforma);

Errors

Overview

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

Common error codes 

Overview

Use the setExternalRef method in conjunction with setSubscriptionUpgrade.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$externalReference = 'YOUR_EXTERNAL_REFERENCE';

try {
    $extRef = $client->setExternalRef($sessionID, $externalReference);
}
catch (SoapFault $e) {
    echo "extRef: " . $e->getMessage();
    exit;
}
var_dump("extRef", $extRef);

Overview

Retrieve information about the upgrade options for a specific subscription.

2Checkout's pricing configuration capabilities enable you to tailor the price details of your products/subscription plans to specific markets or geographic regions. The price, currency, and pricing options set per product can easily adapt to each market, providing a powerful tool to support your localization/globalization strategy.

Example:

A product costs $30 for US-based shoppers and 25 Euro for those in Germany. The 2Checkout system's localization capabilities make it possible for shoppers located in the United States to see the $30 price when adding the product to cart, with the US as the preselected billing country. Similarly, shoppers in Germany will get the 25 Euro localized price, when their country is preselected according to geolocation detection. The flexibility of the 2Checkout system also enables localized prices to be swapped for one another when shoppers manually select the billing country.

Availability

2Checkout Enterprise Edition accounts. 

Requirements

Pricing localization capabilities require the following:

1. Pricing Configurations enabled for your account.
2. Enable geolocation by IP address. 2Checkout uses real-time geo-location to determine shopper locale. Geo-location is enabled by default and should be active to ensure that localized pricing will work for your products.
3. To localize costs you first need to configure a new pricing configuration for a subscription plan/product on top of the Default.

Default pricing configuration

Each product features a Default pricing configuration designed to cover all available billing countries (it includes all markets as long as they aren't covered by any localized pricing strategies). 2Checkout defaults to this pricing configuration when IP geolocation is disabled.

2Checkout recommends you use pricing localization in tandem with IP geolocation. Without geo-location 2Checkout does not pre-select the billing country when shoppers first land in the shopping cart, and they will see the costs configured under the Default pricing configuration. 

Limitations

1. You cannot localize the Default pricing configuration. 
2. All new pricing configurations you add on top of the default are disabled by default until you edit the country details (assign at least one country to a pricing configuration to enable it for the shoppers in that specific market).
3. Marking a new, custom, localized pricing configuration as Default disables the default pricing configuration previously in use (detail reflected by the Not active for eStore status).
4. Transforming a custom, localized pricing configuration into the Default pricing configuration expands its country coverage worldwide, removing all its personalized localization settings.

Setup

1. Click the Add countries link in the eStore billing countries column of a pricing configuration to start adding markets/regions: Europe, the Middle East, and Africa, Asia-Pacific, Latin America, Rest of the World, and North America.
2. Select countries and assign them to the pricing configuration one by one or in bulk. Press and hold the Ctrl key to multi-select items. Once you added the countries for a local pricing configuration.
3. Click Save to save localization details of the pricing configuration and to activate it. When you assign all countries in a geographical region to a pricing configuration, 2Checkout displays the name of that region displayed under the eStore billing countries column. 2Checkout displays a maximum of five assigned standalone markets under the eStore billing countries column, for multi-market localized pricing configurations.

How do localized pricing configurations work?

Localized pricing configurations override the default pricing configuration when 2Checkout detects the shopper country. If the 2Checkout system can't determine the country of a shopper, the shopping cart display prices in accordance with the Default pricing configuration. However, if the shopper selects a country for which you defined a localized pricing configuration, the price details adapt accordingly.

Shoppers from countries not covered by any of their localized pricing configurations also see the price details of the default pricing configuration.

You can associate a specific country ONLY with a single localized pricing configuration at any given time. Re-assigning a country to another localized pricing configuration removes the market automatically from the localized pricing configuration it was part of.

While going through the stages of the purchase process, shoppers will be presented with the price set for the billing country selected in the cart (can be pre-selected, but users can also choose it manually). Per-product pricing details displayed to shoppers change if the billing country is modified to a different market governed by other pricing details. Shoppers will get this warning message in the cart: "The product options have been changed due to availability settings in the selected country."

Non-localized pricing configurations are also active, but not for eStore, as they can be used to supply price lists to your partners.

Localized pricing configuration options

You can create multiple pricing configurations for the same product, be as similar to one another or as different as you prefer. The following parameters can be completely different for multiple pricing configurations applied to the same product.

1. Pricing configuration type (with a base price, without base price, net, gross)
2. Price
3. Default currency
4. Pricing options
5. Renewal discounts
6. Volume discounts

As a result, they can control not only the actual price in accordance to specific geographic regions and countries but also pricing strategies.

Pricing localization and product SKUs

You have the option of configuring stock-keeping units (SKUs) each pricing configuration in the 2Checkout platform, and associate unique SKUs in accordance with the currencies, volume discounts (if any), purchase type and pricing options (if any) settings impacting products when localizing their pricing configurations. 

Upselling and Cross-selling

Localized pricing settings impact their upselling and cross-selling marketing campaigns.

upselling

When configuring upselling campaigns, you'll need to factor in localized pricing strategies for the primary and recommended products. There are four scenarios you need to consider, related to the type of upselling campaigns available.

As a rule of thumb, consider the default pricing configuration of your offerings as the central element of upselling campaigns when pricing options are also involved. In scenarios in which the Primary product of an upselling campaign has pricing options set up for the default pricing configuration, they'll also be available when configuring the upselling recommendation. Pricing options will not be displayed in the Upselling recommendation area when editing a campaign if they're only defined for the localized pricing configurations of the Primary product, but not the default.

Similarly, the pricing options of the Recommended product will only be displayed in the Upselling recommendation area when editing a campaign only if they were enabled for the Default pricing configuration. If not featured under the Default pricing configuration but only for localized pricing configurations, the pricing options will not be available when configuring upselling campaigns.

Cross-selling

Cross-selling campaigns function regardless of the pricing configurations set up for their products. Shoppers located in a country governed by a localized pricing configuration will be able to select the pricing options associated to their locale for the main products and for the cross-selling items as well.

However, if the products are automatically added to cart, they're pricing options will be locked, and shoppers won't have the possibility of editing them (offerings will come with pre-selected pricing options, and the system will disregard the availability of alternatives, which will never be displayed in the cart).

Localized pricing for subscription renewals

When renewing a subscription, the 2Checkout system will correlate the renewal price with that of the initial purchase. Renewal prices can be defined as a part of the default and localized pricing configurations for products with base and without base price.

Essentially, subscriptions initially acquired by shoppers in a specific market governed by a localized pricing configuration, will be renewed in accordance to the same pricing configuration and billing country. Renewal prices will not vary in any way, even if shoppers change the billing country to a market assigned to a different pricing configuration than the one from which they made the initial acquisition.

Renewals made by using the 2Checkout API are impacted by the same limitation, namely, the price will not adapt when the billing country is changed, but will reflect the market in which shoppers were located when they initially purchased the subscription.

Upgrades

When upgrading a product, the 2Checkout system correlates the upgrade price with that of the initial purchase.

2Checkout does not change the localized pricing configuration and billing country when upgrading a subscription, reflecting the initial purchase. Upgrade costs do not vary, even if shoppers change the billing country to a market assigned to a different pricing configuration than the one from which they made the initial acquisition.

Upgrades made by using the 2Checkout API are impacted by the same limitation, namely, the price does adapt when the billing country is changed, but will instead reflect the market in which shoppers were located when they initially purchased the product.

New purchases, renewals and upgrades through API - localized pricing

The 2Checkout API supports localized pricing capabilities.

New purchases

The billing country set by using 2Checkout API causes the price details to be adapted accordingly if you localized the pricing configuration for that specific market.  If there's no match between the localized pricing configuration and the billing country, 2Checkout uses the default pricing configuration used instead.

Upgrades

Upgrades through the 2Checkout API take into account the billing country associated with the initial subscription for the pricing details of the target subscription of the upgrade process. 2Checkout uses the localized pricing configuration of the target subscription plan in accordance with the billing country of the initial subscription.

Note: If the upgrade subscription/product does not feature a pricing configuration localized on a specific market, then the system uses the item's Default pricing configuration.

Renewals

Subscription renewals through the 2Checkout API use the price options from the localized pricing configuration, but you control the price and the billing cycle following the renewal independently of the subscription plan configuration.

Overview

Retrieve the costs of the next subscription renewal.

Attributes

Overview

Renew a subscription in the Avangate system on-demand, controlling the number of days, price and currency of the extension. Use the renewSubscription method renew a subscription.

Parameters

Response

Request

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

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$subscriptionReference = '30E47F8699';
$Days = 4;
$Price = 50;
$Currency = 'eur';
try {
    $CustomPrice = $client->renewSubscription($sessionID, $subscriptionReference, $Days, $Price, $Currency);
}
catch (SoapFault $e) {
    echo "CustomPrice: " . $e->getMessage();
    exit;
}
var_dump("CustomPrice", $CustomPrice);

Overview

Get access to information on specific orders, customers and subscriptions by easily building links to the Order, Customer and Subscription details pages in the Control Panel.

Availability

This feature is available to all 2Checkout accounts.

Requirements

The Control Panel user accounts accessing information on orders, customers and subscriptions require the following role privileges:

• eStore order search
• Customers
• Subscription Management

To edit user roles, go to Account settings -> Manage user access and click View roles. Edit the user role accordingly and click Save role.

Link parameters

Two parameters are key to building specific links. Both parameters are case sensitive.

• refno - used to build links to the Order details and Subscriptions details pages.
• avangateid - used to build links to the Customer details pages.

Order details page

Orders have unique identifiers associated by default. Use these identifiers combined with the refno parameter to build Order details page links.

Example

A link to the Order details page of an order with the 1234567 reference number:

https://secure.2checkout.com/cpanel/order_info.php?refno=1234567

Note: Order reference identifiers are integer values.

Refund orders

Refund orders share the same 2Checkout identifier as the original order. When building links for Refund order details page, you need to add the order status to the URL, together with the refno parameter. You can add the order status via the status parameter (case sensitive).

Example

https://secure.2checkout.com/cpanel/order_info.php?refno=1234567&status=refund

Subscription details page

Subscriptions also have unique identifiers associated by default. Use these identifiers combined with the refno parameter to build Subscription details page links.

Example

A link to the Subscription details page of a subscription with the 0A001B23C5 reference number:

https://secure.2checkout.com/cpanel/license_info.php?refno=0A001B23C5

Customer details page link

Customer accounts have unique 2Checkout identifiers. Use these identifiers together with the avangateid parameter to build links for Customer details pages.

Note: Use the internal, system-generated Avangate customer reference, and not the External customer reference which you control.

Example

A link to the Customer details page of a customer with the id 102407513:

https://secure.2checkout.com/cpanel/customer_details.php?avangateid=102407513

Overview

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

Create promotion                          Update promotion                            Retrieve a promotion                            Search promotions

Promotion object

Overview

Renew a subscription in the Avangate system on-demand, controlling the number of days, price and currency of the extension. Use the renewSubscription method renew a subscription.

Parameters

Response

Request

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

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$subscriptionReference = '30E47F8699';
$Days = 4;
$Price = 50;
$Currency = 'eur';
try {
    $CustomPrice = $client->renewSubscription($sessionID, $subscriptionReference, $Days, $Price, $Currency);
}
catch (SoapFault $e) {
    echo "CustomPrice: " . $e->getMessage();
    exit;
}
var_dump("CustomPrice", $CustomPrice);