Overview

Assign API roles to your users, for allowing them to perform a task that requires access to the 2Checkout API.

Creating API roles

1. Login to the 2Checkout Control Panel using your master account.
2. Go to Account settings.
3. Click Manage user access.
4. Go to the View roles tab.
5. Click Add new role.
6. Fill in a role name and description.
7. Select the API access privileges.
8. Click Save role.

Assign the role to the users you want to provide with access to 2Checkout API.

If a merchant on the PSP business model (2Sell & 2Subscribe) has multiple 2Checkout accounts, which means they have multiple unique domains processing with 2Checkout, then they must have set up a unique API user per account.

Overview

Use the addProductGroup method to create product groups for your account:

• Send null for product group Code. 2Checkout ignores any values you send for Code and generates identifiers itself. 
• Use unique product group names. 
• 2Checkout throws an exception if you send a blank product group.
• If you send only the name of the product group 2Checkout creates the new product group entity. 

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = null;//Send null for the Code. 2Checkout generates unique product group code identifiers.
$ProductGroup->TemplateName = 'Default Template';//'001 - Two Column Billing'; //the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = true;

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

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

?>

Overview

The object below is returned directly or within a successful response from the following API requests:

Create promotion                          Update promotion                            Retrieve a promotion                            Search promotions

Promotion object

Overview

Learn how to leverage the 2Checkout API to build your integration with the 2Checkout system, which will enable you to place and manage orders, manage subscriptions and customers, create, update and extract product catalog and pricing information for your account.

Availability

2Checkout API is available for all accounts.

Protocols and versioning

The 2Checkout API is accessible under three protocols across a number of major and minor versions. 

The URL for each API protocol and version is composed by following this rule:

https://api.2checkout.com/{protocol}/{version}

 The 2Checkout API is accessible under three protocols:

• REST - under https://api.2checkout.com/rest/
• SOAP -  under https://api.2checkout.com/soap/
• JSON-RPC (standard RPC protocol with the payload being JSON encoded) - under https://api.2checkout.com/rpc/

In order to maintain backward compatibility, any changes or new features that would break existing integrations are published under a new API version. You can use multiple versions of the API in parallel, allowing for easier integration of new functionalities, but we do not recommend this practice.   

Accessing a certain version of the 2Checkout API is easy, as the API version is used in the API URL: https://api.2checkout.com/{protocol}/{version}.

The API is versioned with both major and minor versions. The current latest version of the 2Checkout API is API version 6.0 (publicly launched in December 2019). 

Pagination in API

All main resources used in the 2Checkout API support searching and pagination. 

This is achieved by using two standard parameters: page and limit. Both parameters are integers, optional, and can be passed as NULL. 

"Pagination": {
    "Page": 1,
    "Limit": 10,
   }

The page and limit parameters can be sent directly in the payload of the request, or, in some cases, under a Pagination object. 

Typically, the response for a search call will return a list of items, as well as the provided pagination options. Additionally, a total count of items is provided in order to facilitate navigation.

 "Pagination": {
    "Page": 1,
    "Limit": 10,
    "Count": 230
  }

Attributes

Overview

Use the assignProductGroup method to assign a product to a product group. Following the assignation, the 2Checkout system uses the shopping cart template associated with the product group as the default cart design when shoppers purchase a subscription plan/product.

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$productCode = "YOUR_PRODUCT_CODE";
$groupCode = "YOUR_PRODUCT_GROUP_CODE";

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'assignProductGroup',
'params' => array($sessionID, $productCode,$groupCode)
);

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

?>

Overview

Use the updateProductGroup method to create a new product group for your account.

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = 'DBA13A4268';
$ProductGroup->TemplateName = 'Default Template'; // the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = false;

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

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

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.
• For orders paid with PayPal, the original order must have automatic renewal enabled so that it can be reused for future 1-click purchases.

Parameters

Response

Validate previous order reference

<?php
require('PATH_TO_AUTH');
$orderReference = '670174996';
$jsonRpcRequest = array (
'method' => 'isValidOrderReference',
'params' => array($sessionID, $orderReference),
'id' => $i++,
'jsonrpc' => '2.0'
);
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
$jsonRpcRequest = array (
'method' => 'getOrder',
'params' => array($sessionID, $orderReference),
'id' => $i++,
'jsonrpc' => '2.0'
);

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;
$jsonRpcRequest = array (
'method' => 'placeOrder',
'params' => array($sessionID, $Order),
'id' => $i++,
'jsonrpc' => '2.0'
);
var_dump (callRPC((Object)$jsonRpcRequest, $host, true)); 

Overview

Get the price for a product in a new purchase scenario, based on the product ID, the pricing list it's assigned to and specific pricing options.

Requirements

Parameters

Response

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner

$productId = 'YOUR_PRODUCT_ID';
$pricingListCode = 'YOUR_PRICING_LIST_CODE';
$priceOptions = array(
'Pricing_options_group_code1',
'Pricing_options_group_code2'
);

try {
    $ProdPrice= $client->getProductPrice($sessionID, $productId, $pricingListCode, $priceOptions);
} catch (SoapFault $e) {
    echo "ProductUnitPrice: " . $e->getMessage();
    exit;
}

Errors

Overview

Use searchShippingMethods to retrieve information on the shipping methods currently defined on your account.

Search filters

Use the parameters below to filter the results of your search for shipping methods.

Sample request

<?php

require ('PATH_TO_AUTH'); // authentication call

$SearchOptions = new \stdClass();
$SearchOptions->Name = 'ShippingMethodName'; // search for a specific shipping method
$SearchOptions->Codes = ['Code1', 'Code2', 'Code3']; // array of shipping method codes
$SearchOptions->Countries = ['US', 'UK', 'AU']; // array of country codes
$SearchOptions->Active = true; // only active shipping methods
$SearchOptions->Pagination = new \stdClass();
$SearchOptions->Pagination->Page = 1; // set display pages
$SearchOptions->Pagination->Limit = 200; // limit the results

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

Response