Use the variables in the list below to customize the Trial expiration notification shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.

Overview

Use this guide to prepare and migrate your 2Checkout API implementation from version 1.0 to 3.0. This document features deprecations, updates and enhancements, providing guidance on how to upgrade your implementation to the latest version of the 2Checkout API. 

API 1.0 discontinuation

2Checkout plans to discontinue API 1.0 as of the end of February 2017. The end-of-support date implies ceasing all development of bug fixes and patches for API 1.0. 

API 3.0 availability

Version 3.0 of the 2Checkout API is available as of June 2016, following an extensive public testing phase started in November 2015. 2Checkout recommends that you migrate to the latest version of the API (v3.0) to enjoy support for your implementation.

API 3.0 updates and benefits

1. Full REST support for existing platform functionalities in addition to SOAP and JSON-RPC.
2. Simplify interactions with single-entry point (one endpoint, one client, single-authentication).
3. Centralized all previous functionality under 3.0 (plus new capabilities).

4. Unified WSDL for Order, Subscription, and Product scenarios.

Serializations 1.0 vs. 3.0

Single API URL per serialization format

• https://api.avangate.com/rpc/3.0/
• https://api.avangate.com/soap/3.0/
• https://api.avangate.com/rest/3.0/
• https://api.avangate.com/3.0/ redirects to  https://api.avangate.com/rest/3.0/ by default

WSDL 1.0 vs. 3.0

When you migrate from API 1.0 to 3.0, stop using https://secure.2checkout.com/api/merchant/?wsdl in favor of https://api.2checkout.com/soap/3.0/?wsdl.

Methods 1.0 vs. 3.0

New use cases API 3.0 

​

Overview

Direct Debit is a payment method in which the bank processes payments by accessing funds from an account when the holder instructs it to do so. It authorizes the organization you want to pay to collect the money from your account, but only after you've been notified of the amounts and dates of collection.

Once you have agreed on the payment details, the money is deducted automatically. If the organization you are paying wants to change an amount or date of collection, they have to notify you before the changes take place.

Currency

Direct Debit UK supports only GBP.

Mandates and E-mandates

Shoppers authorize 2Checkout to collect payments and instruct their banks to pay those collections with mandates.

• 2Checkout uses e-mandates and does not require shoppers to fill in and submit paperwork.
• Mandates expire within 36 months after the last initiated collection.
• 2Checkout stores mandates at least for 14 months after the last collection of funds.

Workflow

To set up payments by Direct Debit UK, the shopper must complete a Direct Debit instruction to you. The instruction makes it clear that shopper allows you to debit their account. The interface for completing the Direct Debit instruction is controlled by 2Checkout. After the shopper fills in the form, 2Checkout sends the data to the payment processor and to the shopper's bank, via BACS.

Direct Debit UK orders take 21 calendar days to be confirmed. During this interval, shoppers can cancel their order regardless of the reason and receive a refund.

The Direct Debit UK rules allow the instructions to be completed by using an online application form.

Purchase flow

1. Shoppers fill in the billing information, select United Kingdom as the billing country and choose Direct Debit UK as the payment option. Before they can continue, there are two mandatory questions that they need to answer to confirm the ownership of the bank account.
2. Shoppers fill in the Direct Debit UK payment details.
3. They confirm the payment details. Important: If the details are incorrect, they can edit them.
4. The order is finalized. Important: Shoppers can print the order details if needed.
5. 2Checkout sends the Advance Notice Letter to the shoppers informing them about the payment details.
6. The payment is processed and the money is deducted from the shoppers' account.

Emails

2Checkout sends the Advance Notice Letter email to shoppers upon placing the order.

Order statuses

Once the shoppers place an order, 2Checkout shows it as In progress / Processing. Following the fulfillment, the order status changes to COMPLETE. If the shopper's bank rejects the payment, the order shows up as Canceled.

Refunds

2Checkout only offers support for full refunds for orders paid for via Direct Debit UK. Partial refunds are not supported.

Shoppers can ask for a "no-questions-asked" refund right during the eight weeks (56 days) following the debiting of a shopper's account. This period is extended to 13 months for unauthorized Direct Debit collections.

Overview

Use this object to create / update information on additional order/product fields. 

Parameters

Overview

2Checkout myAccount offers billing charges alignment (or co-termination) capabilities to customers owning two or more active subscriptions for different products acquired from you, with unsynchronized expiration/renewal dates. The co-termination process enables the proration of subscriptions, setting a single renewal date for multiple items.

2Checkout renews subscriptions sharing the same co-termination date as part of a single order. As a direct result, following the renewal process, 2Checkout issues a single invoice to customers.

Aligning subscriptions is a customer-side feature. 2Checkout does not align subscription billing cycles automatically.

Requirements

1. Subscriptions must be associated with different products purchased from the same company.
2. Subscriptions must be associated with different products purchased by the same customer (defined through Avangate Customer Reference (ID) and/or AV_CUSTOMERID External Customer ID). This means that you need to aggregate subscriptions under the same customer.
3. Subscriptions status must be Active or Past due (in the grace period), but not expired or disabled.
4. Recurring billing (auto-renewal system) needs to be enabled for subscriptions.
5. 2Checkout aligns subscription expiration/renewal dates chronologically. Shoppers can align the next recurring billing date of a subscription that’s renewing on March 10 with one that’s renewing on March 11, but not the other way around.
6. Subscriptions need to share the same billing cycle.
7. Co-termination is available only for subscriptions associated to products for which customers used a credit/debit card for the initial purchase. Supported cards: VISA, MasterCard, AMEX and Discovery.
8. Transactions for the initial orders which generated the subscriptions must share the same currency.
9. Subscriptions for which billing involves both a base, recurring cost and a dynamic expense component (usage) incurred for metered resources consumed cannot be aligned with other subscriptions.
10. This feature does not work for imported subscriptions.

Billing alignment flow

Customers can align subscription billing charges via myAccount. Let's assume that Customer A has acquired Subscription 1 on May 31 and Subscription 2 on June 1. Both are monthly subscriptions set to renew automatically.

1. Customer A logins into https://secure.2checkout.com/myaccount.
2. Selects the My Products tab https://secure.2checkout.com/myaccount/my_products/?.
3. Clicks the Align invoice date link for Subscription 1.

1. 2Checkout displays a list of eligible subscriptions (items that match the requirements listed above), and Customer A selects Subscription 2.
2. 2Checkout provides details of the alignment. The process involves extending Subscription 1 to align it with Subscription 2, whose upcoming billing is the same as the co-termination date of the two items. To enable the extension, Customer A needs to pay the costs of the extra interval added to the lifetime of Subscription 1.
3. When clicking the Continue button, 2Checkout redirects Customer A  to a shopping cart where he/she can make the payment.

Aligning billing charges for multiple subscriptions

In case customers need to align additional items beyond the first two subscriptions, all they need to do is follow the steps enumerated above, but they can do so only one subscription at a time. Provided that all requirements are met and the 2Checkout system identifies eligible items, additional subscriptions can be aligned with those already sharing the same co-termination date. 

IPN and LCN

2Checkout sends out Instant Payment Notifications for transaction that aligns subscription charge dates. Following the alignment process, 2Checkout provides IPNs for transactions made when renewing multiple subscriptions.

2Checkout sends standalone License Change Notifications for each standalone subscription when updates occur, even for aligned items.

Co-termination costs

While shoppers won't be charged extra for configuring common expiry dates (co-termination dates) for their ongoing subscriptions, they will need to pay the costs of prolonging the lifetime of the aligned subscription.

The alignment charge is the prorated price that customers need to pay to cover the costs of the interval of time that the subscription is prolonged in order to align its billing cycle to that of the target subscription that provides the co-termination date.

The initial price displayed to shoppers in myAccount represents the cost estimate of the transaction and does not include taxes. The final prorated price, including taxes, is displayed in the shopping cart, as customers advance through the stages of the co-termination process.

Renewal notifications

2Checkout sends out standalone renewal notifications for each subscription, regardless of the fact that their billing cycles are aligned or not.

Follow-ups

2Checkout sends follow-up messages for all subscriptions with the same co-termination date, provided that their billing cycles were aligned.

Grace period

Per-subscription or global Grace period settings are not impacted by this feature, even for subscription whose billing charges were aligned.

FAQ

1. Can trial subscriptions be aligned?

This feature does not apply to trial subscriptions.

2. What happens if a subscription previously aligned with another/others is upgraded?

The billing charge alignment will no longer work, and each subscription will be renewed as a standalone item by the 2Checkout system.

3. What happens a subscription that I previously aligned with another/others is renewed with a new product version?

The billing charge alignment continues to work as before.

Overview

Add/import subscriptions in the 2Checkout system. Include card data with your subscription import only if you contacted 2Checkout to enable this functionality for your account. Otherwise, the import process results in a failure. Contact 2Checkout or your account manager directly for more details.

Parameters

Card payment

Add credit/debit card details when importing subscriptions. 2Checkout uses payment information in the recurring billing process. 

For imports of test subscriptions, use the credit card information from this article.

Overview

Starting with 2Checkout API 5.0, search methods are including the option of pagination. Pagination has been developed for decreasing the request loading time, while allowing you to better handle the returning responses.

How it works?

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.

Parameters

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

Response

The response of search methods that are including pagination will contain a new object, with the following parameters:

Sample request

The below PHP sample includes a search method for subscriptions.

<?php

require('PATH_TO_AUTH');

$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'email@avangate.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default)
$SubscriptionSearch->Pagination = new stdClass();
$SubscriptionSearch->Pagination->Page = 1; // set the number of pages for the response
$SubscriptionSearch->Pagination->Limit = 200; // set the limit for the values from the response

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

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

Overview

Boleto/Pix is a payment method tailored for international e-merchants, designed to make it easy for them to receive money from Brazilian customers. The Boleto/Pix credit transfer service enables customers in Brazil to make online purchases via 2Checkout and pay offline at any Brazilian post office, bank branch, or through Internet banking. Boleto/Pix has grown to a market share of approximately 25% in Brazil.

Recommended resources

Availability

Available for merchants on 2Sell, 2Subscribe, 2Monetize accounts and to all shoppers in Brazil. Boleto/Pix is supported in the ConvertPlus ordering engine.

Requirements

Shoppers need to provide their CPF (Fiscal Number) in order to pay through Boleto/Pix.

Shopper flow

1. When placing an order, shoppers in Brazil can select Boleto/Pix as a payment option.
2. Shoppers will have to provide their CPF (Fiscal Number), which is unique to Brazil, on the next page, and will receive an email confirmation.
3. In order to complete the order,  shoppers will need to generate the boleto (banking ticket), by clicking Generate Boleto.
4. Customers need to print the payment slip (Boleto) which contains a bar-coded invoice and take it to one of the convenient Boleto locations. Boleto can easily be paid via Internet banking, at ATMs, at any branch of associated banks or at one of more than 13.000 Brazilian lottery agencies. Shoppers can finalize the transaction using cash or any other accepted payment method.

Payment confirmation

Once the order is paid, the payment should be processed by 2Checkout within three hours. An email containing the product/licensing information will be sent to the email address used by the shopper during the checkout process.

Overview

Retrieve the costs of the next subscription renewal.

Attributes