Overview

Use the searchOrders method via SOAP API 6.0 to retrieve multiple orders depending on the filter parameters. 

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$orderSearchOptions = new stdClass();
$orderSearchOptions->StartDate = “2020-01-23”;
$orderSearchOptions->PartnerOrders = true;
$orderSearchOptions->Pagination = new stdClass();$orderSearchOptions->Pagination->Page = 2;
$orderSearchOptions->Pagination->Limit = 25;

try {
    $orders = $client->searchOrders($sessionID, $orderSearchOptions);
}
catch (SoapFault $e) {
    echo "orders: " . $e->getMessage();
    exit;
}

var_dump("orders", $orders);
               
?>

Response

A successful searchOrders call via SOAP API 6.0 returns:

Per-product selling restrictions

Essentially, you can limit product sales into:

• A specific country
• Multiple countries

At the same time, you can block product sales that involve

• A specific payment method
• Multiple payment methods

Reasons for restrictions vary but can include the need to adhere to the applicable laws, regulations, controls, policies, etc. of the country/countries in which your company operates, including embargoes. See here a list of OFAC countries restrictions.

Restrict sales in specific countries based on credit cards

In addition to per-product selling restriction, 2Checkout also enables you to restrict sales to customers in specific markets based on the credit card they're using. This feature blocks an entire range of cards based on the first 6 digits of the credit card number (the Issuer Identification Number (IIN), or on the bank identification number (BIN)). This setting impacts your entire account, whereas per-product restrictions apply only to specific offerings.

2Checkout displays the following message to customers: "The payment could not be processed due to legal restrictions related to the country associated with this card. Please retry with a different card or choose to finalize the order with a different payment method."

You can contact 2Checkout directly if you require product sales to be restricted.

Restrict sales based on country

To restrict purchases from a certain country, you can use the settings in your Merchant Control Panel.

1. Log in to your 2Checkout Control Panel.
2. Go to Dashboard → Setup → Ordering options.
3. Scroll down to the Billing countries section.
4. Select a country from the left side column and move it to the restricted countries list on the right. This will prevent shoppers from selecting restricted countries for the billing address in the shopping cart.
5. Click on the Save settings button at the bottom of the page to update your settings.

Overview

Use the getPromotion method to extract information on a promotion you set up for your account.

Parameters

Response

Promotion object.

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'YOUR_COUPON_CODE';

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

?>

Overview

Use the PayPal Express 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. 

Related links

Availability

PayPal Express Checkout is available for all account types on both business models (PSP & Reseller). 

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.

PayPal Express Checkout Flow 

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

When using 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.

PayPal Express Checkout links query parameters

You can build buy-links for the PayPal Express 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 buy-link for PayPal

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.
4. Click on the Show advanced options link, and select PayPal from the Payment method drop-down menu in the Additional options area.
5. Configure additional advanced options, if needed.
6. Scroll down to the bottom of the page and click the Generate link button.
7. The 2Checkout system will build a link such as the following:

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

Express Checkout Workflow with PayPal

1. Shoppers click on the Express payments checkout flow with PayPal Buy-Link and are redirected to PayPal.
2. Shoppers log in to PayPal and are displayed an order summary containing preliminary prices. Note: For free orders, 2Checkout needs to authorize $1/1EUR to validate the PayPal account (the credit/debit cards associated with the account). This is a common industry-wide practice for e-commerce companies. Pre-authorizations are designed to ensure that credit/debit cards and PayPal accounts (the credit/debit cards associated with PayPal accounts) are valid and that the necessary funds exist to charge customers for trial conversions and subscription renewals. Temporary charges used for the pre-authorization process are reversed within one hour.
3. Shopper advances to the "Review your information" page. The Shipping address details from PayPal will be copied to the 2Checkout Billing and Delivery information.
4. Shoppers click on Continue and are redirected back to the 2Checkout shopping cart in the verify.php page. Billing and Delivery information are not editable at this point. Depending on the shipping address in PayPal, the final costs of the order may vary, due to the addition of taxes.
5. Shoppers click on Place Order to finish the purchase process.
6. 2Checkout charges the shopper, which is taken to the Thank you page.

PayPal Express Checkout for ConvertPlus

1. Navigate to Generate links under Setup.
2. Select the ConvertPlus checkout flow option under the Checkout links area.
3. Select one or more products.
4. Configure additional options, if needed.
5. Scroll down to the bottom of the page and click the Generate link button.
6. The 2Checkout system will build a link such as the following:

https://secure.2checkout.com/checkout/buy?merchant=AVLRNG&tpl=default&prod=74B8E17CC0&qty=1

7. Copy and paste the link on your web store. When your shoppers click on the PayPal button in cart, to select it as a payment method, they will be redirected to PayPal, as shown in the image below.

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

Use the deleteSkuByCode method to remove SKU information using the unique identifier you assign to the SKU schema. 

When requesting to delete SKU by code, the system will verify if the specific SKU is valid for that product code or pricing configuration code. If not, the 2Checkout system will return an error. The method supports multiple combinations of product code, pricing configuration code and SKU code in one call.

Request Parameters

Request Example

Response Parameters

Response Example

Overview

Use the setProductStatus method to enable / disable products for your account. 

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$productCode = "YourProductCode";

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

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

?>

Response

bool(true)

Overview

Subscription contract period capabilities provide an increased level of control over the evolution and lifecycle of subscriptions sold to your customers, on top of billing cycles. Adding a contract period to a subscription means that you can configure subscriptions that:

• Renew a number of times during a contractual period after which the contract is automatically restarted, unless customers opt-out;
• Renew a number of times during a contractual period after which the contract expires causing the subscriptions it governs to be disabled and blocking customers from renewing, either automatically or through manual payments.

Availability

Contact 2Checkout directly if you wish to start using contracts for your subscriptions. 

Requirements

Subscription contract period functionality can be used only in conjunction with products for which subscriptions are generated.

Contract settings impact only active subscriptions.

Create a subscription contract period

To create a subscription contract period, follow the steps:

1. Go to Setup -> Products.
2. Ssearch and find the product for which you want to define a subscription contract
3. Click Edit.
4. Select the Billing cycle specific for the subscriptions generated for the product from the list of options available under the Billing cycle drop down menu. Note:Subscription contract period is not available when the one time fee option is selected / for evergreen subscriptions.
5. Configure the Contract period in months.

Contract period options

There are two subscription contract periods:

1. Unlimited - When this option is selected, Contracts have no impact on the billing cycle or the lifecycle of subscriptions. Essentially, subscription with the billing cycle set to 1 month will be renewed on a monthly basis indefinitely is the Contract option selected is unlimited.
2. Limited to [number of months] - When this option is selected, the Contract limits billing cycles to the number of months you configure.

Use this option to define the period of time the subscription can be renewed, according to the billing cycles configuration, per contract agreed with your customers. In addition, you can also set the outcome of the Contract expiration, by choosing one of two options:

1. Automatically renews - 2Checkout renews the Contract automatically at the end of the contract period defined with the same value (if it was not modified), unless customers choose to not prolong the agreement, by opting out of the contract. Contracts restart when subscriptions are renewed for the first time past the duration of the old contract. If the value of the Contract period is modified, it will only impact new subscriptions sold. Existing subscriptions move under the new Contract when they renewed for the first time past the period of the old contract.
2. Expires - the Contract expires at the end of the contract period defined. When Contracts expire the subscriptions they govern also expire automatically, and will not be switched to the manual renewal model. Customers will not be given the chance to prolong their agreement and the life of the subscription. The 2Checkout system will not send out emails to let customers make payments manually to renew subscriptions and their Contracts.

Editing contract settings

Contract period settings for a product can be edited at any time. However, the new contract period set will only impact new subscriptions sold to customers. Existing subscriptions will continue to be governed by the same contract as when they were first sold, until the contract is automatically renewed or expires. When subscriptions are renewed, 2Checkout swapes the period parameters of the old contract for the current contract settings defined.

Subscription upgrades

For an upgrade from Product A to Product B, where both products have contract settings the expected behavior for the subscription is to switch start a new contract cycle according to Product's B settings.

Renew with new product version

1. When renewing with a new product version, from Product A to Product B, where Product A has no contract settings and B has contract settings, the expected behavior for the subscription is to start a contract on Product B's Contract settings.
2. When renewing with a new product version from Product A to Product B, where Product A nd Product B both have contract settings, the expected behavior for the subscription to have its contract period swapped to the Product B Contract settings the first time it's renewed past the Contract period of Product A.
3. If the contract for Product A is set to expire, then subscriptions will work only until contract expiration deadline, after which they will be disabled, regardless if the contract settings of Product B, in the context of a renewal with a new product version.

Trials

Contracts for products for which you're offering free or paid trails to your customers only start impacting subscriptions after evaluation versions converted to paying products.

Shopper emails for contracts

In concert with Subscription contract period feature, you can control emails 2Checkout sends to customers. Two options are available to send shopper emails:

1. For each Billing cycle period - Customers  continue to receive emails according to the setup in place and your strategy to communicate subscription renewals and charges. Messages include:
   • Renewal notifications
   • Order confirmations
   • Payment receipts
2. At the end of the Subscription contract period - Emails are sent to customers only at the end of the subscription contract period. When this option is selected, the 2Checkout system blocks all emails from being sent to the customers using the subscriptions of the product impacted by this configuration. As such, customers will not receive:
   
   • Renewal notifications;
   • Order confirmations;
   • Payment receipts.

Send shopper emails each billing cycle period:

• The 2Checkout system sends emails to shoppers each billing cycle for limited contracts that are set to automatically renew.
• The 2Checkout system sends emails to shoppers each billing cycle except the last, after which subscriptions are disabled for limited contracts that are set to expire.

Send shopper emails each subscription contract period:

• The 2Checkout system send emails to shoppers when they first purchase the subscription and at the end of the last billing cycle of the contract period as well as the first time they renew after the contract is restarted for limited contracts that are set to automatically renew.
• The 2Checkout system send emails to shoppers only when they first purchase the subscription for limited contracts that are set to expire.

Manual renewal messages

Send shopper emails each:

• Billing cycle period: shoppers continue to receive manual renewal notifications ahead of the next upcoming expiration deadline as long as they manually renew their subscription.
• Subscription contract period: shoppers do not receive manual renewal notifications.

FAQ

• What happens when the contract period is not a multiple of billing cycles?

  • If the contract period is not a multiple of billing period, for example a 7 months contract for a subscription set to renew every 3 months, then the 2Checkout system will allow subscriptions to be renewed either automatically or manually only as long as the contract period is not exceeded. For example, in the scenario of a 3 months billing cycle subscription governed by a 7 months contract there will be only 2 billing cycles/ contract, after which the contract auto-renews or expires, according to the settings you configured.

Overview

Use the pauseSubscription method to suspend all automatic charges for a predefined time period for a subscription.

Request Parameters

Request Example

<?php
$sb = "58";
$vers = "6.0";
$client = new SoapClient("http://api.sandbox" . $sb . ".avangate.local/soap/$vers/?wsdl", array(
    'location' => "http://api.sandbox" . $sb . ".avangate.local/soap/$vers/",
    'cache_wsdl' => WSDL_CACHE_NONE,
    "trace" => 1));
$date = gmdate('Y-m-d H:i:s');
$merchantCode = "666999";
$key = "%y~8|m]T84p[W4+O1]_?";
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);
$sessionID = $client->login($merchantCode, $date, $hash);
var_dump("session: ", $sessionID);
//$client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
$SubRef = "B7D8E72224";
$resumeDate = "2020-09-30 17:00:00";
$reason = "vacation leave";
try {
    $addPause = $client->setRenewalPause($sessionID, $SubRef, $resumeDate, $reason);
    var_dump("setRenewalPause:", $addPause);
} catch (SoapFault $e) {
    echo "Error setRenewalPause: " . $e->getMessage();
}
try {
    $renewalPause = $client->getRenewalPause($sessionID, $SubRef);
    var_dump("getRenewalPause:", $renewalPause);
} catch (SoapFault $e) {
    echo "Error getRenewalPause: " . $e->getMessage();
}
exit;

Response 

The pauseSubscription call returns the above TRUE/FALSE parameters.

Set INS triggers

In your Control Panel Dashboard, navigate to Dashboard → Integrations → Webhooks and API and click on the INS settings tab. Select the events for which 2Checkout sends notifications from the list of options available under Triggers.

For each trigger enabled, you are able to select which URL endpoint receives the notification, as well as customize the list of parameters included in the notification. Read more about INS parameters here.

Instant Notification Service (INS) provides automatic notifications for orders from the 2Checkout system, based on the following list of triggers you control:

Overview

Use the getPromotion method to extract information on a promotion you set up for your account.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'PROMOTION_CODE'; // code of the promotion that you want to update

try {
    $Discount = $client->getPromotion($sessionID, $promotionCode);
}
catch (SoapFault $e) {
    echo "Discount: " . $e->getMessage();
    exit;
}

var_dump("Discount", $Discount);