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

Overview

2Checkout automatically sends out the payment confirmation email to provide shoppers with a confirmation of having successfully placed the order.

As of July 13th, 2016, you can use a redesigned template complete with fresh content. The new template has replaced the previous payment confirmation email, but any customization you have in place, either in terms of styling or content, continues to be available.

Availability

All 2Checkout accounts.

What is the purpose of this email?

2Checkout sends the payment confirmation email for all successfully placed orders for which it has started processing transactions.

Email content

The email includes one or several of the following:

1. Purchase details with information on ordered products, quantities, unit prices, taxes, and total amount.
2. Indication of next steps to be expected (the shoppers are informed they will be sent a payment receipt email once the payment is authorized and delivery information - if applicable).
3. Technical and payment support contact details.

Sample

Is this the only email my shoppers receive after placing an order?

2Checkout sends the payment confirmation email for all successfully placed orders.

Preview and test email

Navigate to the Email template manager section to:

• Preview and test current templates for emails sent to your shoppers
• Customize the header and the footer sections by creating custom templates you can assign to your emails

Access the payment confirmation email under the Order section.

Why don't I see the new template for this email?

The redesigned template for the payment confirmation email has automatically replaced default templates.

If your preview of payment confirmation email does not show the new template, you are most probably using a customized version that includes content and/or styling your company requested at a certain point in time.

You can compare the above sample to your current template and send us an email if you decide the new one suits your business needs better. We will work with you on the switch.

Overview

If you are leveraging 2Checkout lead management tools (set your campaigns here), our system automatically sends out the Follow-Up Auto email as part of the overall strategy to increase subscriber retention and the conversion rate of recurring charges. This notification makes it easy for subscribers to still renew their subscription in the case of scheduled recurring charges fail.

As of August 31, 2016, you can use a redesigned template complete with fresh content (sample below). The new template has replaced the previous Follow-Up Auto carts email, but any customization you have in place, either in terms of styling or content, continues to be available.

Availability

The lead management set of tools is available for Standard and Enterprise accounts. If you are running on our Growth offer and would like to receive access, please send us an email and we will discuss next steps.

What is the purpose of this email?

2Checkout performs dunning management for unfinished payments (declined) for auto-recurring charge attempts. Messages include links redirecting to a shopping cart where shoppers can manually purchase subscription renewals, but also links to their myAccount. The email covers failed transactions involving credit/debit cards, PayPal, direct debit, and recurring charges for subscriptions acquired through iDeal.

Email content

The email includes:

1. Link to the shopping cart for the manual subscription renewal.
2. Link to shopper myAccount.
3. Order, product, and subscription details.

Preview and test the email sample

Navigate to the Email template manager section to:

• Preview and test current templates for emails sent to your shoppers
• Customize the header and the footer sections by creating custom templates you can assign to your emails

Access the Follow-Up Auto email under the Follow-Up section.

Why don't I see the new template for this email?

The redesigned template for the Follow-Up Auto email has automatically replaced default templates.

If your preview of Follow-Up Auto email does not show the new template, you are most probably using a customized version that includes content and/or styling your company requested at a certain point in time.

You can compare the above sample to your current template and send us an email if you decide the new one suits your business needs better. We will work with you on the switch.

Overview

Use addPromotionProducts to add products to an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Define a product to add to the promotion
$newProduct1 = new stdClass;
$newProduct1->Code = '';
$newProduct1->PricingConfigurationCode = '';
$newProduct1->PricingOptionCodes = ['',''];

// Define another product to add to the promotion
$newProduct2 = new stdClass;
$newProduct2->Code = '';
$newProduct2->PricingOptionCodes = [''];

$productPromotion = [$newProduct1, $newProduct2];

try {
    $updatedPromotion = $client->addPromotionProducts($promotionCode, $productPromotion);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

Use the addSubscriptionUsage method in SOAP API 6.0 to add multiple usages at the same time.

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$SubscriptionReference = "B7D8E72224";

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->OptionCode = "scale";
    $subscriptionUsageRequest->UsageStart = "2025-03-02 10:00:10";
    $subscriptionUsageRequest->UsageEnd = "2025-04-01 10:00:10";
    $subscriptionUsageRequest->Units = 404;
    $response = $client->addSubscriptionUsage(
        $sessionID,
        $SubscriptionReference,
        [$subscriptionUsageRequest]
    );
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}
 exit;

Response 

The successful addSubscriptionUsage call via SOAP APIv6 returns the Usage object.

array(1) {
      [0] =>
      class stdClass#3 (9) {
        public $usageReference =>
        string(12) "120011112191"
        public $subscriptionReference =>
        string(10) "67F3AD6A32"
        public $optionCode =>
        string(6) "USG_MN"
        public $usageStart =>
        string(19) "2020-07-06 12:00:00"
        public $usageEnd =>
        string(19) "2020-07-07 12:00:00"
        public $units =>
        int(30)
        public $description =>
        string(0) ""
        public $renewalOrderReference =>
        string(0) ""
      }
    }

Error handling

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 6.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

Request Example

<?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);

?>

Response Parameters

Overview

2Checkout is the Merchant of Record for orders performed and payments processed using our platform. From a legal standpoint, this means we are responsible for the information provided to your shoppers via the emails sent, on your behalf, through our platform.

Consequently, there are several mandatory requirements to account for when customizing your emails. These requirements depend on the type of emails sent. 2Checkout emails generally fall into two categories:

• Transactional emails. According to CAN-SPAM rules, these emails facilitate an already agreed-upon transaction or update the customer about ongoing transactions. They usually contain order, payment, or customer-specific information.
• Marketing (commercial content) emails. According to CAN-SPAM rules, these emails advertise or promote commercial products or services.

Check the documentation available here to see the emails in each category.

Email requirements

Do not remove mandatory information when you customize the content of your emails.

Transactional email requirements

• Always include the reference to 2Checkout acting as Merchant of Record in Transactional emails (optional for Marketing emails). The structure we recommend using is the one in our default templates: “2Checkout acts as an authorized reseller of <Your Company Name> online products and services.” Localized versions are available for all default templates.
• Show 2Checkout support information in all Transactional emails. This includes the access link to the shopper myAccount along with the email address needed to log in. Keep in mind that we are the ones offering order and payment support, so make sure you provide shoppers with access to all support channels. This weighs a lot in turning them into loyal, long-term customers.
• Display merchant (your company) support information in all Transactional emails. This includes support email and phone numbers. This is critical to your shoppers when they need additional product/subscription information, troubleshooting services, or access modifications.

Marketing email requirements

• Include an unsubscribe option in all Marketing emails. Make it as clear, explicit, and simple to use as possible. We recommend keeping/including an unsubscribe link at the bottom of your message. You can use the UNSUBSCRIBE_LINK variable that takes the shopper to an unsubscribe page.
• Gmail and Yahoo updated their requirements for bulk senders making it mandatory to have one-click unsubscribe option in the header. This means that all emails with the exception of order confirmation, payment receipts, electronic delivery, access links and others will have an unsubscribe option in the header. 
  
  • The current unsubscribe mechanism ensures that the unsubscribe scope is limited to either a specific sale, lead or subscription. Take for example the case where you have configured 5 manual renewal reminders. The shopper receives the first manual renewal reminder and clicks on the “unsubscribe” link. The shopper will no longer receive any manual renewal reminders for that subscription renewal, but he would still be eligible to get the same type of reminder for other subscription(s) and even for the next renewal of the same subscription.
  • The below platform emails will have the one-click unsubscribe option in the header:
    
    • Abandoned cart (lead management)
    • Affiliate newsletter
    • Free trial download expiration
    • Manual renewal reminder
    • Recurring payment failed (Direct Debit)
    • Recurring payment failed (dunning notification)
    • Recurring payment failed (instant payment methods)
    • Unfinished payment (Direct Debit)
    • Unfinished payment (lead management)
    • Unfinished payment (Purchase order)

Shared requirements

• Always display the 2Checkout logo in either the header or the footer of the email. Make sure it is visible and distinctive against other elements. You can use the 2CHECKOUT_LOGO variable that shows the image at optimal dimensions.
• The subject line of your emails needs to be reflective of the content they communicate. Choose a relevant subject line to ensure your shoppers will continue opening emails sent on your behalf and keep these emails out of the spam folder.
• The content of your emails should always be related to the event triggering the email. For instance, build the Payment receipt email to include information on purchased products or subscriptions, quantities, unit prices, taxes, discounts, and total price, billing, and delivery information. Abandoned cart notifications should include a link to the abandoned cart, that the shopper can use to finalize the order.