Overview

Use the Control Panel to order trials for your customers in addition to placing new orders and purchasing upgrades on their behalf.

When ordering trials on behalf of customers you can have their payment details attached to the order. 2Checkout can use the payment information available to charge your customers automatically when the trial converts to the full product, unless shoppers cancel the process through the opt-out mechanism at their disposal.

At the same time, trial orders placed on behalf of customers can be charged to cards on file, enabling 2Checkout to charge the credit / debit cards used for previous purchase.

Requirements

PCI Data Security Standards (PCI DSS) compliance is strongly recommended for this feature. Please contact 2Checkout directly to enable the feature.

To provide users of your account with access to this functionality, follow the steps below.

1. Go to Account settings -> Manage user access.
2. Click Edit on a role.
3. Enable the Place orders on behalf of customer option.

Payment methods available

• Credit / debit cards
• PayPal

Place a trial order on behalf of your customers

1. Go to Orders & customers -> Customers.
2. Search for the customer for whom you want to order the trial.
3. Click View button to access the Customer Details Page.
4. Scroll down below the Customer insight and Customer billing details area and click on the Place new order button.
5. Select an existing credit / debit card from those on file, or opt to introduce new payment information.
6. Choose the order type. For the purposes of this example, select Trial.
7. Select the product whose trial you're ordering on behalf of the customer, choose the billing currency, and enter a coupon code if needed.
8. Define the Trial period. Enter at least 1 for a one-day trial.
9. Set a price for the trial or leave blank if the trial is free. You'll still be able to have cardholder data attached to the trial order and 2Checkout will charge customers automatically when trials are converted to full, paid products based on the payment information on file.
10. Customize the details of the trial further in the shopping cart.

FAQ

Can the quantity of the trial order be modified?

The Quantity option is not editable or displayed.

Can additional products or trials be added to a single order?

Currently this flow supports the purchasing of only one product or trial at a time.

The product I'm trying to order a trial for is not featured in the list of available offerings. Why is that?

This flow does not support bundles of products or products with physical delivery.

Overview

Use the getRenewalDetails method to retrieve information regarding subscription renewals based on Avangate Subscription References:

• Information on the  automatic renewal (recurring billing) status (enabled or disabled).
• The link that customers access to renew the subscription though a manual payment.

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';
try {
    $renewalDetails = $client->getRenewalDetails($sessionID, $subscriptionReference);
}
catch (SoapFault $e) {
    echo "renewalDetails: " . $e->getMessage();
    exit;
}
var_dump("renewalDetails", $renewalDetails);

Overview

2Checkout's data portability capabilities enable you to import and export products using the XML (Extensible Markup Language) file format.

Availability

Import/Export as XML is available for all Active and Inactive products.

Import/Export XML file syntax

Use UTF-8 character encoding.

Please ensure the import file adheres to the XML 1.0 specification syntax rules.

1. XML declaration: <?xml version="1.0" encoding="UTF-8"?>
2. <Export></Export> is the root element for the export and the import file.
3. XML elements feature start and closing tags, as long as there's information to be imported or exported: <Products> INFO </Products>. When no data is included or available, a single tag is sufficient : <AdditionalField/> .
4. XML tags are case sensitive. Use <Products> INFO </Products> and not <Products> INFO </products>.
5. XML attribute values must be quoted.
6. Use this syntax <!-- This is a comment --> for comments in XML.
7. White-spaces are preserved.

Overview

Use the getCustomerInformationBySSOToken method to retrieve the details of a customer entity from the 2Checkout system. Send the SSO token you create by generating tokenized cart payment links.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$idCustomer = '352365983';
$customerType = 'AvangateCustomerReference';
$url = 'https://store.avancart.com/order/checkout.php?PRODS=4639321&QTY=1&CART=1&CARD=2';
$validityTime = 50;
$validationIp = null;

try {
    $ssoLINK = $client->getSingleSignOnInCart($sessionID, $idCustomer, $customerType, $url, $validityTime, $validationIp);
}
catch (SoapFault $e) {
    echo "ssoLINK: " . $e->getMessage();
    exit;
}
var_dump("ssoLINK", $ssoLINK);
parse_str($ssoLINK);

try {
    $CustomerSSOInfo = $client->getCustomerInformationBySSOToken($sessionID, $logintoken);
}
catch (SoapFault $e) {
    echo "CustomerSSOInfo: " . $e->getMessage();
    exit;
}
var_dump("CustomerSSOInfo", $CustomerSSOInfo);

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 = date('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;
}
 
var_dump($sessionID);

$CartItem = new stdClass();
 
$CartItem->Code = 'my_subscription_1';
$CartItem->Quantity = 1; 
$CartItem->PriceOptions = array();

/* $CartItem->Trial = new stdClass(); 
$CartItem->Trial->Period = 8;
$CartItem->Trial->Price = 999; */

$BillingDetails = NULL;
$Currency = 'USD';
$CouponCode = '123';
$PayType = 'CC';

try {
    $itemPrice = $client->getPrice($sessionID, $CartItem, $BillingDetails, $Currency, $CouponCode, $PayType);
}
catch (SoapFault $e) {
    echo "itemPrice: " . $e->getMessage();
    exit;
}
var_dump("itemPrice", $itemPrice);

Overview

Use the savePrices method to update product prices for a specific pricing configuration.

Parameters

Response

bool(true)

<?php
require ('PATH_TO_AUTH');

/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Dynamic pricing configuration
 *
 * Send two prices, including the required one for the default currency
 * The method will append the prices for the sent entries, without removing the previous values
 *
 * If the quantities intervals were not defined then they will be set.
 * If the quantities overlap with existing defined intervals, an Exception will be thrown.
 */
 
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 140;
$Price->Currency = 'USD';
$Prices[] = $Price;
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 10;
 
$PriceOptions = array();
 
$PricingConfigurationCode = '5553603382';
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);

$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
// will output:
// bool(true)

 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the VOLTAGE pricing option group assigned and marked as required.
 * If prices are sent WITHOUT setting the pricing option group and options will set the price but without setting values for the options prices.
 */
 
// Call the login method for authentication
$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
$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);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
// if PricingOption group is not required, will set price for combination of QuantityInterval - no-pricing-option-value.
$PriceOptions = array();
 
// if PricingOption group is required, then send options by assigning a PriceOptionsAssigned object (group code and options)
// $optionAssigned = new stdClass(); // PriceOptionsAssigned
// $optionAssigned->Code = 'VOLTAGE';
// $optionAssigned->Options = array('220V'); // radio option group
// $PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the COLOR and scalenotmandatory pricing option group assigned and marked as required.
 */
// Call the login method for authentication
$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
$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);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 10;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'COLOR'; // checkbox pricing option group, multiple values are allowed
$optionAssigned->Options = array('cyan', 'magenta');
$PriceOptions = array($optionAssigned);
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'scalenotmandatory'; // interval pricing option group
$optionAssigned->Options = array('scalenotmandatory-1-5');
$PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PriceOptions = array();
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
?>

Overview

Include payment (credit/debit card) information that 2Checkout uses for recurring billing to renew imported subscriptions. Importing subscriptions with payment data is available only to eligible 2Checkout accounts. Contact 2Checkout directly for additional details.

Use the addSubscription method to import a subscription into the 2Checkout system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$Product = new stdClass ();
$Product->ProductCode = 'my_subscription_1';
$Product->ProductId = 4639321;
$Product->ProductName = '2Checkout Subscription Imported';
$Product->ProductVersion = 1.0;
$Product->ProductQuantity = 3;
$Product->PriceOptionCodes = array();

$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@2Checkout.com';
$EndUser->FirstName = 'Customer';
$EndUser->Language = 'en';
$EndUser->LastName = '2Checkout';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Fax = NULL;
$EndUser->Zip = '90210';

$Subscription = new stdClass();
$Subscription->ExternalSubscriptionReference = '12345678912ImportedSubscription';
$Subscription->SubscriptionCode= NULL;
$Subscription->StartDate = '2013-01-01';
$Subscription->ExpirationDate = '2017-12-30';
$Subscription->Product = $Product;
$Subscription->EndUser = $EndUser;
$Subscription->ExternalCustomerReference = '12354678ExtCustRef';

$PaymentCard = new stdClass ();
$PaymentCard->CardNumber = '4111111111111111' ;
$PaymentCard->CardType = 'VISA';
$PaymentCard->ExpirationYear = '2018';
$PaymentCard->ExpirationMonth = '12';
$PaymentCard->CCID = '123';
$PaymentCard->HolderName = 'John Doe';
$PaymentCard->HolderNameTime = '15';
$PaymentCard->CardNumberTime = '15';
$PaymentCard->AutoRenewal = true;

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

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

Overview

Move a subscription from under a customer to another customer entity.

Use the updateSubscription method. Avangate moves subscription under the customer for which you provide the Avangate customer reference or the External customer reference during the subscription update process.

Requirements

To move a subscription from a source customer to a target customer:

• Use Avangate customer references or External customer references belonging to the target customer. Avangate re-assigns the subscription to the target customer. 
• Customer references must be valid and associated to the target customer entity under which you move the subscription.

If you provide both the Avangate customer reference and External customer reference they need to belong to the same target customer entity.

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;
}
$SubscriptionReferenceTest = '0742B179DD';
try {
    $retrievedSubscription = $client->getSubscription($sessionID, $SubscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "retrievedSubscription: " . $e->getMessage();
    exit;
}
var_dump("retrievedSubscription", $retrievedSubscription);
var_dump ($retrievedSubscription);
$retrievedSubscription->AvangateCustomerReference = 172673064;
try {
    $updatedSubscription = $client->updateSubscription($sessionID, $retrievedSubscription);
}
catch (SoapFault $e) {
    echo "updatedSubscription: " . $e->getMessage();
    exit;
}
var_dump("updatedSubscription", $updatedSubscription);

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

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

$updatedSubscription = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($updatedSubscription);
$updatedSubscription->RecurringEnabled = false;
$updatedSubscription->SubscriptionEnabled = true;
$updatedSubscription->ExpirationDate = '2020-12-12';

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

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

Overview

Use the getIdealIssuerBanks method to retrieve the information on the 2Checkout 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

The 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.2checkout.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);

?>