Overview

This section includes documentation for the old 2Checkout API.

Getting started

Integrating with 2Checkout is easy. We provide several methods of integration to best fit your needs and support 7 different server-side languages. Follow the steps below to begin your integration.

Learn how to integrate

Use our documentation to learn how you can integrate your site with our service. Test our INS (Instant Notification System), the Admin API, Shopping Cart Integration, and any one of our checkout experience offerings. Select from one of the programming languages listed below to view all specific documentation.

• PHP − You can view the PHP library setup instructions on Github.
• Ruby − You can view the Ruby library setup instructions on Github.
• Python − You can view the Python library setup instructions on Github.
• Java − You can view the Java library setup instructions on Github.
• Microsoft .NET − You can view the .NET library setup instructions on Github.
• Node.JS − You can view the Node.JS library setup instructions on Github.

Overview

This section offers you all the information you need on the creation and use of both manual subscription renewal and upgrade links for your customers and the data protection layer offered by the 2Checkout platform in line with compliance best practice standards.

In this section read more about:

• Data protection for custom links
• Custom upgrade links
• Subscription renewal links

Overview

2Checkout offers you the option to create custom renewal or upgrade links, that you can provide your customers with the relevant communication channel of your choice. This is an alternative to, for example, the automatically-generated renewal links that our platform sends as part of renewal reminders to your shoppers or makes available through the customer myAccount. 

If the path you choose is the one where you, as a merchant, create these links and share them with your customers, extra attention needs to be paid to make sure you distribute the links to the rightful owners of those respective subscriptions. Not only the money they spend is at stake, but also exposing personal information (which falls under strictly regulated areas both inside the EU, as well as the US). 

2Checkout has the obligation to make sure data is protected, therefore whenever the custom link path is chosen by you, shoppers will have to pass an extra validation step in the checkout process in order to confirm they are indeed the owners of the subscription they are attempting to renew/upgrade.  

Availability

This setting is available to all standard 2Checkout account types: 2Sell, 2Subscribe, and 2Monetize, for both PSP and MoR accounts created post-December 10, 2021. We will gradually enable it for all accounts created before this date.  

Benefits

2Checkout is adding an additional safety measure to make sure custom links reach the rightful owners of subscriptions without the need for you to build any additional logic on your side.

Workflow 

The same flow described below applies regardless of the shopping cart you are using, the theme, or the flow you have chosen. 

When shoppers click on a custom renewal/upgrade link you have previously sent, they will be reaching an intermediary page where they are asked to fill in their delivery email address associated with that subscription. 

Hosted Interface Default Layout

ConvertPlus Default Theme Layout

InLine Cart Layout

If there is a match between the delivery email address the shopper fills in and the one stored in the 2Checkout system on the original subscription, the shopper immediately reaches the shopping cart and continues the usual renewal/upgrade flow.

The shopper has three attempts to pass this validation step. If by the third attempt, the shopper fails to enter a matching delivery email address associated with their subscription, 2Checkout will display a warning message shown in the image below.

Hosted Interface Default Layout

ConvertPlus Default Theme Layout

InLine Cart Layout

The email also includes either a renewal or an upgrade link that is digitally signed by 2Checkout. This means that if the customer remembers the original email address and has access to that mailbox, they will be able to click on the relevant link once they open the email received from 2Checkout.

To address those valid scenarios where the original email address is not available anymore (e.g., it belongs to a fellow employee that left the company), the message prompted on the intermediary screen also suggests, as an alternative, reaching out to you. At that point, you will be able to identify the customer, and, if relevant, you can modify the delivery information belonging to that subscription. It will be an informed decision on your side that will also help you store the most up-to-date and relevant information on the owners of your subscriptions.

Overview

As 3D Secure (3DS) becomes a mandatory part of the payment experience fror merchants and shoppers inside the European Economic Area, we recommend migrating to API version 6.0 in order to benefit from all the advantages of 3DS 2 and not experience any loss of conversion.

Find out more about 3DS here.

Adding 3DS to the 1-click purchase flow

In order to add support for 3DS to the 1-click purchase flow for new acquisitions, the same steps needed for Credit Card payments must be covered. The full 3DS flow is detailed here.

Renewal orders payed using 1-click purchase are not required to follow the 3DS flow.

In order to adapt the existing calls, 3 steps need to be done.

Step 1 - Migrate to API 6.0

Before adding the needed parameters for 3DS, make sure you are using version 6 of the 2Checkout Public API. If you are not using our latest API version, you need to migrate. This can be done easily by updating the endpoints where the placeOrder call is made, as the request body does not change between versions. The URLs you need to use for versions 6 are:

• REST: https://api.2checkout.com/rest/ 
• SOAP: https://api.2checkout.com/soap/6.0/ 
• JSON-RPC: https://api.2checkout.com/rpc/6.0/ 

Step 2 - Adapt the request body

The first step to add support for the 3DS flow is to send three new parameters in the placeOrder call done through the 1-click purchase flow. These parameters need to be provided in the PaymentDetails object in the request.

Request body example

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "Email":"example@email.com",
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210"
   },
   "PaymentDetails":{
      "Type":"PREVIOUS_ORDER",
      "Currency":"GBP",
      "CustomerIP":"159.8.170.22",
      "PaymentMethod":{
         "RecurringEnabled":false,
         "RefNo":"224497479",
         "Vendor3DSReturnURL": "http://yoursuccessurl.com",
         "Vendor3DSCancelURL": "http://yourcancelurl.com",
         "CCID": "123"
      }
   }
}

Handling 1-click purchase with orders payed with wallets

If the original order used in the 1-click purchase request was payed with any other payment method outside of credit cards (PayPal, iDeal, Alipay), then the 3DS URLs and CVV are not required and must be sent as null.

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "Email":"example@email.com",
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210"
   },
   "PaymentDetails":{
      "Type":"PREVIOUS_ORDER",
      "Currency":"GBP",
      "CustomerIP":"159.8.170.22",
      "PaymentMethod":{
         "RecurringEnabled":false,
         "RefNo":"224497479",
         "Vendor3DSReturnURL": null,
         "Vendor3DSCancelURL": null,
         "CCID": null
      }
   }
}

Step 3 - Redirect the shopper to the 3DS page

Once the place order call has been done, the order is created with the status = PENDING, and the response object contains the necessary information to finalize the 3DS process. 

For this, the shopper needs to be redirected to the URL provided in the Href property, with the parameters provided in the Params property. The parameters need to be added based on the HTTP Method provided in the Authorize3DS object. 

Response body example

 "PaymentDetails":{
      "Type":"TEST",
      "Currency":"usd",
      "PaymentMethod":{
         "Authorize3DS":{
            "Href":"http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize",
            "Method":"GET",
            "Params":{
               "avng8apitoken":"50dcb997be8b70bd"
            }
         },
         "FirstDigits":"4111",
         "LastDigits":"1111",
         "CardType":"visa",
         "RecurringEnabled":false,
         "Vendor3DSReturnURL":null,
         "Vendor3DSCancelURL":null
      },
      "CustomerIP":"159.8.170.22"
   },

For the above response, the URL where the shopper needs to be redirect would be http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd.

Based on the outcome of the 3DS flow, the shopper will be redirected to the Vendor3DSReturnURL, if the flow is completed successfully. If not, the shopper will be redirected to the Vendor3DSCancelURL.

Step 4 - Validate that the order was successful 

The final step is to validate that the order was successful during the 3DS flow. For this, you have two options:

Option 1: Listen for a webhook

2Checkout provides a series of webhooks that will be triggered once the order status is updated. Setting up a listener for the Instant Payment Notifications (IPN) will allow you to receive a webhook notification once the status of an order is changed. For more information on webhooks, visit our Webhook documentation.

Option 2: Fetch the order via API

In order to validate that the order status was update and that the order can be provisioned, you can perform an API request to get the order based on its reference.

Overview 

The Renewals and Expirations report shows info about the number of license renewals compared to the number of license expirations for the past 12 months, with a month-by-month view. 

You can access this report from your Merchant Control Panel by navigating to Dashboard -> Reports center -> Main reports -> Executive reports -> Renewals and expirations. 

Availability 

The Renewals and Expirations report is available for 2Subscribe and 2Monetize accounts. 

Renewals and Expirations Report Settings 

• Aggregate report for all accounts: if enabled, it generates the report for all your accounts, otherwise the report will be generated for the current account only. 
• Renewals reported according to their initial purchase date: if selected, it will generate the number of renewals and expirations of subscriptions grouped by their initial purchased date. 
• Renewals reported according to their expiration date (Churn rate is calculated): if selected, the report will contain the renewals and expirations grouped by the expiration date. 
• Products: by default, all products are selected. Use this filter if you wish to generate this report for one or more products. 

Report results

Renewals reported according to their initial purchase date

This report is an overview of the renewals reported according to their initial purchase date and it displays the number of subscriptions expired and renewed in the same month.

Renewals reported according to their expiration date

This will generate an overview of the renewals reported according to their expiration date. Renewed subscriptions will be attributed to the same month when they were set to expire.

FAQs

Q: Does the report count subscriptions coming from Trial conversions? 

A: Yes.

Q: Does the report count twice subscriptions coming from upgrades where the upgrade generated a new subscription? 

A: Yes.

Q: Does the report count imported subscriptions? 

A: Yes.

Q: Does the report count test subscriptions? 

A: No.

Q: Does the report count lifetime subscriptions?

A: No.

Q: Does the report count dynamic product subscriptions if no product filter is applied? 

A: Yes.

Q: Does the report count both eCommerce and channel partner subscriptions? 

A: Yes.

Q: Are subscriptions included regardless of the payment method? 

A: Yes.

Q: If the subscription billing cycle has an expiration date in November 2019 and gets renewed in December 2019, is it counted against November or December? 

A: Both. It will be counted in the “Auto Expiration” or “Manual Expiration” column in November 2019, and it will be also counted in “Auto Recurring” or “Manual Payments” in December 2019.

Overview

India is implementing a new regulatory framework rolled out by the Reserve Bank of India (RBI). The new rules have a direct impact on recurring transactions (subscriptions) and bill payments. 

In the past years, RBI worked on a system that enables multiple safety and security measures for online payments. Similar to the Strong Customer Authentication (SCA) in Europe, the new measures require consumers to give an Additional Factor of Authentication (AFA) for card-no-present (CNP) recurring transactions. 

Starting October 1st, 2021, the Reserve Bank of India (RBI) has enacted a new regulatory framework, the Directive of Processing e-mandates. The new RBI directive targets mainly e-mandates for recurring transactions, not one-time payments. The new framework mandates that the use of AFA will be mandatory for any transaction exceeding 15000 INR, which means that merchants selling subscriptions in India might see a rise in payment declines for recurring charges. 

Your subscriptions are safe with 2Checkout (now Verifone) 

The continuity of your subscriptions is safe with 2Checkout (now Verifone), but you might see a drop in renewal rates in India.  

We have reached out to our payment and bank partners from India, and they are working around the clock to make sure their systems are updated to meet the demands of RBI. 

Renewal Notifications for Manual Renewals 

Our system has built-in renewal notifications for Subscriptions and is used extensively as the main tool to notify users of upcoming or pending payments.  

You can set your custom notification schedule for sending out renewal notification emails within the boundaries of a 90-day limit around the renewal date. 

Since the new safety measures imposed by the RBI will require subscribers to manually authorize the payment, you can enable the Manual Renewal function for your customers. They will be able to authorize the payment every time they will be notified to do so.  

Use the Manual Renewal reminder documentation guide to edit email parameters. 

Create Subscription renewal links 

See how you can create subscription renewal links to enable your customers to renew their active and past-due subscriptions on-demand, bypassing the upcoming renewal operation scheduled in the 2Checkout system.  

Dunning Management for Hard Declines 

Use dunning management to reduce declined payments and recover lost revenue from failed authorizations. 2Checkout notifies customers via email about failed renewals, helping them update their payment information in myAccount. 

Dunning management for hard declines is available as part of the 2Recover add-on. To enable it on your account, contact 2Checkout. 

Request payments or Invoices  

Send payment/invoice requests by email to your customers for their subscriptions. The email sent to customers will have a link directing them to a checkout page where they can make a payment instantly. This is how you can set it up. 

For more information, you can contact us at supportplus@2checkout.com. 

Overview

Under the Payment Services Directive 2 (PSD2) initiative, in order to prevent ever-evolving fraud methods, Payment Service Providers (PSPs), such as 2Checkout, must apply extra security steps to implement Strong Customer Authentication (SCA) and further protect the confidentiality of consumers’ data. 

For more details about 3D Secure support in API, check the Payment Services Directive 2 (PSD2) article.  

You can also read the resources below to have a better understanding of what is PSD2 and what it entails: 

• What is the 2nd Payment Service Directive (PSD2)? 
• What is PSD2 and What Does Strong Customer Authentication (SCA) Mean for You? 
• The Impact of PSD2 and SCA: Ordering Flows and Exemptions 

Impact 

All merchants using the 2Checkout Public API versions 3.0, 3.1, and 4.0, on all protocols, are affected by this change.  

In order to avoid your orders being declined due to the lack of 3DS, we recommend you migrate to API version 6.  

How to migrate 

Migrating your placeOrder call to API 6.0 is as simple as updating the endpoint: 

• REST: https://api.2checkout.com/rest/ 
• SOAP: https://api.2checkout.com/soap/6.0/ 
• JSON-RPC: https://api.2checkout.com/rpc/6.0/ 

Once you’ve migrated to API 6.0, you need to provide two mandatory parameters in the paymentMethod object:  

• Vendor3DSReturnURL - the URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized. 
• Vendor3DSCancelURL - the URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized. 

Once the order has been submitted, you will find a new property in the API response - Authorize3DS. 

Based on the parameters provided in Authorize3DS, you need to build and redirect the shopper to a page where they will finalize the 3DS flow.

{ 
  "Type": "CC", 
  "Currency": "usd", 
  "PaymentMethod": { 
    "Authorize3DS": { 
      "Href": "http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize", 
      "Method": "GET", 
      "Params": { 
        "avng8apitoken": "50dcb997be8b70bd" 
      } 

    }, 

    "Vendor3DSReturnURL": "http://shopping.cart.local/checkout/external/return/cc", 
    "Vendor3DSCancelURL": "http://shopping.cart.local/checkout/external/cancel/cc", 
    "FirstDigits": "4111", 
    "LastDigits": "1111", 
    "CardType": "Visa", 
    "RecurringEnabled": false 

  }, 
  "CustomerIP": "10.11.12.1" 

The shopper needs to be redirected to: http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd 

Once the order is approved by the shopper, 2Checkout will update the order status and trigger the webhook notifications.  

You can read more information on the 3DS flow here. 

Overview

Use the getSubscriptionAdditionalInformation method to retrieve all the additional information fields belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = '351D8F557E';

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

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

Overview

Place an order with catalog products without requiring any payment information from your customers (free orders).

Requirements

The final order price has to be 0. Either use products with 0 price, or add a promotion for 100% of the total order price. It's mandatory to set RecurringEnabled to false.

Parameters

Response 

Request

<?php

require ('PATH_TO_AUTH');

$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->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1'; // product needs to have 0 price
$Order->Items[0]->Quantity = 1;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'john.doe@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;

$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'FREE';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = false;

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

$order = callRPC($jsonRpcRequest, $host);

var_dump($order);

Overview

Use the getSubscriptionAdditionalInformationField method to retrieve information related to an additional information field belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = '351D8F557E';
$fieldName = 'subscription';


$jsonRpcRequest = array (
'method' => 'getSubscriptionAdditionalInformationField',
'params' => array($sessionID, $subscriptionReference, $fieldName),
'id' => $i++,
'jsonrpc' => '2.0');

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