Overview

Manage the lifecycle of your subscriptions and control different processes such as delaying the start of a subscription, canceling a subscription, searching a subscription from the Subscriptions page in your Merchant Control Panel.

Availability 

The Subscriptions section is available to all 2Checkout accounts. For more details about subscriptions, read here.

Overview

Use this object to retrieve information about the cross-sell campaigns you configured for your account. 

Parameters

Overview

Use the convertTrial method to convert a trial to a paid subscription. In the eventuality of a conversion failure, you can use convertTrial again for the same trial subscription only after you let 24 hours pass since the initial attempt. The 2Checkout system attempts to automatically convert trials before they expire to full subscriptions, unless you made an attempt that failed less than 24 hours before the scheduled expiration deadline.

In case the trial conversion fails due to a transaction issue, the 2Checkout system sends unfinished payment follow-up emails to customers, provided that you set up lead management for your account.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH'); 
 
$SubscriptionReference = 'BF44555C6C';

$ExtendSubscriptionFromPaymentDate = true; //false can also be used if you want the subscription start date to be the moment when the trial was set to initially expire.

try {
    $convertedTrial = $client->convertTrial($sessionID, $SubscriptionReference, $ExtendSubscriptionFromPaymentDate);
}
catch (SoapFault $e) {
    echo "convertedTrial: " . $e->getMessage();
    exit;
}
var_dump("convertedTrial", $convertedTrial);

Overview

Use the searchLeads method to retrieve leads created in the 2Checkout system.

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$LeadSearchInput = new stdClass();

$LeadSearchInput->Type = "New";
$LeadSearchInput->Language = "BG";
$LeadSearchInput->Country = "RO";
$LeadSearchInput->Page = 1;
$LeadSearchInput->Limit = 200;

try {
    $leadData = $client->searchLeads($sessionID, $LeadSearchInput);
} catch (SoapFault $e) {
    echo "searchLeads: " . $e->getMessage();
    exit;
}

var_dump("searchLeads", $leadData);

Response Example

class stdClass#4 (2) {
  public $Items =>
  class stdClass#5 (1) {
    public $0 =>
    class stdClass#6 (14) {
      public $LeadCode =>
      string(10) "60E6C4B574"
      public $GeneratedFrom =>
      string(3) "API"
      public $CartId =>
      string(11) "CartIdValue"
      public $Currency =>
      string(3) "EUR"
      public $Language =>
      string(2) "BG"
      public $ExternalReference =>
      string(18) "REST_API_3CHECKOUT"
      public $MachineId =>
      string(6) "123asd"
      public $LocalTime =>
      string(19) "2019-11-05 16:48:28"
      public $Items =>
      class stdClass#7 (1) {
        public $0 =>
        class stdClass#8 (15) {
          public $Code =>
          string(10) "04C26C50F8"
          public $Quantity =>
          string(1) "2"
          public $SKU =>
          NULL
          public $Name =>
          string(5) "softy"
          public $Description =>
          NULL
          public $IsDynamic =>
          bool(false)
          public $Tangible =>
          bool(false)
          public $PurchaseType =>
          string(7) "PRODUCT"
          public $PriceOptions =>
          NULL
          }
          public $RecurringOptions =>
          class stdClass#9 (5) {
            public $CycleLength =>
            NULL
            public $CycleUnit =>
            NULL
            public $CycleAmount =>
            NULL
            public $ContractLength =>
            NULL
            public $ContractUnit =>
            NULL
          }
          public $RenewalInformation =>
          class stdClass#10 (1) {
            public $SubscriptionReference =>
            NULL
          }
          public $MarketingCampaigns =>
          class stdClass#11 (3) {
            public $Type =>
            string(2) "23"
            public $ParentCode =>
            string(1) "m"
            public $CampaignCode =>
            string(2) "23"
          }
          public $Price =>
          class stdClass#12 (2) {
            public $Amount =>
            string(2) "20"
            public $Type =>
            string(6) "CUSTOM"
          }
          public $AdditionalFields =>
          NULL
          public $SubscriptionStartDate =>
          string(19) "2019-11-05 16:48:28"
        }
      }
      public $BillingDetails =>
      class stdClass#13 (12) {
        public $FirstName =>
        string(8) "Customer"
        public $LastName =>
        string(9) "2Checkout"
        public $Phone =>
        NULL
        public $Company =>
        NULL
        public $FiscalCode =>
        string(8) "32423423"
        public $Email =>
        string(22) "customer@2checkout.com"
        public $Address1 =>
        string(12) "Test Address"
        public $Address2 =>
        NULL
        public $City =>
        string(2) "LA"
        public $Zip =>
        string(5) "12345"
        public $CountryCode =>
        string(2) "RO"
        public $State =>
        string(2) "CA"
      }
      public $DeliveryDetails =>
      class stdClass#14 (12) {
        public $FirstName =>
        string(8) "Customer"
        public $LastName =>
        string(9) "2Checkout"
        public $Phone =>
        NULL
        public $Company =>
        NULL
        public $FiscalCode =>
        string(8) "32423423"
        public $Email =>
        string(22) "customer@2checkout.com"
        public $Address1 =>
        string(12) "Test Address"
        public $Address2 =>
        NULL
        public $City =>
        string(2) "LA"
        public $Zip =>
        string(5) "12345"
        public $CountryCode =>
        string(2) "RO"
        public $State =>
        string(2) "CA"
      }
      public $DeliveryInformation =>
      class stdClass#15 (1) {
        public $ShippingMethod =>
        class stdClass#16 (1) {
          public $Code =>
          string(5) "sdfsd"
        }
      }
      public $PaymentDetails =>
      class stdClass#17 (4) {
        public $Type =>
        string(2) "CC"
        public $Currency =>
        string(3) "EUR"
        public $PaymentMethod =>
        class stdClass#18 (2) {
          public $RecurringEnabled =>
          bool(false)
          public $CardPayment =>
          class stdClass#19 (1) {
            public $InstallmentsNumber =>
            string(2) "23"
          }
        }
        public $CustomerIP =>
        string(7) "1.2.3.4"
      }
      public $Promotions =>
      array(1) {
        [0] =>
        string(0) ""
      }
    }
  }
  public $Pagination =>
  class stdClass#20 (3) {
    public $Page =>
    int(1)
    public $Limit =>
    int(200)
    public $Count =>
    int(1)
  }
}

Overview

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

Retrieve a customer

Customer object

Overview

With Trustly, you can accept payments, issue payouts, and access valuable user insight data. Easy activation and multi-currency functionality give you the power to expand your business across borders with access to customers in Europe, Australia, Canada, and the US.

Availability

Trustly is available for shoppers in the following countries:

• Austria
• Croatia
• Cyprus
• Czech Republic
• Denmark
• Estonia
• Finland
• Germany
• Latvia
• Lithuania
• Malta
• Netherlands
• Norway
• Spain
• Sweden
• United Kingdom

Requirements

Make sure the billing country code is set to AT, CY, CZ, DE, DK, EE, ES, FI, GB, HR, LT, LV, MT, NL, SE.

Supported currencies

• CZK
• DKK
• EUR
• GBP
• NOK
• SEK

Workflow

1. Shoppers select Trustly as a payment option in the interface you provide to them.
2. Create the order object. Use TRUSTLY as the type of the PaymentDetails object, and include ReturnURL.
3. Use the placeOrder method to send the data to 2Checkout.
4. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING.
5. 2Checkout returns an order object as the output of the placeOrder method. 
6. Use the PaymentMethod object to create a redirect URL for the shoppers, concatenating the values of the Href and avng8apitoken parameters. Here's an example of the redirect URL: https://api.avangate.com/6.0/scripts...bc7fd72d008428
7. After being redirected to Trustly, shoppers need to complete the steps of Trustly payment flow.
8. After customers enter their payment data to Trustly, Trustly notifies 2Checkout if the payment is approved, and the status of the order becomes COMPLETE.
9. Shoppers are redirected to the RedirectURL from the order information object. In case the payment fails, shoppers are redirected to the CancelURL. 

Overview

Refund a sale made in 2Checkout via the issueRefund API method. Depending on your business needs, you can refund only one sale item, the entire order amount, or a partial amount from the total order.

Requirements

The payment for the refundable order needs to be collected.

You cannot issue a refund for an amount higher than the total order amount.

Parameters

Overview

In the US, sales tax is required for transactions in most states, and it is imposed on the end-consumers who receive the delivery of the order (digital or physical). Some organizations and individuals are exempt from paying this sales tax, for various reasons. Tax Exemption Certificates (TEC) are the proof by which a business, institution or individual attests that it is a tax-exempt entity, or that it is purchasing an item with the intent to use it in a way that has been deemed exempt from having sales tax applied.

Availability

• US Sales Tax Exemption is available upon request to merchants using the reseller business model (MOR). Contact Merchant Support (supportplus@2checkout.com) to enable it on your account.
• New orders with US sales tax exemption are available when using ConvertPlus/Inline cart shopping carts or via the API integration.
• Support for automatic renewal orders with US sales tax exemption is available, as long as the initial/previous order was flagged as tax-exempt (on any integration type).

Tax-exempt orders

To receive orders with US sales tax deducted from the total value, a 2Checkout tax-exempt ID needs to be filled in during the ordering process. The tax-exempt ID is generated by the 2Checkout support team upon receiving tax-exemption proof from a business/institutional shopper. 

2Checkout tax-exempt ID

To request a 2Checkout tax-exempt ID, shoppers must send an email to refund@2checkout.com along with the Tax Exemption Certificate (TEC). 2Checkout tax-exempt ID is applicable only for B2B orders (placed by a US-registered entity).

Common reasons for sales tax-exemption are related to the fact that the shoppers are purchasing with the intent to resell or that they are purchasing for an entity that fits in one of these categories:

• Federal, local or tribal government institutions.
• Educational, religious or charitable entities.
• Foreign diplomatic organizations.

If the Tax Exemption Certificate requires the shopper to fill in a seller name, the following company information must be included:

• Avangate Inc dba 2Checkout, 1170 Great Oaks Way no. 210, 30022 Alpharetta, Georgia
• Verifone Payments BV dba 2Checkout, Singel 250, Amsterdam 1016AB, Netherlands

New orders

When placing a new order, the shopper must fill in the 2Checkout tax-exempt ID to deduct taxes from the order value before placing it.

1. During the checkout, the Business order flow needs to be selected.
2. United Stated of America needs to be selected as a billing/delivery country. Company name and state need to match what is referenced on the Tax Exemption Certificate.
3. The shopper needs to check the The company is tax exempt option.
4. The 2Checkout tax-exempt ID needs to be filled in the dedicated field.
5. If validation is successful, the tax amount will be displayed as zero. Validation checks for a match between the 2Checkout tax-exempt ID, company name, state and validity period of the provided tax exemption certificate.
6. The shopper can proceed with the order flow.

Automatic renewal orders

If the initial order triggering the purchase of a recurring subscription is made using a valid 2CO tax exempt ID, all subsequent automatic renewals will inherit the tax exemption status (as long as the Tax Exemption Certificate is still within validity period).

Alternatively, 2Checkout can refund the sales tax to the customer's payment account after the transaction is complete. The refund can be requested by the shopper by emailing a copy of their Tax Exemption Certificate together with the order details to refund@2checkout.com.

Once the initial order is flagged as tax-exempt in the 2Checkout system, all renewals linked to that order will also be tax-exempt if the certificate the shopper has provided is still valid when the renewal order is created.

Overview

Use the convertTrial method to convert a trial to a paid subscription. In the eventuality of a conversion failure, you can use convertTrial again for the same trial subscription only after you let 24 hours pass since the initial attempt. The Avangate system attempts to automatically convert trials before they expire to full subscriptions, unless you made an attempt that failed less than 24 hours before the scheduled expiration deadline.

In case the trial conversion fails due to a transaction issue, the Avangate system sends unfinished payment follow-up emails to customers, provided that you set up lead management for your account.

Parameters

Response

Request

<?php
 
 
function callRPC($Request, $hostUrl, $Debug = true) {
    $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_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
 
 
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $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;
    }
}
 
$host = 'https://api.avangate.com/rpc/3.0/';
 
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
 
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
 
$i = 1; // counter for api calls
// call login
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
 
$sessionID = callRPC($jsonRpcRequest, $host);
 
var_dump($sessionID);
$SubscriptionReference = 'BF44555C6C';
$ExtendSubscriptionFromPaymentDate = true; //false can also be used if you want the subscription start date to be the moment when the trial was set to initially expire.

$jsonRpcRequest = array (
'method' => 'convertTrial',
'params' => array($sessionID, $SubscriptionReference, $ExtendSubscriptionFromPaymentDate),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

In the US there are various organizations and individuals that are exempt from taxes for various reasons. This exemption sometimes also covers sales tax for purchased goods, depending on a number of factors. Tax Exemption certificates are the way in which a business or organization attests that it is a tax-exempt entity, or that you are purchasing an item with the intent to use it in a way that has been deemed exempt from tax.

Sales tax is required for transactions in 45 US States and it is imposed only on the end-consumers. If you are a Channel Manager Partner who is purchasing products for resale to end-consumers, you must provide 2Checkout with the following information:

• Valid Reseller Tax Exemption Certificate for your business location State, or
• Valid Multi-State Reseller Tax Exemption Certificate for all jurisdictions where you’re registered

By providing 2Checkout with a Reseller Tax Exemption Certificate, you agree that:

1. You are purchasing products for resale to end-consumers
2. You will collect and remit sales tax on taxable sales made to your customers who are taxable end-consumers.

Once your Reseller Tax Exemption Certificate has been submitted and reviewed by 2Checkout, we will not charge US State sales tax on transactions with you. On products you purchase from us for resale, you must still collect and remit the US State sales tax on your transactions with your end-consumers in accordance with the State law of the purchaser.

Availability

The feature is available for merchants that use the reseller business model (2Monetize package) and the 2Checkout Channel Manager solution with active partners who have submitted their Reseller Tax Exemption Certificate.

For merchants in the EU and other jurisdictions not imposing VAT on VAT-registered purchasers, VAT will not be applied to your purchase if a valid VAT ID is used by the partner in their account. The tax exemption certificate described above is valid only for US transactions.

How to activate the Channel Manager Tax Exemption

You can find information regarding Reseller Tax Exemption Certificates along with proper forms on your State Department of Revenue website. In most US states, you can simply download the form for completion and signature. In some States, these Exemption Certificates are only issued by the State Department of Revenue at your request.

You can submit a request for activating the tax exemption option by sending an email to operations@2checkout.com. The application will be processed by the Financial Operations department that will request in turn a Reseller Tax Exemption Certificate. After the certificate is validated, your account will be marked as exempt from the US sales tax. 

Orders placed by partners that are marked as tax-exempt will not be charged the US State sales tax (in the Channel Manager portal), as shown in the image below.