REST 3.0 Reference

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