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

Response

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));

Overview

Use the getInstallments method to retrieve information about the number of installments available for a specific selection of product/services.

Supported payment methods

Credit/Debit cards: local Visa and MasterCard Brazilian cards.​

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');
 
$Order = new stdClass();
$Order->RefNo = null;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = null;
$Order->Source = null;
$Order->AffiliateId = null;
$Order->CustomerReference = null;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1; 
$Order->Items[0]->PriceOptions = null;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = null;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = null;

$Order->DeliveryDetails = null;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

try {
    $OrderInstallments = $client->getInstallments($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "Order_Installments: " . $e->getMessage();
    exit;
}
var_dump("Order_Installments", $OrderInstallments);

Overview

Use the disableRecurringBilling method to disable recurring billing for a subscription. When you disable recurring billing, the subscription status doesn’t change. Users continue to use subscriptions with recurring billing disabled until they expire, and 2Checkout provides them with the option to renew their subscription through manual payments.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.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.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$SubscriptionReferenceTest = '48F5AC7011';
try {
    $disabledRecurringBilling = $client->disableRecurringBilling($sessionID, $SubscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "disabledRecurringBilling: " . $e->getMessage();
    exit;
}
var_dump("disabledRecurringBilling", $disabledRecurringBilling);

Overview

Use the getShippingFee method to extract information about a specific shipping fee configuration you defined for your account.

Parameters

Response

Request

<?php
require ('PATH_TO_AUTH');

$shippingCode= "YOUR_SHIPPING_CODE";

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

?>

Overview

An order is the most common way to collect payment from your shoppers and is at the heart of the 2Checkout platform.

The Order Object

While the full order object can be very extensive (the full object structure can be found here), the minimum information needed for placing an order are the billing details, the payment details, and the order items.

The Billing Details

The billing details are mandatory information when placing an order, and they are used in the processing of an order, as they appear on the invoice of the order. 

The payment details

The payment details are used in processing the order and contain information specific for the payment method used. For example, for a Credit Card payment, this is where you would be sending the Card Holder Name, Card Number, Card Type, Expiration Date, and CVV.

Due to the wide range of payment methods supported in the 2Checkout API, the payment details object can differ extensively between payment methods. 

The various payment details objects will be explained and detailed in the Payments flow article. 

The items  

The items object required when placing an order is an array of item objects. The items are the products that the shopper is buying when placing the order. 

The 2Checkout API supports either catalog or dynamic products. Mixed orders, with both catalog and dynamic products is not supported.

For each product in the item list, the quantity is optional and can be left out. In this case, the quantity will be set to 1 by default.  

Catalog products

Catalog products are products that you have defined in your product catalog, either via your Merchant Control Panel or via API. 

The minimum information needed in order to place an order with catalog products, via API, is the alphanumeric product code (not to be confused with the product id). 

The JSON for this would look like:

"Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ]

The full list of fields available for catalog products can be found here.

The full JSON for an order with catalog products would look like:

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"TEST",
      "Currency":"USD",
      "PaymentMethod":{
         "CardNumber":"4111111111111111",
         "CardType":"VISA",
         "ExpirationYear":"2023",
         "ExpirationMonth":"12",
         "HolderName":"Red Doe",
         "CCID":"123",
         "Vendor3DSReturnURL":"http:\/\/yoursuccessurl.com",
         "Vendor3DSCancelURL":"http:\/\/yourcancelurl.com"
      },
      "CustomerIP":"10.10.10.10"
   }
}

Dynamic products

Dynamic products are products generated on the fly when placing orders.

This functionality is available only for merchants on the 2Sell and 2Subscribe accounts (PSP business model), for orders that are placed both through ConvertPlus/InLine ordering engines and API calls.

The minimum information needed in order to place an order with dynamic products, via API is:

The items in the JSON body of the request would look like:

 "Items":[
      {
         "Code":null,
         "IsDynamic":true,
         "PurchaseType":"PRODUCT",
         "Tangible":false,
         "Name":"My Dynamic Product",
         "Quantity":1,
         "Price":{
            "Amount":1,
            "Type":"CUSTOM"
         }
      }
   ]

The full list of fields available for dynamic products can be found here.

The full JSON for an order with catalog products would look like:

{
   "Items":[
      {
         "Code":null,
         "IsDynamic":true,
         "PurchaseType":"PRODUCT",
         "Tangible":false,
         "Name":"My Dynamic Product",
         "Quantity":1,
         "Price":{
            "Amount":1,
            "Type":"CUSTOM"
         }
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"TEST",
      "Currency":"USD",
      "CustomerIP":"10.10.10.10",
      "PaymentMethod":{
         "CardNumber":"4111111111111111",
         "CardType":"VISA",
         "ExpirationYear":"2020",
         "ExpirationMonth":"12",
         "CCID":"123",
         "HolderName":"John Doe",
         "Vendor3DSReturnURL":"https:\/\/example.com",
         "Vendor3DSCancelURL":"https:\/\/example.com"
      }
   }
}

Extending the order object

There's a wide range of use cases that can be supported by the order object, such as, but not limited to, adding customer information on an order, affiliate information, promotions, or additional fields.

In order to add this information, a new object with the corresponding name must be added at the root level of the order object, with the appropriate structure. 

For example, in order to add delivery details that were collected from the shopper, a new object named “DeliveryDetails” needs to be added in the order object (on the same level as the "Billing Details"). 

The Delivery Details object has the same structure as the Billing Details object. 

Let’s assume we also want to add some additional information to the order. This could be done by adding a new Additional Fields array of Additional Field objects. 

The additional field object contains three fields:

• a code (the internal code in the merchant's systems)
• a text (that could be displayed to the shoppers)
• a value (the actual value of the additional field for that order)

Adding delivery details and additional fields to an order would look like this:

 "DeliveryDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "Address1":"Example Street 42",
      "Address2":"2nd line of the address",
      "City":"San Francisco",
      "State":"California",
      "CountryCode":"US",
      "Phone":"555-5555",
      "Email":"example@email.com",
      "Zip":"90210"
   },
   "AdditionalFields":[
      {
         "Code":"ABC1234",
         "Text":"Additional field text",
         "Value":"Additional field value"
      }
   ]

Integration use cases

There are several test credit cards (available here) that can be used to test your integration as described in these steps:

1. Create a test product in the Merchant Control Panel.
2. Using the product code of the newly created product, place an order based on the request example above, and check that an order is placed.
3. Starting from the minimum requirements for a catalog product order, extend the information you send to 2Checkout and check on every new parameter that the order is placed successfully.
4. If you need to create products on the fly via dynamic products, first of all, make sure your account supports dynamic products (available only for 2Sell and 2Subscribe accounts, if you handle your own tax and invoice management.).
5. Starting from the minimum requirements for a dynamic product order, start adding all the information you need to send to 2Checkout while checking that the order is successfully placed.
6. Check that making a placeOrder API call returns an order object.
7. Once an order object is obtained via API, check the order in the Merchant Control Panel. Under Orders & customers → Order search, you can filter by the order reference of the newly created order (the RefNo property).

Overview

Use the disableRecurringBilling method to disable recurring billing for a subscription. When you disable recurring billing, the subscription status doesn’t change. Users continue to use subscriptions with recurring billing disabled until they expire, and 2Checkout provides them with the option to renew their subscription through manual payments.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/3.0/?wsdl", array(
    'location' => $host . "/soap/3.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.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.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$SubscriptionReferenceTest = '48F5AC7011';
try {
    $disabledRecurringBilling = $client->disableRecurringBilling($sessionID, $SubscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "disabledRecurringBilling: " . $e->getMessage();
    exit;
}
var_dump("disabledRecurringBilling", $disabledRecurringBilling);

Overview

Use the setExternalRef method in conjunction with setSubscriptionUpgrade.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$externalReference = 'YOUR_EXTERNAL_REFERENCE';

try {
    $extRef = $client->setExternalRef($sessionID, $externalReference);
}
catch (SoapFault $e) {
    echo "extRef: " . $e->getMessage();
    exit;
}
var_dump("extRef", $extRef);

Overview

Use the disableRecurringBilling method to disable recurring billing for a subscription. When you disable recurring billing, the subscription status doesn’t change. Users continue to use subscriptions with recurring billing disabled until they expire, and 2Checkout provides them with the option to renew their subscription through manual payments.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

try {
    $disabledRecurringBilling = $client->disableRecurringBilling($sessionID, $subscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "disabledRecurringBilling: " . $e->getMessage();
    exit;
}
var_dump("disabledRecurringBilling", $disabledRecurringBilling);

Overview

Use the getRenewalDetails method to retrieve information regarding subscription renewals based on 2Checkout Subscription References:

• Information on the  automatic renewal (recurring billing) status (enabled or disabled).
• The link that customers access to renew the subscription though a manual payment.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Overview

Learn how to tackle the common errors that may arise when issuing refunds via 2Checkout API.

Common error codes