Overview

Use the getAdditionalOrderFields method to extract information about additional fields you set up for your account.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getAdditionalOrderFields ',
'params' => array($sessionID)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

?>

Response

Prevent Payment Failures

Intelligent Payment Routing enables you to match or route card transactions to the payment gateways best equipped to handle them and retry authorizations using a failover or back-up gateway. We recommend taking advantage of this feature to:

• Provide automatic support for switching and optimization between multiple payment processors around the world.
• Increase conversion rates.
• Reduce the volume of unfinished payments.
• Shift riskier transactions to secondary gateways to protect relationships with primary providers.

Analyzing a sample of 2Checkout vendors, we have seen an average uplift between 2% and 5% in their authorization rates using this fallback system.

An equally important aspect is routing transactions to local payment processors in countries such as the USA, Brazil or Turkey.

After using local payment processing, many of our vendors have seen up to 40% increase in authorization rates in the aforementioned markets.

Ensure Billing Continuity

The best way to handle the incoming wave of account number changes is to use an Account Updater.

Account Updater is a generic term for programs such as Visa's Account Updater or MasterCard Automatic Billing Updater that are offered by the credit card networks to automatically exchange updated credit card account information between participating issuers, acquirers, and merchants.

The programs record changes to credit card account numbers and expiration dates due to mergers, portfolio flips (e.g., Visa to MasterCard), re-issued cards (from loss or security breach) account closures, and product upgrades. Companies that participate in updater programs have several ways to check the information in their subscriber database:

• Automated nightly updates that check any card you have processed in the past six months.
• Requests for information on specific cards that have been declined.
• Requests for information on a set of cards due for their next billing installment.

The 2Checkout Account Updater has so far helped our vendors grow their recurring revenue in multiple ways:

• Salvage over 90% of otherwise unusable cards used for recurring billing.
• Seamlessly update state (out of date) credit/card accounts.
• Increase retention by up to 40%.
• Increase customer loyalty by eliminating service disruption.

Increase Authorization Rates for Expired Cards

Credit cards in your database slip past their expiration date on a monthly basis. The account number hasn't changed, and the subscriber still wants to receive your service, but when you attempt to bill that card, the payment is declined -- or your gateway won't let you submit it at all -- because the card is expired.

2Checkout allows you to identify expired cards and update them on file (standard banking procedures to prolong expiration dates), so that stale expiration dates don't deny you revenues or threaten your relationship with a perfectly happy subscriber. You can retry those payments and recover up to 90% of payments that initially had been declined due to expired cards.

We also recommend you create a report to track each retry attempt and its results. That way, you'll be able to see how many payments you're recovering at each step and notice any changes in the trend.

For instance, adding three years to the date tends to recover a higher percentage of payments now, but in the past adding two years was slightly more successful. The optimal approach is always a moving target, but with good tracking, you'll be able to adapt to the changes.

We’ve seen an average authorization rate uplift of 4% after some of our vendors started taking advantage of this mechanism.

Increase Recovery Rate and Minimize Payment Failures

Configurable Retry Logic enables you to automatically recover payments for soft card declines. Soft declines refer to temporary issues, with a high probability that a subsequent try would be successful.

We recommend that you adapt the number of retries and retention strategy to your business and customer base, and we can provide guidance on optimizing conversion rates.

Soft decline reasons include:

• Insufficient funds
• Card activity limit exceeded
• Processing failures due to system, technical or infrastructure issues
• Expired cards

2Checkout’s Retry Logic proved to successfully recover up to 20% of failed transactions due to soft declines.

More extreme situations may result in hard declines, due to stolen/lost cards and/or invalid card data. We no longer attempt authorizations for subscriptions for which the initial card charge results in a hard decline. Unless you target those customers with your own retention strategies, such subscriptions expire.

Reduce Churn and Recapture Revenue

Use our Authorization and Revenue Recovery Dashboard to monitor the impact of your recovery strategies and use the insight to adjust and optimize your tactics to reduce churn and recapture more revenue.

• Gain unmatched transparency and visibility into subscription renewals and recurring billing.
• Access extensive authorization data to optimize retention strategies.
• Gain granular-level insight at the subscription level into the activities of the Retry Logic and Account Updater tools.
• Take advantage of data portability to support third-party marketing and retention campaigns.

Around 16% of successful automatic renewals registered by 2Checkout are currently recovered through our auto-renewal enrollment and churn prevention campaigns.

Recover Revenue from Unfinished Payments

Dunning is the process of methodically communicating with customers to ensure the collection of accounts receivable. Our dunning management tools help you reduce customer churn and recover lost revenue from failed authorizations. We notify customers via email about failed renewals, helping them update their payment information in myAccount.

We automatically attempt to authorize a recurring charge for a subscription according to its renewal deadline. If the authorization process fails with a hard decline - a permanent error from the payment processor/gateway indicating that any further authorizations would also be unsuccessful – then the dunning management tools come into play.

We send a single dunning management email immediately after each failed automatic authorization attempt made for subscriptions with the auto-renewal system enabled. As soon as the shoppers update their payment information, we automatically attempt to authorize the payment and renew the subscription.

2Checkout’s dunning management tools led to an average of 1% increase in authorization rates.

Overview

Use the getCustomerInformation method to retrieve the details of a customer entity from the 2Checkout system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXT_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference

$jsonRpcRequest = array (
'method' => 'getCustomerInformation',
'params' => array($sessionID, $customerReference, $externalCustomerReference),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

Use setPromotionDiscount to set a fixed promotion discount.

Parameters

Response

Request

<?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 = 'setPromotionDiscount';
    public const ADDITIONAL_OPTIONS = null;
    public const PROMOTION_CODE = "AB3WMME0UA";
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "Type": "FIXED",
  "DefaultCurrency": "USD",
  "Values": [
    {
        "Currency": "USD",
        "Amount": 10
    },
    {
        "Currency": "EUR",
        "Amount": 10
    }
  ]
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION,
        string $promotionCode = Configuration::PROMOTION_CODE
    ): ?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, $promotionCode, $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);
}

Set LCN triggers and contents 

In your Control Panel account, navigate to Dashboard → Integrations → Webhooks and API and click on the LCN Settings tab. In the General LCN Settings section, under Triggers, select the events for which 2Checkout sends notifications.

License Change Notification (LCN) provides automatic notifications for orders from the 2Checkout system, based on the below list of triggers you control.

LCN Triggers 

Here's a list of the events for which you can trigger notifications. from Control Panel. You can set the triggers (when the notification will be sent) and what tags (parameters) will be included in the response from Control Panel. Find further information on LCN parameters here.

LCN triggers - API calls

Overview

2Checkout supports 1-click purchases for returning customers who paid for their previous orders with:

• Credit/Debit cards
• PayPal
• iDEAL
• Alipay
• UnionPay

How does this work?

1. Identify returning customers.
2. Access data on the previous purchases of returning customers.
3. Validate previous order references for 1-click purchase scenarios using the isValidOrderReference method (explained below).
4. Place a new order using a valid previous order reference as the payment method.
5. 2Checkout charges returning customers using their payment-on-file information, either a card or their PayPal account.

Requirements

• Use only references to previous orders with one of the following statuses AUTHRECEIVED or COMPLETE.

• The email address of the BillingDetails object is mandatory and it needs to match the email address used as a part of the billing details of the initial order whose reference you're now using to place a new order. 2Checkout checks whether the email addresses are identical, and throws an error if they're not, blocking the order placement process.

   

  You have the possibility of providing only the email address of the shopper, and can ignore the rest of the required customer billing information. This way the rest of the billing information will be pre-filled from the order used as payment reference. If you enter any billing details in addition to the email address, you'll have to provide all information required in the BillingDetails object.

Parameters

Response

Validate previous order reference

<?php
require('PATH_TO_AUTH');
$orderReference = '670174996';
try {
    $validOrderRef = $client->isValidOrderReference($sessionID, $orderReference);
}
catch (SoapFault $e) {
    echo "validOrderRef: " . $e->getMessage();
    exit;
}
var_dump("validOrderRef", $validOrderRef);
try {
    $existentOrder = $client->getOrder($sessionID, $orderReference);
}
catch (SoapFault $e) {
    echo "existentOrder: " . $e->getMessage();
    exit;
}

Place an order using previous order reference 

<?php
require('PATH_TO_AUTH');
$oldOrderExistent = callRPC((Object)$jsonRpcRequest, $host, true);
$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Email = $oldOrderExistent->BillingDetails->Email;;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'PREVIOUS_ORDER';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->RefNo = $orderReference;
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;
try {
    $newOrderPaidWithPreviousRef = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrderPaidWithPreviousRef: " . $e->getMessage();
    exit;
}
var_dump("newOrderPaidWithPreviousRef", $newOrderPaidWithPreviousRef);
?>

Overview

Use this setup to force a delay between the moment of authorization and the actual payment capture. Add a buffer period between the moment the payment is authorized and the actual completion date of the order, so you can check if you have enough stock for the products you’re selling or do additional background checks on the customers that place orders, to identify potential fraudulent purchases.

Availability

Capture delay is a set-up available only on request. Contact 2Checkout for more information.

Workflow

The recommended capture delay interval is 48 hours after payment authorization. Capture delay is valid for a period of up to 7 days from the authorization of the payment. After 7 days, the authorization expires, and the amount will be reversed back to customers by their bank.

Tangible products (catalog or dynamic) with catalog shipping

Intangible and dynamic products with dynamic shipping 

Payment methods

Capture delay can be applied to new purchases, renewals (only for the first billing cycle), and upgrades paid by credit cards.

Use cases

Overview

Set the test mode in order to use card-based payment methods and eCheck/ACH using test cards and test cardholder names.

Use case

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 theTwoCoInlineCart.products.add({code, quantity, options})method to prepare your catalog product.
4. In order to test mode useTwoCoInlineCart.cart.setTest(true).
5. Use theTwoCoInlineCart.cart.checkout()method to show the cart on your page.

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.setTest(true);
  TwoCoInlineCart.cart.checkout();
});

Demo

After adding the products to the InLine cart using the above method for testing purposes, your cart should look like this:

Test cards