Overview

License Change Notification (LCN) works as a message service generating automatic subscription notifications for your 2Checkout account. Use the notifications to process subscription data into your own management systems by synchronizing it with 2Checkout account events. 2Checkout generates notifications for subscription update and expiration events (including past-due notifications).

How can I use LCN?

Use LCN to automate back-end functions for your services, including but not limited to:

• Creating end-user accounts
• Providing access to acquired services
• Manage subscriptions
• Fulfilling purchases
• Engaging subscribers
• Converting trials to paid subscriptions
• Cutting access to a delinquent account

Webhook asynchronicity

2Checkout’s webhooks (IPN and LCN) operate asynchronously. 

How does LCN work?

1. Create one or multiple LCN listener pages on your website. 2Checkout sends LCNs to publicly accessible servers.
2. Configure the LCN settings of your 2Checkout account to point to the URLs of your default/preferred listener pages. Our system performs a GET request against the URL you fill in and expects an HTTP 200 code as a response. Make sure that your URL can be queried via a GET request from our webserver  IPs.
3. Set up multiple URLs if you require more listener pages, such as in testing scenarios in which you don’t want to use your default LCN listener. 
4. 2Checkout sends subscription notifications to the endpoints you defined when subscribers change specific subscription details, using secure (HTTPS) POST.
5. 2Checkout uses an HMAC_SHA signature to validate the HTTPS POST. Calculate the signature using data sent and your 2Checkout account’s secret key, following the instructions included in this article.
6. Your custom LCN listener scripts consume the notifications and process the info received.
7. Configure your LCN listener to output a read receipt confirmation on the listener page after receiving a valid LCN message. This article includes guidance on how to generate the confirmation.
8. In the absence of a confirmation from one of your LCN listeners, 2Checkout continues to send notifications to that endpoint, according to the failure retry process, until you provide a valid response.
9. The 2Checkout system regularly checks the status of subscriptions to identify expired items and modifications. 2Checkout then sends notifications for expirations as well as for updates that occurred in the last 24 hours prior to the moment when it performs the check. 2Checkout does not re-send notifications for the same event unless the status of the subscription changes or it identifies additional modifications.

Set up the default LCN URL

1. Log into your 2Checkout account.
2. Navigate to Dashboard → Integrations → Webhooks and API.
3. Click on the LCN Settings tab.
4. Click on the Edit button to edit an existing URL corresponding to your default LCN listener or click on the Add LCN URL button to add a URL corresponding to your default LCN listener in the LCN URL field.
5. Save your settings by clicking on the Update button at the bottom of the page.
6. 2Checkout checks the validity of the URLs in terms of access to ensure that notifications reach your LCN listener without any issues.

Set up multiple LCN URLs

You can set up multiple endpoints for your LCN notifications, for scenarios in which you have multiple Internal Systems that require receiving this information. You can set up eight (8) URLs for your notifications.

Navigate to LCN settings under Integrations → Webhooks and API, in your Merchant Control Panel Dashboard. Select the LCN settings tab and click on the Add LCN URL button to create an additional URL configuration for your notifications.

To find out more about the NOTIFICATION_URL functionality, read more here.

Debug LCN

To view or debug LCN notifications during the integration phase, place TEST orders.

Alternatively, search for specific subscriptions in the Subscriptions area. On the subscription details page, you have the option to resend notifications. You can also see how many LCN notifications have been sent so far for a subscription. Opt to reissue the LCN for debugging and 2Checkout re-generates and re-sends the LCN, but also displays a copy of the content sent in the control panel.

Secure your LCN script 

For security reasons, 2Checkout recommends that you restrict access to the LCN script. 

Overview

Multi-product promotions allow you to offer percentage-based discounts to your shoppers, based on the number of unique products added to the shopping cart. They apply automatically as long as the order includes the products assigned to the promotion.

How to configure a multi-product promotion

1. Enter a promotion title and description. Promotion names are visible to your shoppers if the order meets the promotion criteria.
   
   • Add localized promotion names for any of the supported languages. The 2Checkout shopping cart automatically displays localized promotion names based on the selected shopping cart language.
2. Define the time interval when you want the promotion to be active. To start a promotion as soon as you activate it, leave the start date empty. If you don't set an end date, the promotion will stop when the maximum number of orders has been reached or will continue to run if the maximum number of orders is set to unlimited.
3. You can restrict promotions to a specific number of orders, or set them to run indefinitely
4. Define a minimum order value threshold. Choose whether to apply the promotion to any order or only to orders exceeding a certain value (including taxes). To set a threshold, choose Custom, define the threshold and select the default currency. Orders using currencies without a threshold are automatically converted to the default threshold currency, using exchange rates applicable at the moment of purchase. 
5. Select whether or not to activate the promotion as soon as you save it.
6. Configure the discount depending on the number of unique products added to the shopping cart. Click Add rule, enter a number of unique products to be detected in the cart and set the corresponding discount. You can add multiple scenarios for different numbers of unique products. If you define multiple promotions or scenarios, 2Checkout automatically applies the one with the highest discount, provided that the order meets the promotion criteria.
7. Assign products to the promotion. Multi-products promotions only apply to products in the shopping cart that are not subject to another regular promotion or cross-selling discount at the time of purchase!
8. Save the promotion when you're done configuring it.

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 Growth, Standard, 2Sell, 2Subscribe, 2Monetize and Enterprise packages are not affected.

If your integration is using https://2checkout.com/checkout/api/1/ endpoint to trigger payments, then you need to follow the transition process below.

3D Secure (3DS) support added to our Payment API

For card-based payments, this resulted in the implementation of 3D Secure version 2 (3DS2 aka EMV 3DS). 3D Secure has been employed to secure online card transactions since 2001, but now a new version has been developed to meet the PSD2 SCA requirements. Basically, to be able to accept payments from the world’s largest card networks (Visa, Mastercard, Amex,etc.), any merchant will need to have implemented 3D Secure version 2 for their online store. Initially, this will apply mainly to EU-based merchants and their clients. Outside the EU, the current implementation pace of EMV 3DS is considered slow and less dominant.

The new flow for 3DS transactions in the Payment API is asynchronous and requires that you redirect the buyer to an authentication URL that will be returned in the authorization response, and wait for the buyer and sale parameters to be returned to a callback URL on your server.

What happens if I do not update my integration

If no change is done to your API integration, the Payment API will continue to work as normal, but you will start to notice a higher rate of declines as the processors will not be able to continue the transaction if the shopper’s card requires 3DS authentication.

Set up Callback URL

To enable 3DS support in your integration, you need to set up an endpoint on your server where the 2Checkout system will return the shopper and order parameters when the order is completed. The return will be a GET request and will include all standard 2Checkout Return Process parameters: total, order_number, invoice_id, merchant_order_id, and key parameter, which will contain the MD5 hash to validate the passback. 

MD5 Hash Validation

The MD5 hash is calculated as: UPPERCASE(MD5_ENCRYPTED(INS secret word + seller id + order_number + total)).

The INS secret word can be found in your Merchant Control Panel, under Integrations → Webhooks and APIs → Secret word section. The seller id is your numerical merchant code/seller ID. The order_number is the order number for the sale returned on the passback. The total is the numerical value for the total amount of the sale. Each of our community-supported libraries provides a binding to validate the hash.

Pass Callback URL in the authorization request

To let the 2Checkout system know that you are ready to handle the new 3DS flow, a new parameter needs to be added - returnUrl - in the root of the JSON payload on your authorization (create sale) API call. The returnUrl value needs to be the absolute path of your callback URL.

Authorization Request Sample

{
    "sellerId": "your-seller-id",
    "privateKey": "your-private-key",
    "merchantOrderId": "example-custom-id-123",
    "token": "client-side-token",
    "currency": "USD",
    "total": "1.11",
    "billingAddr": {
        "name": "Testing Tester",
        "addrLine1": "123 Test St",
        "city": "Columbus",
        "state": "Ohio",
        "zipCode": "43123",
        "country": "USA",
        "email": "example@2co.com",
        "phoneNumber": "5555555555"
        },
    "returnUrl": "https://www.your-site.com/return.php"
}

If the card needs 3D Secure authentication for the payment, then the API will return an HTTP status '400'. In the body of the response, under the exception object, the errorCode value will be ‘700’ and the errorMsg value will contain the URL where the customer needs to be redirected for the authentication of the payment.

API Response Sample

{
    "validationErrors": null,
    "exception": {
        "errorMsg": "https://api.2checkout.com/5.0/scripts
/credit_card/authorize?avng8apitoken=77fdf3f03b265840",
        "httpStatus": "400",
        "exception": false,
        "errorCode": "700"
    },
    "response": null
}

Once the shopper completes the 3DS authentication process, they will be redirected to your callback URL along with the order parameters. If the 3DS authentication fails, they will be returned to the 2Checkout cart so that they can verify their payment method and re-attempt the payment.

Overview

2Checkout supports multiple partial refunds for the same order. This feature enables you to partially reimburse order costs on multiple occasions to deal with more than one refund incident/dispute.

Scenarios

• Pay back the money for a single product in a multi-offering order, and then refund the costs of another product, if the customer requests it;
• Refund part of the value of an order such as in scenarios in which you charge customers for usage, and add a subsequent partial refund if needed;
• Refund the total value of an order using several partial refunds until the entire costs are reimbursed.

Requirements

Multiple refunds work only for orders paid with one of the following methods:

• VISA
• MasterCard
• Discover
• AMEX
• PayPal

Please contact 2Checkout directly if this feature is not available for your account.

Availability

1. You can place a second partial refund only if there are no existing unprocessed refunds (pending). As long as all previous partial refunds for an order were processed, you can place a new request to reimburse a partial amount of the costs paid by the customer.
2. The value of the partial refund you request needs to be equal or smaller than the amount of money paid by the customer, subtracting any costs already reimbursed. For example: for a $100 order for which you already reimbursed $40, the value of the second partial refund request cannot exceed $60.

Partial refunds

In addition to Total refunds (which return 100% of the transaction amount to the buyer) you can also issue Partial refunds, namely reimburse only part of the transaction amount paid for Completed/Finished orders, with the system automatically calculating the taxes for the repayment. This feature gives you full flexibility to control in detail the reimbursement parameters for an order. The new Partial refund functionality is an upgrade to the old Advanced refund option, which required you to specify all the details of a partial reimbursement in the comments section.

To initiate a Partial refund, follow the steps below.

1. Go to Orders & customers -> Order search.
2. Select the eStore orders tab.
3. Search for the order you want to reimburse (the status must be Completed/Finished).
4. Click the item's reference number.
5. Click Request refund.
6. Choose to return only a part of the transaction costs by selecting the Partial refund option.

Use the feature to provide refunds for a limited quantity of products or only for specific items in an order in scenarios involving orders containing multiple units/products. The repayment amount per unit (including taxes) supports values from the bare minimum, which cannot be 0 or a negative number, to the maximum, which cannot be larger than the price paid for the product/number of products being refunded.

You can repay part of the money your customers spent on product subscriptions and taxes (calculated automatically by the system), and DIS (Download Insurance Service) costs. Use the comments section to detail special refund requests.

Note: Make sure to configure all the details of the partial reimbursement, including the products and the number of units involved, but also the amount to be refunded, whether or not to re-use keycodes / cancel subscriptions (disable licenses), and enter the Cancellation reason or any other comments for the cancellation before clicking the Request refund button. Prior to the introduction of Partial refunds, your customer support representatives could only disable all subscriptions/licenses for a refunded order or none at all.

Please note that the amount you set for the refund will be the final sum sent back to the customer, including taxes.

Multiple partial refunds

To refund an order follow these steps:

1. Go to Orders & customers -> Order Search
2. Search for the order you want to refund. Note: The order needs to be Finished for a refund to be processed.
3. Click the reference number to access the Order details page.
4. Click Request refund.
5. Select Partial refund and provide the parameters for the reimbursement including the costs which will be returned to the customer.
6. Wait for the refund to be approved and the money to be reimbursed.
7. After the refund request is processed, repeat steps 1 through 5 to request an additional reimbursement.

Instant Payment Notification (IPN) for refunds

Instant Payment Notifications are generated and sent for the first partial refund as well as for subsequent refunds processed by the 2Checkout system.

Make sure to update your system to handle multiple IPN notifications in scenarios involving multiple refunds.

Notifications sent by 2Checkout will show REFUND as the order status and the amount of money reimbursed (as a negative number).

Multiple partial refunds through Instant Refund Notification IRN

You can place multiple partial refunds through Instant Refund Notification (IRN). It's mandatory that you specify the value that will be reimbursed using the AMOUNT for partial refunds. Note: In the case of IRN refunds, the value for AMOUNT must match that of the unit price multiplied with the quantity refunded.

For example, if a customer purchased 10 units of Subscription A which cost $99 each, and wants a refund for 2 subscriptions, you to match the value refunded ($198) with the unit price of Subscription A multiplied by the quantity for which you're reimbursing the customer.

Total refunds

Total refunds are available only for orders that haven't passed through the refund process previously.

Total refund limitations:

• Only a single total refund can be approved per order. A second total refund means that 2Checkout would repay the customer twice the sum of money paid for the order, which is impossible.
• If a partial refund was already approved, and the money returned to the customer, a subsequent total refund is no longer possible, considering that the value of the order and implicitly of the total refund would exceed the money paid by the customer initially, from which at least a partial refund was already subtracted.

Overview

Use the addPromotionCoupon method to add single or multiple coupons to a promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';

// Define single coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'SINGLE';
$promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'MULTIPLE';
$promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

try {
    $updatedPromotion = $client->addPromotionCoupon ($sessionID, $promotionCode, $promotionCoupon);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

Use the Proposal object via SOAP API 6.0 to store cart information at a point in time that allows you afterward to operate fast changes to the cart configuration so that you can offer custom deals to your shoppers. By using the Proposal object you can create, update, and search proposals via the 2Checkout API and control the following proposal attributes:

• Proposal content
• Price options
• Proposal links
• Billing details

Parameters 

Use the parameters below to add new custom deals for your shoppers via SOAP API 6.0.

PROPOSAL OBJECT

ProposalContent Object

LineItem Object

BillingCycle Object

PriceOptions - Array of priceOption objects

AdditionalFields - Array of additionalField Object

BillTo Object

tac Object

SentBy Object

Links Object

SellTo Object

ERRORS

Overview

Voluntary churn happens when a customer decides to end the relationship and stops using your product or downgrades from a paid version. Preventing voluntary churn requires the right combination of product engagement, customer experience, and perceived value. If customers don’t use your product often, don’t have a good experience when they do, or don’t see value in your product, they won’t stick with you. This holds true whether you’re talking about free trial users considering a paid upgrade or paying customers deciding whether to renew.

Voluntary Churn Prevention Tools 

Reduce voluntary churn and revenue spillage and uplift your revenues by up to 10% by using 2Checkout's Voluntary Churn Prevention tools. 

• Offer discounts during the churning process to entice price-sensitive subscribers to stay. Activate a churn prevention campaign, and make discounts attractive enough to make a difference.  

• Offer subscribers the option to pause their subscriptions instead and then have these automatically resume at a specific date without reacquisition costs, using the pauseSubscription API.  

• Extend the subscription duration and ask subscribers to re-enable automatic renewal right after they cancel it, to minimize the chances of them churning.  

• Allow subscribers to downgrade to plans not as rich in functionality but which are also cheaper using custom downgrade links.  

COVID-19 Resources for 2Checkout Merchants

2Checkout always strives to help merchants and their businesses thrive and in the current context of the COVID-19 pandemic, we've put up a collection of resources that can help you maintain a steady profit and not lose customers during this challenging period. 

2Checkout's retention tools introduce a smart and easy way to reduce customer churn and gain useful insights into what drives customers to cancel automatic renewals. Use 2Checkout's out-of-the-box retention capabilities to:

• Leverage proactive subscription enrollment to increase renewals and generate additional revenue. Use special deals to deepen loyalty and incentivize your customers to enroll in automatic subscription renewals.
• Decrease churn and prevent recurring revenue from "leaking" by converting cancelations into continued subscriptions. Offer the right incentives to the customers that decided to cancel their subscriptions and make them change their minds at the point of exit.
• Turn threats into opportunities by capturing your customers' feedback at the point of cancelation.

Overview

WeChat Pay is an online payment method that allows shoppers in China and Hong Kong to send payments through the WeChat social media mobile application. Every WeChat user has their own WeChat Payment account, in which they can acquire balance by linking their WeChat account to their debit card. With an increasing market share in China and Southeast Asia, WeChat Pay offers customers an easy-to-use and reliable payment method.

Related links

Availability

Available on 2Monetize accounts.

Requirements

Shoppers must have the WeChat application installed on their Android or iOS devices.

Supported currencies

• CNY
• USD
• HKD

Benefits

WeChat Pay enhances the checkout experience through multiple optimizations:

• Convenient, easy and safe. Simplified purchase flow designed for mobile payments and safe storage for cards used within the wallet.
• Increased market share. Used by hundreds of millions of users every day, WeChat Pay is one of the most popular payment methods in China.
• Higher conversion rates. Convert more Chinese visitors into buyers.

Activation steps

Go to Payment methods and enable WeChat Pay.

Purchase flow

1. Shoppers select China or Hong Kong in the shopping cart.
2. They place the order.
3. 2Checkout redirects shoppers to WeChat.
4. WeChat displays the QR code that shoppers need to scan.
5. Shoppers use their WeChat application to scan the QR code.
6. 2Checkout marks the order as Pending until shoppers place the order.
7. Shoppers place the order and the WeChat application confirms the payment.
8. 2Checkout marks the order as complete as soon as WeChat sends back an Instant Payment Notification.
9. Shoppers receive the Payment receipt and Electronic delivery emails from 2Checkout.

Note: You can configure unfinished payment follow-up emails from the Control Panel.

Type of charges

WeChat Pay does not support recurring transactions, so subscription renewals can only be done manually.

Refunds

WeChat supports order refunds.

Overview

Use the attached blueprints to integrate with the 2Checkout API via REST 3.0. 

Authentication

To authenticate to the 2Checkout REST API include a header with the following structure into your requests:

X-Avangate-Authentication: code="{VENDOR_CODE}" date="{REQUEST_DATE_TIME}" hash="{HASH}"

Alternatively, use:

X-Avangate-Authentication: code='{VENDOR_CODE}' date='{REQUEST_DATE_TIME}' hash='{HASH}'

• VENDOR_CODE: Your unique Avangate supplied merchant code.
• REQUEST_DATE_TIME: The UTC date-time of the request. Format: YYYY-MM-DD HH:MM:SS.
• HASH: The hash mac digest with an md5 hashing algorithm of the following: LEN(VENDOR_CODE) + VENDOR_CODE + LEN(REQUEST_DATE_TIME) + REQUEST_DATE_TIME. Use the secret key associated with your account for the hashing.

You must authenticate for all requests.

JSON encoded requests

The 2Checkout REST API supports only JSON encoded requests and responses. You need to include the following headers in your requests:

• Content-Type: application/json
• Accept: application/json

Responses follow HTTP specifications regarding response headers. Successful responses are composed of:

• An HTTP Success header.
• A JSON encoded string.

Resources

Please visit https://github.com/avangate.

Working code samples for REST are available for each documented scenario and method. To access code samples, select any scenario and click on the "Working example" link. You can use:

• cURL
• Java
• JavaScript
• Node.js
• Perl
• Python
• PHP
• Ruby
• Go
• C#
• Visual Basic
• Groovy
• Objective-C
• Swift

Best practices

One-click (1 click) subscription renewal

2Checkout supports 1-click manual subscription renewals for returning customers who paid for their previous orders with Credit/Debit cards.

In this scenario, you can facilitate subscription renewals for subscribers who opted out of auto-renewal (recurring billing).

How does this work?

• Identify returning customers.
• Generate the manual renewal link.
• Create a tokenized manual subscription renewal link and serve it to the returning customer.
• Customers using the link land a hosted shopping cart choose one of the credit cards they previously used for purchases from your account/store and place the order.

Availability

Contact 2Checkout to start using one-click (1-click) subscription renewals.

Requirements

1. Make sure that the subscription is eligible:

   • Status needs to be Active or Past Due
   • Subscription cannot be evergreen​

2. The email address must match that from the initial order. If shoppers change the email they need to re-enter the payment details.

   • Identify returning customers.
   • Generate the manual renewal link.
   • Create a tokenized manual subscription renewal link and serve it to the returning customer.
   • Customers using the link land a hosted shopping cart choose one of the credit cards they previously used for purchases from your account/store and place the order.

Detailed 1-click subscription renewal flow

1. Identify returning customers

   You particularly need either the 2Checkout customer reference or the external customer reference you control.

2. Use customer information

   If customers log into your system and you’ve mapped unique identifiers into the 2Checkout platform you can easily extract their subscription information.

3. Use subscription information

   You can also use subscription information to extract customer references, based on a set of filters. Validate the status of the subscription (needs to be Active or Past Due).

   • Customer email
   • Delivered codes/activation keys
   • Avangate customer reference
   • External customer reference
   • Subscription status
   • Recurring billing status
   • Product code
   • Customer country
   • Purchased date
   • Expiration/Renewal deadline
   • Subscription type

4. Create the manual renewal link

   Retrieve information regarding subscription renewals based on 2Checkout Subscription References:

   • Information on the automatic renewal (recurring billing) status (enabled or disabled).
   • The link that customers access to renew the subscription through a manual payment.

5. Attach the payment token to the manual renewal link

   2Checkout 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 2Checkout system.

REST API 3.0 Blueprints for Download