Skip to main content

Create customer

Overview

Use the createCustomer method to add the details of a customer entity into the 2Checkout system. By default, customer status is Inactive until you assign a specific subscription to the customer. Following that action, customer status reflects the status of the attached subscription(s).

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Customer

Object

Response

Parameters Type/Description

AvangateCustomerReference

Int

 

System-generated customer reference.

Request

<?php

require ('PATH_TO_AUTH');

$newCustomer = new stdClass();
$newCustomer->AvangateCustomerReference = null;
$newCustomer->ExternalCustomerReference = 'ThisIsATestReference123456';
$newCustomer->FirstName = 'NewCustomer';
$newCustomer->LastName = 'NewCustomerLastName';
$newCustomer->Company = null;
$newCustomer->FiscalCode = null;
$newCustomer->Address1 = 'Address';
$newCustomer->Address2 = null;
$newCustomer->City = 'LA';
$newCustomer->Zip = '90210';
$newCustomer->CountryCode = 'us';
$newCustomer->Phone = null;
$newCustomer->Fax = null;
$newCustomer->Email = 'newcustomer@email.com';
$newCustomer->ExistingCards = null;
$newCustomer->Enabled = null;
$newCustomer->Trial = null;
$newCustomer->Language = 'en';

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

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

Set sale source in the InLine Cart

Overview

Use the Cart object to set a sale source for the InLine Cart by calling theTwoCoInlineCart.cart.setSource(source)method.

Use case

  1. Add an HTML link or button in your page like the one below.
  2. Create a JavaScript click handler to execute the Inline Client desired methods.
  3. Use theTwoCoInlineCart.products.add({code, quantity, options})method to prepare your catalog product.
  4. In order to set sale source useTwoCoInlineCart.cart.setSource('YouTube Channel').
  5. Use theTwoCoInlineCart.cart.checkout()method to show the cart on your page.

Sample request

HTML

<a href="#" class="btn btn-success" id="buy-button">Buy now!</a>

Javascript

window.document.getElementById('buy-button').addEventListener('click', function() {
  TwoCoInlineCart.products.add({
    code: "74B8E17CC0"
  });
  TwoCoInlineCart.cart.setSource('YouTube Channel');
  TwoCoInlineCart.cart.checkout();
});

Demo

After setting the sale source to the InLine cart using the above method, your cart should look like this:

 

Product

Overview

Use the Product object to create/add, update/edit and retrieve subscription plans/products for your account. You can control:

  • Product information
  • Pricing
  • Subscription plan settings and renewal configuration
  • Subscription plan recurring billing
  • Fulfillment
  • Shipping classes
  • Localization

Parameters

Product

 

Object

AvangateId

String

 

Unique, system-generated Avangate product ID. Read-only.

ProductCode

String

 

The product code that you can define for each of your offerings. Needs to be unique.

ProductType

String

 

REGULAR or BUNDLE

ProductName

String

 

The name of the product

ProductVersion

String

 

The product version number

GroupName

String

 

The name of the Product Group to which the product belongs. Cannot be edited as part of the addProduct API call.

ShippingClass

Object

 

Existing shipping class object with the structure detailed below.

GiftOption

boolean

 

True or false depending on whether the product can be gifted or not.

ShortDescription

String

 

The product's short description

LongDescription

String

 

The product's long description

SystemRequirements

String

 

System requirements

ProductCategory

String

 

Product category

Platforms

Array of Platform objects

 

Array of objects detailing the platforms supported by the application. Details below.

ProductImages

Array of Image objects

 

Image object. Details below. Read-only.

TrialUrl

String (anyURI)

 

The URL from where shoppers can download trial software.

TrialDescription

String

 

Descriptive text entered for trials.

Enabled

Boolean

 

True/false depending on whether the products are active or disabled. When empty, Avangate marks the product as disabled.  

AdditionalFields

Array of AdditionalFieldAssigned objects

 

Array of existing additional fields assigned to products. Details below.

Translations

Array of ProductTranslation objects

 

Details below.

PricingConfigurations

Array of PricingConfiguration objects

 

Details below. Avangate creates pricing configurations during the process when you add a product.

BundleProducts

Array of BundleProductCode objects

 

Details below.

Fulfillment

String

 

BY_AVANGATE

NO_DELIVERY – The Avangate system finalizes orders immediately after it receives payment confirmation.

BY_VENDOR – you are responsible for delivering/fulfilling orders

Prices

Array of Price objects

 

Use this object only when Pricing Configurations are not available for your account. Details below.

GeneratesSubscription

boolean

 

TRUE or FALSE depending on whether you set the product to generate subscriptions or not.

 

NULL for bundles for which you set the following subscription management option: “Use the subscription settings of each product in the bundle”

SubscriptionInformation

ProductSubscriptionInformation Object

 

Details below. NULL for bundles which you set to use the renewal settings of child products and not of the parent bundle.

FulfillmentInformation

Object

 

Details below. Can be NULL. Available only in Product API 2.5 and later.

 

ShippingClass

Object

Name

String

 

The name of the shipping class

Amount

Decimal

 

The shipping costs

Currency

String

 

The currency ISO code used for shipping costs - ISO 4217.

ApplyTo

String

 

Possible values:

• PRODUCT

• ORDER

Type

Possible values:

• FIXED

• PERCENT

 

Platform

Object

PlatformName

String

 

The label of the platform per the product configuration.

Category

String

 

Platform category per product configuration. 

 

ProductImage

Object (Read-only)

Default

Boolean

 

True or False depending on whether you set the image stored at the address in the URL parameter as default or not.

URL

String

 

The location of the image on the Avangate system.

 

AdditionalFieldAssigned

Object

Label

String

 

The name of the additional field assigned to a product.

Code

String

 

The code of the additional field assigned to a product.

Enabled

Boolean

 

True or false depending on whether the assigned product field is enabled or not.

Required

Boolean

 

True or false depending on whether the assigned product field is required or not.

URLParameter

String

 

The value of the system generated URL parameter for the product field that can be used in Buy Links.

 

Translation

Object – ISO 639-1 two-letter code

LongDescription

String

 

The translated long description in the language corresponding to the Translation object.

TrialUrl

String

 

The trial URL for users speaking the language corresponding to the Translation object.

TrialDescription

String

 

 

SystemRequirements

String

 

Localized system requirements.

Name

String

 

Localized product name.

Description

String

 

Localized product short description.

Language

String

 

ISO 639-1 two-letter code.

 

PricingConfiguration

Object

Name

String

 

Pricing configuration name

Code

String

 

System-generated identifier.

Default

boolean

 

True for the default pricing configuration

BillingCountries

Array of strings

 

ISO codes of the countries assigned to the pricing configuration.

Empty unless specific countries are assigned to a pricing configuration.

PricingSchema

String

 

DYNAMIC – With a base price

FLAT – Without a base price

PriceType

String

 

Possible values:  NET / GROSS

DefaultCurrency

String

 

The ISO code of the default currency for the pricing configuration

Prices

Object

 

Details below.

PriceOptions

Array of AssignedPriceOptionGroup objects

 

Details below.

 

Prices

Object

Regular

Array of objects

 

Details below.

Renewal

Array of objects

 

Details below.

 

Regular

Object

Amount

Int

 

The price of the product.

Currency

String

 

ISO code of the currency for the product price.

MinQuantity

Int

 

The minimum quantity of volume discounts. Default is 1.

MaxQuantity

Int

 

The maximum quantity of volume discounts. Default is 99999.

OptionCodes

Array of objects

 

Details below.

 

Renewal

Object

Amount

Int

 

The price of the product.

Currency

String

 

ISO code of the currency for the product price.

MinQuantity

Int

 

The minimum quantity of volume discounts. Default is 1.

MaxQuantity

Int

 

The maximum quantity of volume discounts. Default is 99999.

OptionCodes

Array of PriceOptionCode objects

 

Details below.

 

PriceOptions

Object

Code

String

 

System generated pricing options group code (you can also configure it) that the Avangate system uses to calculate product prices for pricing configurations without a base price.

Required

Boolean

 

True or False depending on whether you want to make it mandatory for shoppers to select the price option during the puyrchase process.

 

PriceOptionCode

Object

Code

String

 

Price option identifier.

Options

Array of strings

 

The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.

 

BundleProducts

Object

ProductId

String

 

Unique, system-generated product ID.

ProductCode

String

 

Editable product code that you control.

 

Prices

Object - Use this object only when Pricing Configurations are not available for your account.

Amount

Int

 

The price of the product.

Currency

String

 

ISO code of the currency for the product price.

MinQuantity

Int

 

The minimum quantity of volume discounts. Default is 1.

MaxQuantity

Int

 

The maximum quantity of volume discounts. Default is 99999.

OptionCodes

Array of objects

 

Details below.

 

PriceOptions

Object

Code

String

 

System generated pricing options group code (you can also configure it) that the Avangate system uses to calculate product prices for pricing configurations without a base price.

Required

Boolean

 

True or False depending on whether you want to make it mandatory for shoppers to select the price option during the puyrchase process.

 

SubscriptionInformation

Object

 

NULL for bundles for which you set the following subscription management option: “Use the subscription settings of each product in the bundle”

DeprecatedProducts

Array

 

Deprecated products.

BundleRenewalManagement

String

 

Possible values:

  • GLOBAL
  • INDIVIDUAL

Can be NULL.

UpgradeProductCode

String

 

Code belonging to the upgrade product.

BillingCycle

String

 

The number of subscription billing cycle units (months or days).  Possible values:

  • 0 (zero represents a one-time fee)

Days

  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14

 

Months

  • 1
  • 2
  • 3
  • 6
  • 12
  • 15
  • 18
  • 24
  • 36 (max)

BillingCycleUnits

String

 

The units of the billing cycle:

  • M - months
  • D - days

IsOneTimeFee

Boolean

 

True or False depending on whether the subscription is evergreen or not.

ContractPeriod

Object

 

Details below.

UsageBilling

Int

 

The usage billing interval must be smaller than or equal to the grace period.

 

Interval of time within the grace period, when the Avangate system attempts to automatically charge customers for recurring costs and additional metered usage fees (in arrears). Avangate renews subscriptions only after subscribers make all outstanding payments per the renewal settings (from the expiration or the renewal date). If automatic renewal and usage charges fail, subscriptions can be manually renewed only by the end of the grace period, after which they expire.

 

Can be NULL.

GracePeriod

Object

 

Details below.

RenewalEmails

Object

 

Details below. Can be NULL. Available only in Product API 2.5 and later.

 

ContractPeriod

Object

Period

Int

 

The contract period in months or days. -1 for unlimited contracts.

PeriodUnits

String

 

The contract period units

days | months

IsUnlimited

boolean

 

This flag is true if the contract is for an unlimited period

Action

String

 

The action performed after the subscription expires.

Possible values CANCEL | RESTART

EmailsDuringContract

Boolean

 

True or False depending on whether you suppress renewal notification emails throughout the duration of the contract or not.

GracePeriod

Object

Type

String

 

CUSTOM – you configured grace period setting at product level.

GLOBAL – global grace period settings apply.

Period

String

 

Number of days set for the grace period.

PeriodUnits

String

 

D - Days.

IsUnlimited

Boolean

 

True or False depending on whether you set the grace peri2od to unlimited or not.

 

RenewalEmails 

Object (can be NULL)

Type 

String

 

GLOBAL - Send emails according to the global renewal notification settings.

CUSTOM – per product renewal notification settings

Settings

Object (can be NULL)

 

Details below.

 

Settings 

Object (can be NULL)

ManualRenewal

Object (can be NULL)

 

Details below.

AutomaticRenewal

Object (can be NULL)

 

Details below.

 

ManualRenewal

Object (can be NULL)

Before30Days 

Boolean

 

True or False.

Before15Days 

Boolean

 

True or False.

Before7Days 

Boolean

 

True or False.

Before1Day 

Boolean

 

True or False.

OnExpirationDate 

Boolean

 

True or False.

After5Days

Boolean

 

True or False.

After15Days 

Boolean

 

 

 

AutomaticRenewal

Object (can be NULL)

Before30Days 

Boolean

 

True or False.

Before15Days 

Boolean

 

True or False.

Before7Days 

Boolean

 

True or False.

Before1Day 

Boolean

 

True or False.

OnExpirationDate 

Boolean

 

True or False.

After5Days

Boolean

 

True or False.

After15Days 

Boolean

 

 

FulfillmentInformation

Object (can be NULL)

IsStartAfterFulfillment 

Boolean

 

True or False. Depending on whether you want the subscription lifetime to start afther the completion of the fulfillment process or not.

IsElectronicCode 

Boolean

 

True or False. Depending on whether you configure the delivery of keys/codes for the product or not.

IsDownloadLink 

Boolean

 

True or False. Depending on whether you configure the delivery of a product file or not.

IsBackupMedia 

Boolean

 

True or False. Depending on whether you configure the delivery of backup media or not.

IsDownloadInsuranceService 

Boolean

 

True or False. Depending on whether you enable the Download Insurance Service or not, for a product for which you configure a product file.

IsInstantDeliveryThankYouPage 

Boolean

 

True or False. Depending on whether you enable instant delivery in the Thank You page or not.

IsDisplayInPartnersCPanel 

Boolean

 

True or False. Depending on whether you share access to the product file with your channel partners or not.

CodeList 

Object (can be NULL)

 

Details below.

BackupMedia 

Object (can be NULL)

 

Details below.

ProductFile

Object (can be NULL)

 

Details below.

AdditionalInformationByEmail 

String (can be NULL)

 

The text you set up in the Additional fulfillment information - by email area.

AdditionalInformationEmailTranslations 

Object (can be NULL)

 

Array of localized Additional fulfillment information - by email texts.

AdditionalThankYouPage 

String (can be NULL)

 

The text you set up in the Additional fulfillment information - "Thank you" page area.

AdditionalThankYouPageTranslations 

Array (can be NULL)

 

Array of localized Additional fulfillment information - "Thank you" page texts.

 

CodeList 

Object (can be NULL)

Code 

String

 

The unique code list identifier.

Name 

String

 

Name of the code list.

Type 

String

 

Code list type:

  • STATIC
  • DYNAMIC

 

BackupMedia 

Object (can be NULL)

Code 

String

 

The unique backup media identifier.

Name 

String

 

Name of the backup CD/DVD.

Type 

String

 

Media type:

  • CD

 

ProductFile

Object (can be NULL)

Code 

String

 

Unique product file identifier.

Name 

String

 

Display name.

File 

String

 

Name of the product file.

Version 

String

 

File version.

Size

String

 

File size.

Type 

String

 

File type.

LastUpdate 

String

 

YYYY-MM-DD HH-MM-SS. Date time stamp when you last updated the file.

 

 

How do I add custom categories for affiliates

Add and manage multiple, custom categories for standalone affiliates or for batches of accounts, and use classifications to filter recipients of newsletter campaigns.

Requirements

This functionality is available only for active affiliate accounts from the 2Checkout Affiliate Network.

Important: Use UTF-8 character encoding when creating and saving the CSV file with custom categories for your affiliates.

How do I add custom categories and assign affiliates to them?

  1. Navigate to Active Relationships under Relationships for the Affiliate network.
  2. Click Add categories.
  3. Download a list of all your active affiliates as a Comma Separated Values (CSV) file.
  4. Fill in one or multiple categories under the Categories header. Example:

Not editable

Editable

IdAffiliate

CompanyName

Homepage

Categories

12344

Affiliate

Affiliate.com

Premium,Europe,XaaS

Important: Use UTF-8 character encoding.

Note: The import process takes into account only data marked as editable in the table above. 2Checkout uses the remaining information to identify affiliates and does not import any changes you make to the values marked as not editable.

Best practice: When assigning an affiliate to multiple categories, make sure the CSV file includes inverted commas ("") to mark the lists as a single value:

  • IdAffiliate,CompanyName,Homepage,Categories
  • 1234,Affiliate,Affiliate.com,"Premium,Europe,XaaS"
  1. Once you filled in custom categories in your CSV file, import it into the 2Checkout system:
  1. 2Checkout assigns the custom categories to your affiliates. You can access them:
    • By viewing the details page for standalone affiliate.
    • By re-downloading the list of active affiliates following the steps above. The CSV file contains all custom categories you add to affiliates.

How do I manage/delete custom categories or unassigned affiliates?

  1. Re-download the list of active affiliates following the steps above. The CSV file contains all custom categories you add to affiliates.
  2. You can modify existing categories or add new ones and re-upload the resulting file. Important: Use UTF-8 character encoding.
  3. To unassign affiliates from certain categories, simply delete the categories and re-import the file.

Can I manage custom categories individually?

  1. View the details page for standalone affiliate.
  2. Click the red X to delete a category.
  3. Use the add category field to add new categories. Don't forget to save any of the changes you make and separate multiple values with commas (,).

How do I target specific affiliates when I send out newsletters?

  1. Navigate to the Affiliate Newsletter Management area.
  2. Select one or multiple categories of affiliates who will receive a newsletter from the Category field under Compose Newsletter. All custom categories you add into 2Checkout are available under this filter.

2Checkout sends out your newsletter only to affiliates assigned to the custom categories you select.

Set SKU codes

Overview

Use the setSku method to create a valid combination of elements (code) for a specific product. 

In case there is an active SKU schema available for that Product Code and Pricing Configuration Code, when setting new SKUs the entire existing schema will be overwritten with the new values. The same validations that are applied to the CSV file import in the Merchant Control Panel are applicable to the API as well.

Product SKUs created via API will also be available in the Merchant Control Panel for manual update (Dashboard → Setup → Products → Edit product → Information → SKU Manager (SKU list Tab).

Request Example

<?php

require ('PATH_TO_AUTH');

$product = new \stdClass();
$product->ProductCode = "6B3CB17DDA_COPY1";

$skuPricingOption1 = new \stdClass();
$skuPricingOption1->Code = "E684EC99B0";

$skuDetail1 = new \stdClass();
$skuDetail1->ProductSKU = "Product_Test_SKU_001022";
$skuDetail1->Currency = "USD";
$skuDetail1->FromQty = 1;
$skuDetail1->ToQty = 3
$skuDetail1->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 1";
$skuGroupOption->Value = "option_code_1";

$skuGroup->Options = [$skuGroupOption];

$skuDetail1->Groups = [$skuGroup];
$skuDetail1->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrlXauuZOojh8cww==";

$skuDetail2 = new \stdClass();
$skuDetail2->ProductSKU = "Product_Test_SKU_001023";
$skuDetail2->Currency = "USD";
$skuDetail2->FromQty = 1;
$skuDetail2->ToQty = 3
$skuDetail2->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 2";
$skuGroupOption->Value = "option_code_2";

$skuGroup->Options = [$skuGroupOption];

$skuDetail2->Groups = [$skuGroup];
$skuDetail2->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrmXauuZOojjccxw==";

$skuPricingOption1->Details = [$skuDetail1, $skuDetail2];

$product->SkuPricingOptions = [$skuPricingOption1];


try {
    $skuOutput = $client->setSku($sessionID, [$product]);
} catch (SoapFault $e) {
    echo "setSku: " . $e->getMessage();
    exit;
}

var_dump("setSku", $skuOutput);



Response Example

class stdClass#201 (2) {
  public $Results =>
  class stdClass#202 (1) {
    public $0 =>
    class stdClass#203 (2) {
      public $ProductCode =>
      string(16) "6B3CB17DDA_COPY1"
      public $PricingConfigurationCode =>
      string(10) "E684EC99B0"
    }
  }
  public $Errors =>
  class stdClass#204 (0) {
  }
}

 

Retrieve shipping fees

Overview

Use the getShippingFees method to extract information about the shipping fees you defined for your account.

Parameters

Parameters Type/Description

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Response

Parameters Type/Description

ShippingFees

Array of objects

<?php

require ('PATH_TO_AUTH');

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

?>

Retrieve a subscription

Overview

Extract information on a single subscription. Use the getSubscription method to retrieve details about a subscription.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

subscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

Response

Parameters Type/Description

Subscription

Object

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Delete customer credit card

Overview

Use the removeCCFromCustomer method via SOAP API 6.0 to delete/unlink a customer's credit card information from the myAccount platform.

Request parameters

Parameter Type Required/Optional Description
CustomerReference String Required Internal 2Checkout customer reference or your customer identifier.
TransientToken String Required Transient Token for the card can be found in getCustomerInfoBySSOToken.

Response

# all good and was deleted
{
    "Deleted": true
}
# no and the delete failed with reasons
{
    "Deleted": false,
    "Subscriptions" [
        {
            "SubscriptionReference": "ABCF122132",
            "Error": {
                "error_code": "MY_ERROR_CODE_1",
                "message": ".... credit card was not deleted due to ..."
            }
        },
        {
            "SubscriptionReference": "DKHGTR12312",
            "Error": {
                "error_code": "MY_ERROR_CODE_2",
                "message": ".... credit card was not deleted due to ..."
            }
        },
        {
            "SubscriptionReference": "KHSTT1213",
            "Error": {
                "error_code": "MY_ERROR_CODE_3",
                "message": ".... credit card was not deleted due to ..."
            }
        }
    ]
}

Request sample

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'unlinkCustomerCreditCard';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD =
        <<<json
    {
        "CustomerReference" : "someref",
        "TransientToken" : "sometoken"
    }
json;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }
        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url.'?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode).$merchantCode.strlen($date).$date;
        $hash = hash_hmac('md5', $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');

        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    echo $ex->xdebug_message;
    var_dump($ex);
}

Retrieve subscription

Overview

Extract information on a single subscription. Use the getSubscription method to retrieve details about a subscription.

Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

subscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

Response

Parameters Type/Description

Subscription

Object

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

try {
    $subscriptionInfo = $client->getSubscription($sessionID, $subscriptionReference);
}
catch (SoapFault $e) {
    echo "subscriptionInfo: " . $e->getMessage();
    exit;
}
var_dump("subscriptionInfo", $subscriptionInfo);

Product

Overview

Use the Product object to create, update and retrieve subscription plans/products for your account. Use 2Checkout's API and control the following product attributes:

  • Product information
  • Pricing
  • Subscription plan settings and renewal configuration
  • Subscription plan recurring billing
  • Fulfillment
  • Shipping classes
  • Localization 

Parameters

Use the parameters below to add new products into your 2Checkout catalog.

Parameters Type/Description

Product

 

Object/Required

Product details.

ProductCode

String/Required

 

The product code that you can define for each of your offerings. Needs to be unique.

ProductType

String/Optional

 

REGULAR or BUNDLE

Defaults to REGULAR.

ProductName

String/Required

 

The name of the product

ProductVersion

String/Optional

 

The product version number

PurchaseMultipleUnits Boolean/Optional
 

Possible values:

  • TRUE - customers can purchase multiple units of this product.
  • FALSE - customers can purchase only one unit at a time.

 

The default value is TRUE.

ShippingClass

Object/Optional

 

Existing shipping class object with the structure detailed below.

 

Name

String

 

 

The name of the shipping class

 

Amount

Decimal

 

 

The shipping costs

 

Currency

String

 

 

The currency ISO code used for shipping costs - ISO 4217.

 

ApplyTo

String

 

 

Possible values:

• PRODUCT

• ORDER

 

Type

Possible values:

• FIXED

• PERCENT

GiftOption

Boolean / Optional

 

True or false depending on whether the product can be gifted or not.

ShortDescription

String / Optional

 

The product's short description

LongDescription

String / Optional

 

The product's long description

SystemRequirements

String / Optional

 

System requirements

ProductCategory

String / Optional

 

Product category

Platforms

Array of Platform objects / Optional

 

Array of objects detailing the platforms supported by the application. Details below.

 

PlatformName

String

 

 

The label of the platform per the product configuration.

 

Category

String

 

 

Platform category per product configuration. 

ProductImages

Array of Image objects / Optional

 

Image object. Details below. Read-only.

 

Default

Boolean

 

 

True or False depending on whether you set the image stored at the address in the URL parameter as default or not.

 

URL

String

 

 

The location of the image on the 2Checkout system.

TrialUrl

String (anyURI) / Optional

 

The URL from where shoppers can download trial software.

TrialDescription

String / Optional

 

Descriptive text entered for trials.

Enabled

Boolean / Optional

 

True/false depending on whether the products are active or disabled. When empty, 2Checkout marks the product as disabled.  

AdditionalFields

Array of AdditionalFieldAssigned objects / Optional

 

Array of existing additional fields assigned to products. Details below.

 

Label

String

 

 

The name of the additional field assigned to a product.

 

Code

String

 

 

The code of the additional field assigned to a product.

 

Enabled

Boolean

 

 

True or false depending on whether the assigned product field is enabled or not.

 

Required

Boolean

 

 

True or false depending on whether the assigned product field is required or not.

 

URLParameter

String

 

 

The value of the system generated URL parameter for the product field that can be used in Buy Links.

Translations

Array of ProductTranslation objects / Optional

 

Details below.

 

LongDescription

String

 

 

The translated long description in the language corresponding to the Translation object.

 

TrialUrl

String

 

 

The trial URL for users speaking the language corresponding to the Translation object.

 

TrialDescription

String

 

 

 

 

SystemRequirements

String

 

 

Localized system requirements.

 

Name

String

 

 

Localized product name.

 

Description

String

 

 

Localized product short description.

 

Language

String

 

 

ISO 639-1 two-letter code.

PricingConfigurations

Array of PricingConfiguration objects/Required

 

Details below. 2Checkout creates pricing configurations during the process when you add a product.

 

Name

String

 

 

Pricing configuration name

 

Code

String

 

 

System-generated identifier.

 

Default

boolean

 

 

True for the default pricing configuration

 

BillingCountries

Array of strings

 

 

ISO codes of the countries assigned to the pricing configuration.

Empty unless specific countries are assigned to a pricing configuration.

 

PricingSchema

String

 

 

DYNAMIC – With a base price

FLAT – Without a base price

 

PriceType

String

 

 

Possible values:  NET / GROSS

 

DefaultCurrency

String

 

 

The ISO code of the default currency for the pricing configuration

 

Prices

Object

 

 

Details below.

 

Regular

Array of objects

 

 

Details below.

 

Amount

Int

 

 

The price of the product.

 

Currency

String

 

 

ISO code of the currency for the product price.

 

MinQuantity

Int

 

 

The minimum quantity of volume discounts. Default is 1.

 

MaxQuantity

Int

 

 

The maximum quantity of volume discounts. Default is 99999.

 

OptionCodes

Array of objects

 

 

Details below.

 

Code

String

 

 

Price option identifier.

 

Options

Array of strings

 

 

The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.

 

Renewal

Array of objects

 

 

Details below.

 

Amount

Int

 

 

The price of the product.

 

Currency

String

 

 

ISO code of the currency for the product price.

 

MinQuantity

Int

 

 

The minimum quantity of volume discounts. Default is 1.

 

MaxQuantity

Int

 

 

The maximum quantity of volume discounts. Default is 99999.

 

OptionCodes

Array of PriceOptionCode objects

 

 

Details below.

 

Code

String

 

 

Price option identifier.

 

Options

Array of strings

 

 

The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.

 

PriceOptions

Array of AssignedPriceOptionGroup objects

 

 

Details below.

 

Code

String

 

 

System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.

 

Required

Boolean

 

 

True or False depending on whether you want to make it mandatory for shoppers to select the price option during the puyrchase process.

BundleProducts

Array of BundleProductCode objects / Optional

 

 

Details below.

 

ProductId

String

 

 

Unique, system-generated product ID.

 

ProductCode

String

 

 

Editable product code that you control.

Fulfillment

String / Required

 

BY_2CHECKOUT

NO_DELIVERY – The 2Checkout system finalizes orders immediately after it receives payment confirmation.

BY_VENDOR – you are responsible for delivering/fulfilling orders

Prices

Array of Price objects / Required

 

Use this object only when Pricing Configurations are not available for your account. Details below.

 

Amount

Int

 

 

The price of the product.

 

Currency

String

 

 

ISO code of the currency for the product price.

 

MinQuantity

Int

 

 

The minimum quantity of volume discounts. Default is 1.

 

MaxQuantity

Int

 

 

The maximum quantity of volume discounts. Default is 99999.

 

OptionCodes

Array of objects

 

 

Details below.

 

Code

String

 

 

Price option identifier.

 

Options

Array of strings

 

 

The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.

GeneratesSubscription

Boolean / Required

 

TRUE or FALSE depending on whether you set the product to generate subscriptions or not.

 

NULL for bundles for which you set the following subscription management option: “Use the subscription settings of each product in the bundle”

SubscriptionInformation

ProductSubscriptionInformation Object / Optional

 

Details below. NULL for bundles which you set to use the renewal settings of child products and not of the parent bundle.

 

DeprecatedProducts

Array

 

 

Deprecated products.

 

BundleRenewalManagement String

 

 

Possible values:

  • GLOBAL
  • INDIVIDUAL

Can be NULL.

 

BillingCycle

String

 

 

The number of subscription billing cycle units (months or days).  Possible values:

  • 0 (zero represents a one-time fee)

Days

  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14

 

Months

  • 1
  • 2
  • 3
  • 6
  • 12
  • 15
  • 18
  • 24
  • 36 (max)

 

BillingCycleUnits

String

 

 

The units of the billing cycle:

  • M - months

D - days

 

IsOneTimeFee

Boolean

 

 

True or False depending on whether the subscription is evergreen or not.

 

ContractPeriod

Object

 

 

Details below.

 

Period

Int

 

 

The contract period in months or days. -1 for unlimited contracts.

 

PeriodUnits

String

 

 

The contract period units

days | months

 

IsUnlimited

Boolean

 

 

This flag is true if the contract is for an unlimited period

 

Action

String

 

 

The action performed after the subscription expires.

Possible values CANCEL | RESTART

 

EmailsDuringContract Boolean

 

 

True or False depending on whether you suppress renewal notification emails throughout the duration of the contract or not.

 

UsageBilling

Int

 

 

The usage billing interval must be smaller than or equal to the grace period.

 

Interval of time within the grace period, when the 2Checkout system attempts to automatically charge customers for recurring costs and additional metered usage fees (in arrears). 2Checkout renews subscriptions only after subscribers make all outstanding payments per the renewal settings (from the expiration or the renewal date). If automatic renewal and usage charges fail, subscriptions can be manually renewed only by the end of the grace period, after which they expire.

 

Can be NULL.

 

GracePeriod

Object

 

Type

String

 

 

CUSTOM – you configured grace period setting at product level.

GLOBAL – global grace period settings apply.

 

Period

String

 

 

Number of days set for the grace period.

 

PeriodUnits

String

 

 

D - Days.

 

IsUnlimited

Boolean

 

 

TRUE or FALSE depending on whether you set the grace period to unlimited or not.

 

RenewalEmails

Object

 

 

Details below. Can be NULL. Available only in Product API 2.5 and later.

 

Type 

String

 

 

GLOBAL - Send emails according to the global renewal notification settings.

CUSTOM – per product renewal notification settings

 

Settings

Object (can be NULL)

 

 

Details below.

 

ManualRenewal

Object (can be NULL)

 

 

Details below.

 

Before30Days 

Boolean

 

 

True or False.

 

Before15Days 

Boolean

 

 

True or False.

 

Before7Days 

Boolean

 

 

True or False.

 

Before1Day 

Boolean

 

 

True or False.

 

OnExpirationDate 

Boolean

 

 

True or False.

 

After5Days

Boolean

 

 

True or False.

 

After15Days 

Boolean

 

 

True or False.

 

AutomaticRenewal

Object (can be NULL)

 

 

Details below.

 

Before30Days 

Boolean

 

 

True or False.

 

Before15Days 

Boolean

 

 

True or False.

 

Before7Days 

Boolean

 

 

True or False.

 

Before1Day 

Boolean

 

 

True or False.

 

OnExpirationDate 

Boolean

 

 

True or False.

 

After5Days

Boolean

 

 

True or False.

 

After15Days 

Boolean

 

 

True or False.

FulfillmentInformation

Object / Optional

 

Details below. Can be NULL. Available only in Product API 2.5 and later.

 

IsStartAfterFulfillment 

Boolean

 

 

True or False. Depending on whether you want the subscription lifetime to start afther the completion of the fulfillment process or not.

 

IsElectronicCode 

Boolean

 

 

True or False. Depending on whether you configure the delivery of keys/codes for the product or not.

 

IsDownloadLink 

Boolean

 

 

True or False. Depending on whether you configure the delivery of a product file or not.

 

IsBackupMedia 

Boolean

 

 

True or False. Depending on whether you configure the delivery of backup media or not.

 

IsDownloadInsuranceService 

Boolean

 

 

True or False. Depending on whether you enable the Download Insurance Service or not, for a product for which you configure a product file.

 

IsInstantDeliveryThankYouPage 

Boolean

 

 

True or False. Depending on whether you enable instant delivery in the Thank You page or not.

 

IsDisplayInPartnersCPanel 

Boolean

 

 

True or False. Depending on whether you share access to the product file with your channel partners or not.

  ReturnMethod Object
    Information on the customer redirect method after a successful purchase.
            Type String
   

Possible values:

  • DIRECT_RETURN
  • HEADER_REDIRECT
  • HTML_LINK
            URL String
    Website to which customers are redirected after a successful purchase. Example: "http://mySuccessURL.com"

 

CodeList 

Object (can be NULL)

 

 

Details below.

 

Code 

String

 

 

The unique code list identifier.

 

Name 

String

 

 

Name of the code list.

 

Type 

String

 

 

Code list type:

  • STATIC

  • DYNAMIC

 

BackupMedia 

Object (can be NULL)

 

 

Details below.

 

Code 

String

 

 

The unique backup media identifier.

 

Name 

String

 

 

Name of the backup CD/DVD.

 

Type 

String

 

 

Media type: CD

 

ProductFile

Object (can be NULL)

 

 

Details below.

 

Code 

String

 

 

Unique product file identifier.

 

Name 

String

 

 

Display name.

 

File 

String

 

 

Name of the product file.

 

Version 

String

 

 

File version.

 

Size

String

 

 

File size.

 

Type 

String

 

 

File type.

 

LastUpdate 

String

 

 

YYYY-MM-DD HH-MM-SS. Date time stamp when you last updated the file.

 

AdditionalInformationByEmail 

String (can be NULL)

 

 

The text you set up in the Additional fulfillment information - by email area.

 

AdditionalInformationEmailTranslations 

Object (can be NULL)

 

 

Array of localized Additional fulfillment information - by email texts.

 

AdditionalThankYouPage 

String (can be NULL)

 

 

The text you set up in the Additional fulfillment information - "Thank you" page area.

 

AdditionalThankYouPageTranslations 

Array (can be NULL)

 

 

Array of localized Additional fulfillment information - "Thank you" page texts.

 

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo