Overview

Disclaimer: the following method is intended for internal purposes only.

Use the getMerchantInforamtion method for retrieving vendor information required by the 2CO shopping cart into a single call.

This API method is protected through a special authentication header that the 2CO cart should sent. Click here to learn more about the X - header authentication.

Requirements

Authenticate using the special authentication header.

Response

Request

<?php

function callRPC($Request, $hostUrl, $Debug = false) {
    $curl = curl_init($hostUrl);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPPROXYTUNNEL, false);
    curl_setopt($curl, CURLOPT_PROXY, '');
    curl_setopt($curl, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Accept: application/json',
        'X-Avangate-Authentication: type="private" ver="2" app="2co-shopping-cart" merchant="RDGM" date="2018-01-31T13:57:44+00:00" hash="0m3ULy6dZ2xUI8CFtU0ersCootdf6wz8Z1qxN28FdXI="'
    ));

    curl_setopt($curl, CURLOPT_COOKIE, '');
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);

    if ($Debug) {
        var_dump($RequestString);
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        var_dump($ResponseString);
    }

    if (!empty($ResponseString)) {
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }

    return null;
}

$host = 'http://api.avangate.com/soap/5.0';


try {
    $merchantInformation= $client->getMerchantInformation($sessionID);
}
catch (SoapFault $e) {
    echo "MerchantInformation: " . $e->getMessage();
    exit;
}

var_dump("merchantInformation", $merchantInformation);

Overview

Use the Express Payments Checkout flow to minimize billing data entry for your shoppers, depending on the selected payment method, enabling you to further streamline the available single page checkout flows. This flow is particularly optimized to facilitate high volumes of payments via PayPal. 

2Checkout recommends that you test the compatibility of existing shopping cart templates with the 'Express payments checkout' flow to ensure smooth purchase experiences for customers.

Availability

The Express Payments Checkout is available for all account types on both business models (PSP & MoR). 

Requirements

Use a currency parameter in the buy-link, preferably EUR or USD when pre-selecting PayPal as the payment method for the Express payments checkout, to ensure that the ordering process uses a PayPal supported currency.

If shoppers are geo-located in a market using a currency not supported by PayPal, the 2Checkout system automatically switches the currency to Euro (EUR), but only in scenarios in which PayPal is the pre-selected method for the Express payments checkout.

Express payments checkout flow 

The Express payments checkout flow modifies the shopping cart design by positioning the payment methods selector area above the billing details section. 

PayPal

In scenarios in which you use PayPal as the pre-selected payment method for the Express payments checkout flow, the cart displays a streamlined Billing Information area. Customers are only required to select the currency for the transaction that can be either EUR or USD.

Cards and other payment methods

By default, the payment methods list features four visible items. Users can click on the Select other methods link to access an extensive list of payment methods, initially hidden. Note: These are all payment methods activated for your account.

The order in which items are listed in this area is optimized by the 2Checkout system to reflect the popularity of payment methods in specific geographies worldwide. This causes the list to vary from market to market according to the location of shoppers.

Express payments checkout links query parameters

You can build buy-links for the Express payments checkout flow manually. Use the parameters described below either with your custom domain or with https://secure.2checkout.com/order/checkout.php:

Here's an example of such a link:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&QTY=1&COUPON=4066_100&CLEAN_CART=ALL

Generate an Express payments checkout flow link

1. Navigate to Generate links under Setup.
2. Select the Express payments checkout flow option in the list of purchase flows available under the Link options area.
3. Select one or more products and configure advanced options, if needed.
4. Scroll down to the bottom of the page and click on the Generate link button.
5. The 2Checkout system builds a link such as the following:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&DESIGN_TYPE=1

FAQs:

1. Are free orders supported?

For free orders (with zero value) 2Checkout authorizes a minimum charge, for example, $1 when USD is the currency used for PayPal account validation purposes. 2Checkout subsequently returns the money to the shopper.

2. Can CARD=1 and CARD=2 parameters be used with the Express Payments Flow?

The Express payments flow supports both CARD=1 and CARD=2 parameters. 

Overview

Purchase upgrades in addition to new licenses and subscription renewals. The 2Checkout platform enables you to offer partners upgrades to:

• A different subscription/product;
• A newer version of the current subscription/product;
• A distinct licensing option of the same subscription/product.

Requirements

• It's mandatory to associate upgrades to the same price list as the original products (subscriptions/licenses), and to assign them to partners to provide access. Products that are not part of price lists assigned to partners will not be available as upgrade options.
• Upgrades are only available for active subscriptions/licenses. As long as expired licenses/subscriptions are still in their grace period (featuring the Past due status), upgrading them is a valid option.
• When defining the product which will act as the upgrade make sure to also generate a subscription under the Renewal tab. Products can only be upgraded to offerings for which a subscription was generated, when ordering on behalf of your partners. If the upgrade is not a subscription, select none as the Renewal interval. This creates a lifetime license.

Place partner upgrade orders

1. Go to Orders & customers -> Place partner order.
2. Select the partner for which you're ordering upgrades, either by typing the name in the Select partner box, or by using the drop down menu available. Alternatively, provided that you already placed orders on behalf of your partners, a list of Last used partners will be available in this area, and clicking on a name will automatically select it.
3. Select Upgrade to move to the next stage.
4. Search for subscriptions/licenses you want to upgrade. The results returned for the search include only active, upgradable subscriptions/licenses previously purchased by the selected partner. Expired or disabled subscriptions/licenses, as well as those for which you haven't defined an upgrade, will not be listed here. Upgrades need to be ordered individually, one at a time, unlike prolonging subscriptions, where you can bulk renew a number of selected items. The reason for this is the fact that each product subscription/license can have different upgrade options, requiring you to customize each item individually. However, once you add an upgrade to cart, you can continue doing so for more subscriptions/products. You'll be able to add to cart and order as many upgrades as you wish, but you have to do it one by one. The quantity/number of units of the upgrade is locked and cannot be modified, unlike additional options you configured.
5. Editing functionality for upgrade orders involves options such as adding more upgrades, remove added items one by one or all at once, and communicate with your partner through comments. You can even edit the specific details of a subscription/license already added to cart, if you would like to modify the options selected initially, for example.
6. Step 4: Add extra margin/discount options to decrease the cost of an upgrade for your partner. Extra margins and discounts are entirely optional and completely under your control.
   
   • Discount - Apply a discount to the product(s) value in this order. The discount is deducted from the total price of the products before partner margin is applied.
   • Extra margin - Offer an extra margin to your partner only for this order. The extra margin is deducted from the total price of the products after discount and partner margin are applied.
7. Place the order. Hit the Place order button to place an upgrade order once all the details are final.
8. Order confirmation. Orders placed by you on behalf of your partners are confirmed automatically, regardless of the order confirmation settings of the partner account.
9. Attach end user information. For upgrades, the 2Checkout system is designed to copy the end user information attached to the original subscription/license. However, when such data is not available, you'll need to provide it for the order to move to the delivery/fulfillment stage (if they are required according to the Partner commercial settings). 2Checkout needs at least the email address of partners/shoppers to deliver keys for orders that require end user information.
10. Attach reseller information. Reseller information is also copied automatically from the original subscription/licenses as a part of the upgrade process. Similarly, when such data is not available, you'll need to provide it for the order to move to the delivery/fulfillment stage, if the reseller information is required according to that partner's commercial settings.
11. Pay partner invoices. Partner invoices can be generated manually or automatically, depending on your partner account settings. If the order is placed without any available credit, or your partners do not enjoy a credit limit - they will first need to pay the partner invoice that gets generated automatically when the order is confirmed, and only then will the process advance to the delivery/fulfillment stage. To manually issue a partner invoice, go to Partner invoices under Orders & customers.
12. Click the item in the list of available orders on the left hand side of the page to add them to the partner invoice you're generating, and click Preview.
13. Click Save to create the partner partner invoice. On the next screen you'll have the option to notify your partner of the newly generated partner invoice or to cancel it if necessary.
14. Delivery/fulfillment: When delivery/fulfillment is handled by 2Checkout, not required or has been confirmed by you, the system will give green light to deliveries immediately for order that are paid in full or placed within available credit. Fulfillment for partner orders guidance is available here.

Error messages

Use the variables in the list below to customize the Electronic delivery and payment receipt shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.

Overview

Perform easy account management via API Requests. The 2Checkout API portfolio contains extended capabilities that can help you automate processes as creating products or promotions, placing orders (both with catalog and dynamic product information), issuing refunds, retrieving the shipping price for an order, handling subscriptions, and many others.

Overview

Use deletePromotionProducts to remove products from an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'MY_PROMO_CODE_1';

// Define the first product to remove from the promotion
$newProduct1 = new stdClass;
$newProduct1->Code = '';
$newProduct1->PricingConfigurationCode = '';
$newProduct1->PricingOptionCodes = ['',''];

// Define another product to remove from the promotion
$newProduct2 = new stdClass;
$newProduct2->Code = '';
$newProduct2->PricingOptionCodes = [''];

$productPromotion = [$newProduct1, $newProduct2];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'deletePromotionProducts',
'params' => array($sessionID, $promotionCode, $productPromotion)
);
var_dump (callRPC($jsonRpcRequest, $host));

Overview

Use the createUpSellCampaign method to create an upsell campaign via JSON-RPC API 6.0.

Request parameters

Response parameters

Request sample

<?php
require ('PATH_TO_AUTH');

$upsell = new \stdClass();

$upsell->Name = 'December 2020 upsell campaign’;
$upsell->StartDate = '2020-12-21';
$upsell->EndDate = '2020-12-25';
$upsell->DisplayForManualRenewals = false;

// setup percent discount
$discountPercent = new \stdClass();
$discountPercent->Type = 'PERCENT';
$discountPercent->Value = 5;

// setup fixed discount
$discountFixed = new \stdClass();
$discountFixed->Type = 'FIXED';
$discountValues = [
    'USD' => 10,
    'EUR' => 8,
    'TRY' => 80,
    'RUB' => 1100,
];
$dv = [];
foreach ($discountValues as $curr => $amt) {
    $disc = new \stdClass();
    $disc->Currency = $curr;
    $disc->Amount = $amt;

    $dv[] = $disc;
}
$discountFixed->Values = $dv;

// assign discount
$upsell->Discount = $discountPercent;
# OR
# $upsell->Discount = $discountFixed;


// setup primary product
$primaryProduct = new \stdClass();
$primaryProduct->Code = $productCode;
$primaryProduct->Quantity = 1;
$ppPriceOptionGroup1 = new \stdClass();
$ppPriceOptionGroup1->Code = 'OPTGRP2';
$ppPriceOptionGroup1Option = new \stdClass();
$ppPriceOptionGroup1Option->Code = 'OptGrp2Code2';
$ppPriceOptionGroup1->Options = [$ppPriceOptionGroup1Option];

$ppPriceOptionGroup2 = new \stdClass();
$ppPriceOptionGroup2->Code = 'interval_scale_grp1';
$ppPriceOptionGroup2Option = new \stdClass();
$ppPriceOptionGroup2Option->Code = 'interval_scale_grp1-1-10';
$ppPriceOptionGroup2Option->Value = '6';
$ppPriceOptionGroup2->Options = [$ppPriceOptionGroup2Option];

$primaryProduct->PriceOptions = [$ppPriceOptionGroup1, $ppPriceOptionGroup2];
$upsell->PrimaryProduct = $primaryProduct;

// setup recommended product
$recommProduct = new \stdClass();
$recommProduct->Code = $recProductCode;
$recommProduct->Quantity = 0; // stands for “match quantity” 
$rpPriceOptionGroup1 = new \stdClass();
$rpPriceOptionGroup1->Code = 'CHECKB_LIST';
$rpPriceOptionGroup1Option1 = new \stdClass();
$rpPriceOptionGroup1Option1->Code = 'chk1';
$rpPriceOptionGroup1Option2 = new \stdClass();
$rpPriceOptionGroup1Option2->Code = 'chk3';
$rpPriceOptionGroup1->Options = [$rpPriceOptionGroup1Option1, $rpPriceOptionGroup1Option2];
$recommProduct->PriceOptions = [$rpPriceOptionGroup1];
$upsell->RecommendedProduct = $recommProduct;

$upsell->Enabled = true;

// setup languagte descriptions / texts
$enDescription = new \stdClass();
$enDescription->Language = 'EN';
$enDescription->Text = 'Buy <!--{RECOMMENDED_PRODUCT_NAME}--> for just <!--{RECOMMENDED_PRODUCT_PRICE}--> until Dec 25th';
$upsell->Description = [$enDescription];

$jsonRpcRequest = new \stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'createUpsellCampaign';
$jsonRpcRequest->params = [$sessionID, $upsell];
$jsonRpcRequest->id = $i++;

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

Overview

You can generate links for dynamic products outside the Merchant Control Panel, using the ConvertPlus parameters explained in this article. Some of the ConvertPlus buy-link parameters require a signature, to prevent any interference in the ordering process. Optional parameters also require a signature if they are included in the generated buy-link.

ConvertPlus parameters that require a signature

ConvertPlus parameters to be included in the signature - general rules

1. General parameters included in the signature, regardless of the type of checkout (catalog products, dynamic products, renewal, unfinished payment): return-url, return-type, expiration, order-ext-ref, customer-ref, customer-ext-ref.
2. Parameters to be included in the signature for dynamic products buy-links: currency, prod, price, qty, type, opt, description, recurrence, duration, renewal-price,  item-ext-ref.
3. Parameters to be included in the signature for manual renewal buy-links: prod, qty, opt.
4. Parameters to be included for on-the-fly pricing for catalog products: prod, price, qty, opt, coupon.
5. The parameter to be included in order to lock the cart for catalog products: lock.
6. Parameters to be included when an approved URL is set: in this case, all parameters will be included in the signature, when redirected after successful completion of a sale.

Build the ConvertPlus signature

To sign a ConvertPlus buy-link, you need to follow these steps:

1. Sort the parameters that require a signature alphabetically.
2. Serialize the parameters and append to them the length of their values.
3. Concatenate the resulting values.
4. The serialized value is then encrypted with your Buy Link Secret Word using the HMAC method (algorithm sha256).
5. The resulting value is added to the buy link under the signature parameter

Example

Let's consider the following parameters:

•     merchant = 'MCODE'
•     dynamic = '1'
•     prod = 'Software'
•     price = 10
•     currency = 'USD'
•     qty = 1
•     type = 'digital'
•     expiration = 1893456000

The regular buy-link will have the following structure:

https://www.2checkout.com/checkout/buy?merchant=2COLRNC&dynamic=1&prod=Software&price=10currency=USD&qty=1&type=digital&expiration=1893456000 

This link is missing one last parameter, a signature.

Let's take a look at the list of parameters that require a signature:

•     merchant = '2COLRNC'
•     dynamic = '1'
•     prod = 'Software' <-- SIGNATURE REQUIRED
•     price = 10        <-- SIGNATURE REQUIRED
•     currency = 'USD'        <-- SIGNATURE REQUIRED
•     qty = 1             <-- SIGNATURE REQUIRED
•     type = 'digital'         <-- SIGNATURE REQUIRED
•     expiration = '1893456000' <-- SIGNATURE REQUIRED

We extract only those parameters:

•     prod = 'Software'
•     price = 10
•     currency = 'USD'
•     qty = 1
•     type = 'digital'
•     expiration = 1893456000

Sort the parameters alphabetically

•     currency = 'USD'
•     expiration = 1893456000
•     price = 10
•     prod = 'Software'
•     qty = 1
•     type = 'digital'

Serialize the values

To serialize a value, you need to prepend to it the number of letters or digits a value has. For example, the currency parameter has the 'USD' value that will be serialized as '3USD', where 3 is the number of letters that make up the value. The value of the price parameter is '10', so the serialized value will be '210', where 2 is the number of digits that make up the value.

In case a value uses special characters, to serialize it, you need to prepend to it the number of bytes in the string, also known as the UTF-8 string length. To count the bytes in the string, you can use an online bytes counter. For example, if the prod parameter has the 'ελληνικά' value, this will be serialized as '16ελληνικά' and not as '8ελληνικά', due to the use of special characters, where '16' is the number of bytes in the string.

•     currency = '3USD'
•     expiration = 101893456000  
•     price = 210
•     prod = '8Software'
•     qty = 11
•     type = '7digital'

Concatenate the values

    '3USD1018934560002108Software117digital'

Encrypt using your Secret Word

The serialized value is then encrypted using the HMAC method.

    - the algorithm used is sha256

    - the key used when encrypting is the merchant secret word (in this example, the secret word is 'secret_wordbuylink')

This outputs a 64 character string:

c2225743f22e3b698b2f31052e35ec7602b787c804eaac1e0cd127a9a06b5762

Add the string in the buy-link

https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&dynamic=1&prod=Software&price=10&currency=USD&qty=1&type=digital&expiration=1893456000&signature=c2225743f22e3b698b2f31052e35ec7602b787c804eaac1e0cd127a9a06b5762

Overview

Use the setSubscriptionGracePeriod method to set a custom grace period for an Active or Past Due subscription. This method changes per-subscription end user data and not customer details.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$gracePeriod = YOUR_GRACE_PERIOD;

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

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

Overview

Use the getAdditionalOrderFields method to extract information about additional fields you set up for your account.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

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

?>

Response