Overview

Use the searchProducts method to extract information about the subscription plan/products you configured for your account.

Pagination

Use pagination to decrease the request loading time, while better handling the returning responses.

Pagination works on all the search methods existing on 2Checkout API 5.0. The default pagination behavior is to display page 1 with 10 results. The maximum number of items displayed on a single page is 200.

To use pagination, include the Pagination object inside the search method call, using the parameters below:

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$SearchOptions = new stdClass();
$SearchOptions->Name = '2Checkout Subscription'; //Product name
$SearchOptions->Types = array ('REGULAR', 'BUNDLE'); //product type (standalone), regular or bundle
$SearchOptions->Enabled = True;
//$SearchOptions->GroupName = '';
$SearchOptions->Pagination = new stdClass();
$SearchOptions->Pagination->Page = 1;
$SearchOptions->Pagination->Limit = 10;

try {
    $ProdSearch = $client->searchProducts($sessionID, $SearchOptions);
}

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

var_dump("Query", $ProdSearch);

?>

Parameters

Overview

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

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$productCode = 'YOUR_PRODUCT_CODE';
$fieldCode = 'YOUR_FIELD_CODE';

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

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

?>    

Response

bool(true)

Overview

Use this method to get information on the products added to the shopping cart during the current cart session.

Requirements

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

try {
    $CartContents= $client->getContents ($sessionID);
} catch (SoapFault $e) {
    echo "Contents: " . $e->getMessage();
    exit;
}
var_dump ("Contents ", $CartContents);

Errors

Overview

Offer free trials with payment details or paid trials to your shoppers.

Availability

This feature is available for 2Monetize accounts.

Requirements

Configure at least one subscription. 

Supported payment methods

Credit and debit cards, PayPal, and Direct Debit.

Workflow

1. Set up the subscription plan.
2. Generate the Trial Buy Link and serve it to shoppers.
3. 2Checkout collects customer and payment details and:
   
   • Pre-authorizes the transaction for free trials. 
   • Authorizes transactions and collects funds for paid trials.
4. 2Checkout automatically converts the trial to a paid subscription when the trial interval expires by charging shoppers based on the payment-on-file information. Customers can opt-out at any time using their myAccount. 

Generate a trial link

1. Access the trial link generation options in the Checkout Links area, under Dashboard → Setup → Generate Links. Alternatively, you can navigate to this page through the View Edit product section of the 2Checkout Control Panel, select the product you want to generate the trial subscription for, go to the Information tab, and click on Get trial links.
2. Click the Trial link radio button.

3. Select the product for which you're creating the trial. 

4. Choose the duration of the trial. Minimum 7 days. Default: 30 days. 

5. Configure the trial price. 0 by default, but you have the option of charging shoppers for the trials. To further modify pricing, you can use Additional pricing options. Input pricing options codes separated by commas. 2Checkout uses pricing options to calculate the costs of the automatic trial conversion.

6. Scroll down to the bottom of the page and generate the link.

7. Place the URL on call-to-actions on your store that offer access to trials. 

Customize the trial 

1. Trial period - Minimum 7 days. 
2. Trial price - 2Checkout uses the custom prices and ignores the per-product pricing configuration. 
3. Additional pricing options - Input pricing options codes separated by a comma. 2Checkout calculates the costs of the trial conversion based on the pricing options.
4. Advanced options - In the advanced options screen, you can specify the default language and billing currency for the checkout process.
   
   • Default language - AUTO preselected. Choose a specific language for the ordering interface.
   • Billing currency - AUTO preselected. Choose a specific currency for the ordering process. 
5. Additional options
   
   • Scroll down to the Additional options area, to choose the Order template displayed to your shoppers.
   • Enter a specific link source for the sales, and have the separate link identifier (SRC) to track every sale point generator (e.g. homepage, product page, etc.)
   • Provided that you defined a coupon code for the product you're generating the trial subscription for, insert it in the coupon code field. The appropriate discount is deducted from the full product price (and displayed in the shopping cart and/or checkout page).

Disable recurring billing for a trial

1. Navigate to Subscriptions management.
2. Search for the trial subscription you wish to update and edit it.
3. Click the Stop automatic billing button.

Re-enable recurring billing for a trial

Requirements

• The 2Checkout system needs to have available payment-on-file data for subscribers.
• To re-enable the auto-renewal (automatic billing) system, subscriptions must not be:
  
  • Lifetime, but instead have a recurring billing cycle defined.
  • Expired subscriptions with the expiration deadline in the past (before the moment when you attempt to re-enable recurring billing).

1. Navigate to Subscriptions management.
2. Search for the trial subscription you wish to update and click to edit it.
3. Click the Enable automatic billing button.

Checkout flow for trials

1. Shoppers land in the cart and see information such as Product/Subscription plan name, trial duration, total price, trial price. Payment details are also present in this form.

2. Shoppers also get information on the trial period and price after submitting their payment details, on the review order page. The message includes details such as the date when the trial subscription expires and the total amount that 2Checkout charges automatically for the trial conversion.

3. After placing the order, shoppers reach the Thank you page. 2Checkout also sends shoppers emails containing payment receipt confirmation as well as any download links and trial license keys. 5 days before the trial expiration date, the 2Checkout system sends an opt-out notification. If shoppers decide to cancel the trial, 2Checkout sends out a confirmation message of the cancelation. If shoppers do not cancel the trial, 2Checkout charges them automatically for the trial conversion.

Reporting

The Trial Conversion Rates report centralizes data on the number of trial customers converted into paying customers. The trial conversion rates are only available in scenarios in which payment details are mandatory for accessing trials.

FAQ

1. Can I set the trial price to zero?

Yes. 2Checkout displays a notification to shoppers selecting a card as a payment option, informing them that they will not be charged for the trial. As a standard practice, 2Checkout does pre-authorize cards & PayPal to ensure that the payment data provided by shoppers is valid. 

2. Free/paid trials with payment details Direct Debit

2Checkout also supports free/paid trials with payment details using Direct Debit.  Just as is the case for credit/debit cards and PayPal, when providing their payment details to access the trial, shoppers agree to the first and to subsequent recurring charges for renewals, if the product they're testing is a subscription.

Shoppers also have to provide valid banking information, including their name, bank sort code, and bank account number. 2Checkout checks the payment info and provides access to the trial only after successful validation (delivery only happens after the direct debit is confirmed).

3. Use CART and CARD parameters in the trial links

By default, shoppers need to go through the "Checkout page" purchase flow in order to access a trial for which they are supplying you with their payment details.

However, you can customize the ordering process using the CART and CARD parameters in the Buy link for your trials.

For example, use:

1. &CART=1&CARD=1

https://secure.2checkout.com/order/tr...df5c9cb9586c8b&CART=1&CARD=1

Using &CART=1&CARD=1 will let shoppers enter their payment information on the landing page, and then order the trial from the Review page.

2. &CART=1&CARD=2

https://secure.2checkout.com/order/tr...17e093da98477a&CART=1&CARD=2

Use &CART=1&CARD=2 to expedite the purchase flow as much as possible and let users provide all their details as well as order the trial on a single page, excluding the Review page completely.

4. How many keys does the shopper receive? 

One for the trial order, one for the full product order.

5. Will I be notified of trial orders through Electronic Delivery? 

Yes. You can also choose to send only one key and activate it for trial/ full functionality from your own system. Note: the product is delivered only once.

6. Is the recurring billing system enabled for trial subscriptions?

Trials renew automatically unless customers opt out. 

7. Is the shopper able to opt-out of the automatic renewal? 

Yes, at any time, via 2Checkout myAccount. You can also disable the trial.

8. When is the auto-charge notification sent to shoppers? 

Five (5) days prior to the trial expiration date.

9. When is the customer charged for the full product?

• When the trial renewal interval is smaller or equal to six (6) months, the 2Checkout system attempts to charge customers three (3) hours prior to expiration.
• When the trial renewal interval is larger than six (6) months, 2Checkout makes the first attempt to charge shoppers two (2) days prior to the trial expiration date. 2Checkout makes a subsequent attempt one day before the subscription/license is set to expire.

These periods are set to avoid customer dissatisfaction from service interruption due to expired cards, insufficient funds, etc.

10. What is the minimum trial period? 

Seven (7) days.

11. Are trial subscriptions impacted by pre-expiration billing attempts activated as part of Advanced Revenue Recovery Tools?

No, the only billing attempts applicable to trial subscriptions are the ones on the day of the renewal and after expiration.

Reporting

The Trial Conversion Rates report centralizes data on the number of trial customers converted into paying customers. The trial conversion rates are only available in scenarios in which payment details are mandatory for accessing trials.

Overview

Use this method to extract the reseller information defined for a specific order.

Requirements

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

$refNo = 'YOUR_ORDER_REFERENCE';

try {
    $reseller= $client->getOrderReseller ($sessionID, $refNo);
} catch (SoapFault $e) {
    Echo "Reseller: " . $e->getMessage();
    exit;
}
var_dump ("Reseller ", $reseller);

Errors 

Overview

Use the updateSubscriptionPaymentInformation method to update the credit card information related to the payment to be made for a subscription. To be able to do this, you need to generate a payment token using the credit card information via the 2Pay.js library, and then use this token in the request of the method as indicated below.

Request Parameters

Request Example

<?php

declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'updateSubscriptionPaymentInformation';
    public const ADDITIONAL_OPTIONS = null;
    public const SUBSCRIPTION_REF = 'YC9XXMGOYO';
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "PaymentDetails": {
    "Type": "EES_TOKEN_PAYMENT",
    "PaymentMethod": {
      "EesToken": "f6347256-bbbb-45a8-be61-e21fe1725f47",
      "Vendor3DSReturnURL": "www.3dsReturnURL.com",
      "Vendor3DSCancelURL": "www.3dsCancelURL.com"
    }
  }
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object
    {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }

        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, Configuration::SUBSCRIPTION_REF, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url . '?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
       // $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Response

The method responds with Boolean True when the payment information update was successfully performed.

Otherwise, in case of validation or access rights failures, it returns the usual error response with specific messages indicating the cause of the failure.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ xmlns:ns1="urn:order" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/ SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/>
    <SOAP-ENV:Body>
        <ns1:updateSubscriptionPaymentInformationResponse>
            <updateSubscriptionPaymentInformationReturn xsi:type="ns1:PaymentDetailsCard">
                <CardType xsi:type="xsd:string">visa</CardType>
                <FirstDigits xsi:type="xsd:string">4012</FirstDigits>
                <LastDigits xsi:type="xsd:string">9936</LastDigits>
                <Authorize3DSUrl xsi:type="xsd:string">http://...</Authorize3DSUrl>
            </updateSubscriptionPaymentInformationReturn>
        </ns1:updateSubscriptionPaymentInformationResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Overview

Extract information on a specific list of subscriptions. Use the getSubscriptions method to retrieve details about a specific list of your account’s subscriptions.

Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$SubscriptionReferences = array('REFERENCE1', 'REFERENCE2', 'REFERENCE3');

try {
    $ListofSubscriptions = $client->getSubscriptions($sessionID, $SubscriptionReferences);
}
catch (SoapFault $e) {
    echo "ListofSubscriptions: " . $e->getMessage();
    exit;
}
var_dump("ListofSubscriptions", $ListofSubscriptions);

Overview

Use theTwoCoInlineCart.card.addCoupons(['COUPON'])method to apply multiple coupons.

Use case - Add Coupons

1. Add an HTML link or button in your page like the one below.
2. Create a JavaScript click handler to execute the Inline Client desired methods.
3. Use the TwoCoInlineCart.products.add({code, quantity, options})method to prepare your catalog product.
4. To apply several coupons to your cart products, use theTwoCoInlineCart.card.addCoupons(['COUPON'])method.
5. To show the cart on your page call theTwoCoInlineCart.cart.checkout()method.

Sample request

HTML

<a href="#" class="btn btn-success" id="buy-button">Buy now!</a>

JavaScript

window.document.getElementById('buy-button').addEventListener('click', function() {
  TwoCoInlineCart.products.add({
    code: "74B8E17CC0"
  });
  TwoCoInlineCart.cart.addCoupons(['CUPON']);
  TwoCoInlineCart.cart.checkout();
});

Demo

After setting the test mode to add coupons to the InLine Checkout using the above method, your cart should look like this:

Overview

Use the getSingleSignOnInCart method.  Avangate attaches a unique token to links, designed to identify the returning shoppers and support the automatic extraction of payment data and billing information from the Avangate system. For example, you can generate single sign on in cart links for existing customers logged into your website based on their external or Avangate customer IDs.

How does this work?

When accessing the shopping cart using tokenized payment links:

• Avangate prefills automatically customer billing and delivery details associated with their Avangate customer accounts (linked based on their unique customer IDs).
• Avangate presents shoppers with an optimized payment area featuring the credit / debit cards used to make previous purchases / transactions in the Avangate system. Customers have the option of selecting one of the payment methods depending on available card-on-file data.

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;
}
$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);