2Checkout API Use Cases

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.

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

Overview

Use getShippingPrice to retrieve the shipping method and price available, based on a current cart configuration. This API call returns the available shipping methods defined in your Control Panel, together with the fees you configured based on order total amount/weight/country.

Requirements

It's mandatory to have tangible products defined in your Control Panel, to retrieve shipping method and price information.

Parameters

Sample request

<?php

require ('PATH_TO_AUTH'); // authentication call

$cartItems = [];
$cartItem = new stdClass();
$cartItem->Code = 'my_product_code_1'; // product code defined in the Information tab, at product level
$cartItem->Quantity = 2; // quantity that is being purchased
$cartItems[0] = $cartItem;
$billingDetails = new stdClass();
$billingDetails->CountryCode = 'US'; // billing country
$deliveryDetails = new stdClass();
$deliveryDetails->CountryCode = 'AU'; // delivery country

$currency = 'USD'; // purchase currency

$couponCode = ['TANGIBLEPROMO']; // apply discount to promotion

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'getShippingPrice';
$jsonRpcRequest->params = array($sessionID, $cartItems, $billingDetails, $deliveryDetails, $currency);
$jsonRpcRequest->id = $i++;

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

Response

Overview

Use the addCrossSellCampaignText method to customize the texts that are shown in the shopping cart when a cross-sell campaign is displayed.  

Editing a text can be done via the updateCrossSellCampaignText method with the same payload. If during a call to updateCrossSellCampaignText method, a text is not found in the database, it will be added automatically.  

Request parameters

Response

Both the addCrossSellCampaignText and updateCrossSellCampaignText methods will return the full list of texts available in the platform. 

Request sample

<?php 

require ('PATH_TO_AUTH'); 

$csCampaignText = []; 
 
$textObj = new stdClass(); 
$textObj->Language = "ro"; 
$textObj->Title = "Numele campaniei mele"; 
$textObj->Description = "Descrierea campaniei mele"; 

$csCampaignText[] = $textObj; 

$textObj = new stdClass(); 
$textObj->Language = "en"; 
$textObj->Title = "My campaign name"; 
$textObj->Description = "My campaign description"; 

$csCampaignText[] = $textObj; 
try { 

    $csCampaignTextResponse = $client->addCrossSellCampaignText($sessionID, $csCampaignText); 

} catch (SoapFault $e) { 

    echo  $e->getMessage(); 

} 

Overview

Retrieve information and manage subscriptions for your account. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Object parameters