Skip to main content

Assign a product group

Request

<?php

$host   = "https://api.avangate.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 = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.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;
}

$ProductCode = 'AAA4643116';
$Code = "5C08A761E1";

try {
    $AssignedProductGroup = $client->assignProductGroup($sessionID, $ProductCode, $Code);
}

catch (SoapFault $e) {
    echo "AssignedProductGroup: " . $e->getMessage();
    exit;
}

var_dump("AssignedProductGroup", $AssignedProductGroup);

?>

Save prices

Overview

Use the savePrices method to update product prices for a specific pricing configuration.

Parameters

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.

Prices

Array of BasicPrice objects

 

Details below.

Quantities

QuantityInterval object

 

Details below.

PriceOptions

Array of PriceOptionsAssigned objects

 

Details below. Required for FLAT (without base price) pricing configurations. Is NULL for DYNAMIC (with base price) pricing configurations.

PricingConfig

Required (PricingConfigurationIdentifier object)

 

System-generated unique pricing configuration code.

type

Require (string)

• REGULAR

• RENEWAL

 

BasicPrice

Object

Currency

String

 

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

Amount

Decimal

 

Basic price.

 

QuantityInterval

Object

MinQuantity

Int

 

The minimum quantity of volume discounts. Default is 1.

MaxQuantity

Int

 

The maximum quantity of volume discounts. Default is 99999.

 

PriceOptionsAssigned

Object

Code

String

 

Price option identifier.

Options

String

 

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

 

PricingConfigurationIdentifier

Object

ProductCode

String

 

The unique product code that you control.

Country

String

 

The country assigned to the pricing configuration you’re editing.

Response

bool(true)

Request

<?php

$host   = "https://api.avangate.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 = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key          = "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;
}

$Prices                     = array();
$Prices[0]                  = new stdClass();
$Prices[0]->Currency        = 'USD';
$Prices[0]->Amount          = 999.99;
$Prices[1]                  = new stdClass();
$Prices[1]->Currency        = 'EUR';
$Prices[1]->Amount          = 111.99;
$Quantities                 = new stdClass();
$Quantities->MinQuantity    = 1;
$Quantities->MaxQuantity    = 99999;
$PriceOptions               = null;
/*
$PriceOptions = array();
$PriceOptions[0] = new stdClass();
$PriceOptions[0]->Code = '04WCPNHWQ5';
$PriceOptions[0]->Options = array();
$PriceOptions[0]->Options[0] = 'loqmhwcpwk';
$PriceOptions[0]->Options[1] = 'n7332ux312';
$PriceOptions[1] = new stdClass();
$PriceOptions[1]->Code = '4CU1OVAGAA';
$PriceOptions[1]->Options = array();
$PriceOptions[1]->Options[0] = 'dvk7hv62jg';
$PriceOptions[1]->Options[1] = 'uf1svzaxcd';
*/
$PricingConfig              = new stdClass();
$PricingConfig->ProductCode = 'NewSubscriptionPlan_Code_12345';
$PricingConfig->Country     = null;
$type                       = 'REGULAR';

try {
    $NewPrice = $client->savePrices($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfig, $type);
}

catch (SoapFault $e) {
    echo "NewPrice: " . $e->getMessage();
    exit;
}

var_dump("NewPrice", $NewPrice);


?>

 

Update product group

Overview

Use the updateProductGroup method to create a new product group for your account.

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.

ProductGroup

Required (object)

 

Use this object to update product groups.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = 'DBA13A4268';
$ProductGroup->TemplateName = 'Default Template'; // the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = false;

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

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

Retrieve order information

Overview

Use this method to extract information about orders in the Avangate platform.

Parameters

Parameters Type/Description
sessionID String
  Session identifier string, output of the Login method. An exception is thrown if the values are incorrect.
refNo String
  Order reference number of an existing approved/paid order.

Response

Parameters Type/Description
Order Object

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication

$refNo = 'YOUR_ORDER_REFERENCE'

try {
    $getOrder = $client->getOrder($sessionID, $refNo);
} catch (SoapFault $e) {
    echo "getOrder: " . $e->getMessage() ;
}
var_dump ($getOrder);

Delete customer credit card

Overview

Use the removeCCFromCustomer method via JSON-RPC 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/rpc/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
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;

    public function execute()
    {
        $this->login(Configuration::URL);
        $this->call(Configuration::URL, $this->generateRequestPayload(), Configuration::ACTION);
    }

    private function login(string $url)
    {
        $payload = $this->generateAuthPayload();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }

    private function generateAuthPayload(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode).$merchantCode.strlen($date).$date;
        $hash = hash_hmac('md5', $string, $key);

        return compact('merchantCode', 'date', 'hash');
    }

    private function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);
        $curl = curl_init($url);
        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', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if (empty($response)) {
            die('Server unavailable');
        }
        echo $response.'</br>';

        return json_decode($response, true);;
    }

    private function generateRequestPayload(): array
    {
        if (empty($this->sessionId)) {
            throw new LogicException('Login should be called first');
        }

        $requestPayload = (is_string(Configuration::PAYLOAD))
            ? json_decode(Configuration::PAYLOAD,
            true) : Configuration::PAYLOAD;

        $payload = array_merge(
            (array)$this->sessionId,
            (array)Configuration::ADDITIONAL_OPTIONS
        );
        $payload[] = $requestPayload;
        array_filter($payload);

        return $payload;
    }
}

$client = new Client();
$result = $client->execute();
var_dump($result);

Custom order search export fields and templates (XML, CSV, XLS)

Overview

Custom order export template capabilities provide you with complete control over order data from the 2Checkout system. Order data portability through customizable reports is available for both eStore and Channel Manager (Partners), enabling you to build reports of the orders placed by shoppers buying directly from you as well as the sales made to your partners.

The 2Checkout order data portability capabilities enable you to export sales information using: XML (Extensible Markup Language - eStore orders only), CSV (comma-separated values) or XLS (Excel) files.

This feature enables you to choose the column headers of the order search report which can be exported as a CSV (comma-separated values) or an XLS (Excel) file, or the XML elements when the export is an XML file. Order data will be included or excluded from the report based on whether the column headers/XML elements governing specific types of information are present or absent in the order report template used for export. Essentially, when a column header/XML element is present, its column will be populated with the corresponding order or product data, provided that it exists in the 2Checkout system.

Benefits

  1. Streamlined order data portability;
  2. Granular control over you order information;
  3. Complete personalization of the orders reporting tool

Availability

Custom order export templates are available by default to all 2Checkout merchants.

Access custom order export templates

eStore orders

  1. Go to Orders &customers -> Order search.
  2. Select the eStore orders tab.
  3. Run a search to identify the orders you're looking for.
  4. Click Export.
  5. Click Edit templates.
Order status in search export Order status in control panel Approve status Notes
COMPLETE Finished Finished The order was fulfilled.
AUTHRECEIVED Pending approval Pending approval The order has yet to be approved.
In progress / Processing In progress The order was approved.
Suspect Suspect Suspect order - potential fraud.
REVERSED Canceled Canceled The order was canceled before fulfillment.
PENDING Unfinished Unfinished The order has yet to be approved.
Suspect Suspect Suspect order - potential fraud.
TEST TEST TEST Test order.
TOTAL REFUND Refunded Refunded Full refund.
PARTIAL REFUND Refunded Refunded Partial refund.
CHARGEBACK Refunded Refunded Full refund as a result of a lost chargeback.

Channel Manager

  1. Go to Orders &customers -> Order search.
  2. Click the Partner orders tab.
  3. Run a search to identify the orders you're looking for.
  4. Click Export.
  5. Click Edit templates.

You can export Channel Manager/Partner order data only as CSV and XLS files.

Note: Order data available is adapted to the report type you're trying to customize and export. As such, some shopper-specific information will not be featured in the Channel Manager report, and similarly, partner-related details will not be included in the eStore report.

Default templates

Three templates are available by default as read-only. You cannot edit or delete the following:

  • 2Checkout Simple Export Template
  • 2Checkout Full Options Template
  • 2Checkout Chargeback Orders Template

You can build your own custom template using 2Checkout Simple Export Template and 2Checkout Full Options Template by clicking the Edit button. Any changes you make will be saved as a new template, without impacting the default items.

Create a custom template

  1. Create a new customer template by:
    • Clicking the Add new template button and completely customizing the template;
    • Clicking edit for 2Checkout Simple Export Template and 2Checkout Full Options Template, and customizing the settings of the default templates.
  2. Provide a unique name for the template to make it easily distinguishable from similar templates.
  3. Select the desired elements from the Additional template elements area either by checking entire categories (in bulk) or standalone items (one by one), and move them to the Template elements area to the right by using the action buttons. The selected items will act as the column headers for the CSV and XLS files, and as the XML elements for the XML export file. Once added to the Template elements headers area, the elements will also be featured in your custom template.
  4. You can further personalize the template by:
    • Changing the order of the elements in the custom template. To do this simply click on an item added to the Template elements, hold the mouse button pressed, and drag and drop the item in a new position. Note: This action will impact only the CSV and XLS exports. The order of the elements in the XML export file is predefined and will not be changed.
    • Renaming the template elements. Click on the Rename column icon to access a dialog box enabling you to enter a new label that might be better suited to your needs. Changing the name of the elements won't affect the export functionality. Note: This action will impact XML, CSV and XLS exports.
    • Remove elements from the custom template. You can remove elements from a custom template either one by one by clicking the Remove column icon, or in bulk, by multi-selecting items and clicking on the action button designed to place elements back under the Additional template elements area. Note: Removing elements from the custom template will delete any custom names you entered. You'll need to re-enter the custom label for an item that gets re-added to the custom template if previously removed. However, if you removed an element by mistake, and did not save the change, clicking Reset will restore it, complete with the custom label you provided. Note: Removing column headers from the custom template will delete any custom names you entered. You'll need to re-enter the custom label for an item that gets re-added to the custom template if previously removed. However, if you removed a column header by mistake, and did not save the change, clicking Reset will restore it, complete with the custom label you provided.
  5. Click Save to preserve the custom template, as well as any custom configurations that you introduced.

Use a custom export template

When exporting order search data, use the drop-down menu to select the item best suited to your needs from the Export Template menu featuring all default and custom export templates.

Set any template that you're using with predilection as the Default template, and it will be pre-selected as the Export Template option.

What happens when I click Reset?

Clicking the Reset button on a custom template restores it to the previously saved state discarding all modifications you made but did not save. Note: All unsaved changes will be lost.

Can I delete templates?

Yes. Click to edit the template you want to be removed, and hit the Delete button in the right-hand side corner of the screen. Note: Template removal actions cannot be undone.

Order search export CSV headers

 

CSV field label Explanation Data type DB Datatypes
Order      
Reference No Order reference identifier. A refund order will have the same Reference No as the initial order. int INT
Order status

Possible values:

  • COMPLETE
  • AUTHRECEIVED
  • REVERSED
  • PENDING
  • TEST
  • TOTAL REFUND
  • PARTIAL REFUND
  • CHARGEBACK
string VARCHAR(30)
Approval status

Possible values:

  • Finished
  • Pending approval
  • In progress
  • Canceled
  • Unfinished
  • TEST
  • Suspect
  • Refunded
string VARCHAR(30)
Order No Orders placed by your customers receive consecutive numbers. Order No can be null for unfinished orders. int INT
External Reference No An identifier that you can set for orders. string VARCHAR(38)
Original External Reference No The External Reference No values set for the initial orders when the subscriptions were first acquired. Available for subscription renewals. Not available in the default template. For bundled products, multiple reference numbers are separated using "|", as such: RefNo1| RefNo2. string VARCHAR(100)
Order Date The date when the order was placed. Datetime stamp is time zone sensitive. datetime (yyyy-mm-dd hh:ii:ss) DATETIME
Order Finish Date The date when the order was finished. Datetime stamp is time zone sensitive. datetime (yyyy-mm-dd hh:ii:ss) DATETIME
Pay Method

The name of the payment method used by the shopper:

  • Visa
  • MasterCard
  • Wire transfer
  • American Express
  • Diners Club
  • PayPal
  • And more.
string VARCHAR(30)
Gateway Response

The answer received from the payment processor. Possible values: Approved, error message, N/A (when this functionality is not available for your account).

 

A list with gateway responses is available here.

string VARCHAR(30)
Origin

Possible values:

Web - new acquisitions or manual renewal orders placed via Web

API - orders placed via API

Automatic Billing - orders renewed automatically by 2Checkout

Mobile - orders placed through Mobile devices

string VARCHAR(30)
Sale Source The URL used by customers to reach the shopping cart. Not available for partner orders. string VARCHAR(255)
Delivery Type

Product delivery type. Possible values:

  • Electronic
  • Physical
  • Electronic and physical
string VARCHAR(255)
Shipping date

Order shipment date. Orders for physical products that are not marked as shipped will appear as 'Not shipped'.

Orders for electronic products are displayed with 'N/A'.

string VARCHAR(255)
Original Sale Source Sale source (link source, the SRC parameter) values for the initial orders when the subscriptions were first acquired. Available for subscription renewals. Not available in the default template. For bundled products, multiple sale sources are separated using "|", as such: Source1| Source2. string VARCHAR(255)
EndUserIP Shopper IP. string: (127.0.0.1) VARCHAR(20)
Fulfillment information Activation keys delivered to customers. For bundled products, multiple product keys are separated using "|", as such: Key1| Key2. string VARCHAR(255)
Chargeback Status

The status of the chargeback dispute from the moment the report is generated.

Possible values:

OPEN = a chargeback was opened by a customer and the dispute continues to be unresolved.

WON = the dispute was won by you and no money was paid back to the customer.

LOST = the dispute was lost and the entire value of the order was reimbursed to the customer.

NONE = if a chargeback wasn't requested.

string VARCHAR(20)
Chargeback Reason

The reason why the chargeback was initiated. Possible values:

 

1. Order not fulfilled/not delivered: Customers claim that they did now receive the product they purchased or that they cannot access the service acquired.

2. Product(s) not as described/unfunctional: Customers claim that the product/subscription/service purchased does not work or functions differently than you advertised it would.

3. Duplicate order: Customers claim that they were charged twice when purchasing the same product.

4. Fraud/Order not recognized: Customers claim that they don't recognize the charge.

5. Agreed refund not processed: Customers have opened a chargeback dispute because the refund they agreed on with you failed to process.

6. New/renewal order not recognized: Customers have opened a chargeback dispute because the refund they agreed on with you failed to process.

7. Authorization problem: Customers claim that the payment authorization failed and are surprised to see that the charge went through.

8. Information request: The customer's bank requested details about a charge. This is a temporary status, which can be closed once customers recognize the charge, or result in a chargeback for one of the reasons listed above.

string VARCHAR(80)
Chargeback Reason Code

An identifier for the chargeback dispute reason from the 2Checkout system. Possible values:

  • MERCHANDISE_NOT_RECEIVED - Order not fulfilled/not delivered
  • NOT_AS_DESCRIBED - Product(s) not as described/nonfunctional
  • DUPLICATE_TRANSACTION - Duplicate order
  • FRAUD / NOT_RECOGNIZED - Fraud/Order not recognized
  • CREDIT_NOT_PROCESSED - Agreed refund not processed
  • NOT_RECOGNIZED - New/renewal order not recognized
  • AUTHORIZATION_PROBLEM - Authorization problem
  • INFO_REQUEST - Information request
  • UNKNOWN - Unknown
String VARCHAR(25)
Chargeback Request Date The date when the chargeback dispute was initiated. Datetime stamp is time zone sensitive. datetime (yyyy-mm-dd hh:ii:ss) DATETIME
Chargeback Close Date The date when the chargeback dispute was closed. Datetime stamp is time zone sensitive. datetime (yyyy-mm-dd hh:ii:ss DATETIME
Order Additional Fields

Information collected from customers during the ordering process via one or multiple per-order custom additional fields. The Order Additional Fields column will report data collected from shoppers according to the following format:

- for CSV and XLS: "Field Name: Value." When multiple additional fields are used for a single order, data reported will be separated using "|", as such: Field Name1: Value1| Field Name2: Value2.

This column will be filled only for the first line of that order (first product) in the export file.

For "CHECKBOX" additional fields, if the field was checked during the ordering process "CHECKED" value is showed in the export file. If the field was not checked, no information is displayed in the export.

- for XML: <Order_Additional_Fields> <Order_Additional_Field_Item> <Field_Label>Label1(the same as the Field text)</Field_Label>

<Field_Value>Value1</Field_Value>

</Order_Additional_Field_Item> <Order_Additional_Field_Item>

<Field_Label>Label2 (the same as the Field text)</Field_Label> <Field_Value>Value2</Field_label>

</Order_Additional_Field_Item>

</Order_Additional_Fields>

 

Order_Additional_Fields elements will be displayed per-order.

string VARCHAR(255)
Shopper / Partner Reference Number

The internal reference number your customers or partners assign to orders during the checkout process.

Customers and partners using Purchase Orders (POs) as the payment method during the ordering process have the option of setting identifiers for their orders designed to track and manage purchases in their own system.

string VARCHAR(255)
Refund Comment Comments entered for refunded orders. Displayed only on the first row of a refund order. string VARCHAR(255)
Test Order

Differentiates test orders from real orders. Available values:

  • YES
  • NO
boolean VARCHAR(3)
Product      
Product ID The unique identifier of products configured in the 2Checkout system. int INT
Product Code The identifiers that you control and can associate with products configured in the 2Checkout system. string VARCHAR(38)
Product Product name. string VARCHAR(80)
Extra info The text entered in the Additional information field when generating Buy links, or via the INFO[productid]= parameter used in the Buy links. string VARCHAR(255)
Pricing Options Name The name of the pricing option selected by the shopper during the purchase process. string VARCHAR(255)
Pricing Options Code The code of the pricing option selected by the shopper during the purchase process. string VARCHAR(255)
SKU Stock Keeping Unit string VARCHAR(255)
Product Additional Fields

Information collected from customers during the ordering process via one or multiple per-product custom additional fields. The Product Additional Fields column will report data collected from shoppers according to the following format:

- for CSV and XLS: "Field Name: Value." When multiple additional fields are used for a single product, data reported will be separated using "|", as such: Field Name1: Value1| Field Name2: Value2. Product Additional Fields features all values set by the customer in the ordering process for the additional fields defined for the product listed in the respective export row.

- for XML: <Product_Additional_Fields> <Product_Additional_Field_Item> 
<Field_Label>ExportData</Field_Label> <Field_Value>ExportData</Field_Value>
</Product_Additional_Field_Item> 
</Product_Additional_Fields>

For "CHECKBOX" additional fields, if the field was checked during the ordering process "CHECKED" value is showed in the export file. If the field was not checked, no information is displayed in the export.

string VARCHAR(255)
Delivered Filename The name of the product file delivered to customers as a part of the fulfillment process. string VARCHAR(255)
Pricing Options Operator

Array with all the price operators corresponding to each price option. 
Possible values:

  • ADD
  • SUBTRACT
string VARCHAR(9)
Pricing Options Value Array with all the prices corresponding to each option (prices are in the order currency). 
In the case of usage scale pricing options groups, it will return the price of the metered resources consumed by the customer in the order currency.
int VARCHAR(12)
Downloads Count Integer indicating the number of times a product was downloaded. int INT
Price      
Currency The currency used to place the order. string VARCHAR(15)
Unit price (without VAT) Price per unit. Taxes are not included. double DOUBLE
Quantity Number of units. int INT
Unit Discount The value of the discount per unit. double DOUBLE
Promotion The name of the promotion used during the ordering process. string VARCHAR(255)
Promotion Coupon Code The coupon code. string VARCHAR(20)
Total Price The total costs incurred by the customer per product. double DOUBLE
Total VAT The total value of VAT. double DOUBLE
General Discount The total discount per order. double DOUBLE
General Total Total value of the order. double DOUBLE
Shipping Per-order shipping cost. double DOUBLE
Shipping VAT The VAT for shipping costs. double DOUBLE
Customer and End User information      
Company The name of the company on whose behalf the order was placed from the billing details. string VARCHAR(80)
Client The name of the customer placing the order from the billing details. string VARCHAR(80)
Address The address of the customer placing the order from the billing details. string VARCHAR(100)
Phone The phone number of the customer placing the order from the billing details. string VARCHAR(20)
Email The email of the customer placing the order from the billing details. string VARCHAR(100)
City The city of the customer placing the order from the billing details. string VARCHAR(50)
Zip Code The zip code of the customer placing the order from the billing details. string VARCHAR(20)
Country The country of the customer placing the order from the billing details. string VARCHAR(50)
State The state of the customer placing the order from the billing details. string VARCHAR(30)
Fiscal Code VAT ID for companies from the billing details. string VARCHAR(20)
Registration Number Company registration number. string VARCHAR(20)
End-user company The name of the company on whose behalf the order was placed from the delivery details. string VARCHAR(80)
End user name The name of the end-user from the billing details. string VARCHAR(50)
End-user address The address of the end-user from the billing details. string VARCHAR(100)
End-user phone number The phone number of the end-user from the billing details. string VARCHAR(20)
End-user email address The email of the end-user from the billing details. string VARCHAR(100)
End-user city The city of the end-user from the billing details. string VARCHAR(50)
End-user ZIP Code The zip code of the end-user from the billing details. string VARCHAR(20)
End-user country The country of the end-user from the billing details. string VARCHAR(50)
End-user state The state of the end-user from the billing details. string VARCHAR(20)
Client First Name First name of the billing person. string VARCHAR(40)
Client Last Name Last name of the billing person. string VARCHAR(40)
End-User First Name First name of the product user. string VARCHAR(40)
End-User Last Name Last name of the product user. string VARCHAR(40)
Affiliate information      
Affiliate Affiliate company name for affiliate orders. Can be empty for non-affiliate orders. string VARCHAR(80)
Affiliate website Affiliate website. Can be empty for non-affiliate orders. string VARCHAR(100)
Affiliate ID 2Checkout affiliate ID. Can be empty for non-affiliate orders. int INT
Affiliate source (AFFSRC) Affiliate order source. string VARCHAR(1000)
Subscription information      
Avangate subscription reference The unique identifier of subscriptions in the 2Checkout system. For bundled products, multiple subscription identifiers are separated using "|", as such: Subscription1| Subscription2. string VARCHAR(38)
RenewalStatus Possible values:Manual|Auto string VARCHAR(20)
Subscription Possible value: New, Renewal, Upgrade, Trial and Regular from Trial. For bundled products, multiple values are separated using "|", as such: Trial|New|Renewal.   VARCHAR(50)
DIS Cost DIS costs incurred by the shopper. double DOUBLE
DIS Profit The DIS profit after your cost is deducted from the sum paid by the shopper. double DOUBLE
Billing Cycle Shows the number of times subscriptions featuring contract periods were renewed using an Int value. Otherwise, it will display the following string: N/A. int and the 'N/A' string VARCHAR(10)
Billing Cycles Left The number of billing cycles remaining until the contract restarts. 2Checkout counts down from the moment a subscription goes live. For example, the BILLING_CYCLES_LEFT value for a monthly subscription with a 12-month contract will be 11 in the first month, 10 the second month, 9 the third, then 8, 7, 6, 5, 4, 3, 2, 1 and 0, before the contract restarts. int VARCHAR(255)
Current Billing Cycle This parameter indicates the total number of billing cycles passed for a subscription out of the duration of the current contract. For example, the CURRENT_BILLING_CYCLE value for a monthly subscription with a 12-month contract will be 1 for the first month, 2 for the second month, and so forth until the twelfth billing cycle when the value will reach 12. Following the restart of the contract, the CURRENT_BILLING_CYCLE value will also be restarted, starting with 1 for the first month of the new contract, 2 for the second, etc. int VARCHAR(255)
Custom Price Billing Cycles Left 0 if you did not set a custom price for an ongoing subscription. Otherwise, this value shows the number of billing cycles that will be impacted by the custom price set for an ongoing subscription. int VARCHAR(255)
Financial details      
Processing fee 2Checkout commission (including DIS fees). double DOUBLE
Affiliate Commission The commission paid to the affiliate. double DOUBLE
Net Profit Your earnings minus the commissions paid to 2Checkout, affiliates, VAT or sales tax, shipping tax, DIS costs double DOUBLE
Payment Currency The currency 2Checkout uses to pay you for orders from your customers. string VARCHAR(15)
Exchange Rate The currency exchange rate used to convert the money paid by shoppers into the settlement currency 2Checkout used to pay you. double DOUBLE
Final Exchange Rate Possible values: YES, NO. The exchange rate is final when included into a 2Checkout Sales Report, or estimative otherwise. string VARCHAR(5)
NetIncomePerProduct Your earnings minus the commissions paid to 2Checkout, affiliates, VAT or sales tax, shipping tax, DIS costs for each product in an order. double DOUBLE
Invoice Number Prefix The prefix used for the invoice number. string VARCHAR(5)
Invoice Number The invoice number. int Int(11)
Communication language Language used during the ordering process. string VARCHAR(5)
FX markup FX markup used for converting the order into your payout currency. int Int(11)
Template ID ID assigned to the cart template used during the purchase. int Int(11)
Exported file options      
Timezone The time zone set for your account (Control Panel only, not API) via the Account settings area. string VARCHAR(50)
URL Unique website URL attached to each 2Checkout merchant account. In scenarios in which you export orders for aggregated accounts, the URL will feature the link to the website associated with the account from which the export is generated. string VARCHAR(255)

Order search export XML elements

The elements used in the XML export file for order data reflect the same information as the CSV headers detailed above. However, the labels have been adapted to match XML syntax best practices. Compare the CSV headers table above with the XML tree below to get an idea of the syntax differences.

Note: If you use custom labels for XML elements, please make sure to also follow XML syntax best practices. The 2Checkout system is designed to also ensure that there are no syntax issues, and as such will replace special characters with underscores.

All XML elements feature closing tags as long as there's content included in the export file. For example: <Product_ID>1234567</Product_ID>. Otherwise, if no data is available, the tag format will be: <SKU/>.

<?xml version="1.0" encoding="utf-8"?>
<OrdersSearchExport><Orders>
        <Order>
            <Products>
                <Product>
                    <Product_ID>1234567</Product_ID>
                    <Product_Code>bundle123456</Product_Code>
                    <Product>2Checkout Bundle</Product>
                    <Extra_info>ExtraInformationUsingTheINFOParameter</Extra_info>
                    <Quantity>1</Quantity>
                    <Unit_price__without_VAT_>99</Unit_price__without_VAT_>
                    <Total_Price>99.00</Total_Price>
                    <Total_VAT>0.00</Total_VAT>
                    <Unit_Discount>0.00</Unit_Discount>
                    <Promotion>100%</Promotion>
                    <Promotion_Coupon_Code/>
                    <SKU/>
                    <Subscription>
                        <Licence>New Acquisition</Licence>
                        <Licence>New Acquisition</Licence>
                    </Subscription>
                    <Avangate_subscription_reference>
                        <Licence>CDDA115DD6</Licence>
                        <Licence>DCDAD834F7</Licence>
                    </Avangate_subscription_reference>
                    <RenewalStatus>N/A</RenewalStatus>
                    <DIS_Cost>0.00</DIS_Cost>
                    <DIS_Profit>0.00</DIS_Profit>
                    <Billing_Cycle>N/A</Billing_Cycle>
                    <Billing_Cycles_Left>N/A</Billing_Cycles_Left>
                    <Current_Billing_Cycle>N/A</Current_Billing_Cycle>
                    <Affiliate_Commision>12.38</Affiliate_Commision>
                    <NetIncomePerProduct>77.15736842105264</NetIncomePerProduct>
                    <Product_Additional_Fields/>
                    <Pricing_Options_Name>1 User</Pricing_Options_Name>
                    <Pricing_Options_Code>oneuser1</Pricing_Options_Code>
                    <Fulfillment_information>
                        <Code>___TEST___CODE____</Code>
                    </Fulfillment_information>
                </Product>
                <Product>
                    <Product_ID>4622937</Product_ID>
                    <Product_Code>DISC_32877</Product_Code>
                    <Product>100%</Product>
                    <Extra_info/>
                    <Quantity>1</Quantity>
                    <Unit_price__without_VAT_>-94.05</Unit_price__without_VAT_>
                    <Total_Price>-94.05</Total_Price>
                    <Total_VAT>0.00</Total_VAT>
                    <Unit_Discount>0.00</Unit_Discount>
                    <Promotion/>
                    <Promotion_Coupon_Code/>
                    <SKU/>
                    <Subscription>
                        <Licence>New Acquisition</Licence>
                    </Subscription>
                    <Avangate_subscription_reference>
                        <Licence/>
                    </Avangate_subscription_reference>
                    <RenewalStatus>N/A</RenewalStatus>
                    <DIS_Cost>0.00</DIS_Cost>
                    <DIS_Profit>0.00</DIS_Profit>
                    <Billing_Cycle>N/A</Billing_Cycle>
                    <Billing_Cycles_Left>N/A</Billing_Cycles_Left>
                    <Current_Billing_Cycle>N/A</Current_Billing_Cycle>
                    <Affiliate_Commision>0.00</Affiliate_Commision>
                    <NetIncomePerProduct>-85.06049999999999</NetIncomePerProduct>
                    <Product_Additional_Fields/>
                    <Pricing_Options_Name/>
                    <Pricing_Options_Code/>
                    <Fulfillment_information/>
                </Product>
                <Product>
                    <Product_ID>1234567</Product_ID>
                    <Product_Code>my_subscription_1</Product_Code>
                    <Product>2Checkout Subscription</Product>
                    <Extra_info>ThisIsAdditionalInfoForATrial</Extra_info>
                    <Quantity>1</Quantity>
                    <Unit_price__without_VAT_>99</Unit_price__without_VAT_>
                    <Total_Price>99.00</Total_Price>
                    <Total_VAT>0.00</Total_VAT>
                    <Unit_Discount>9.90</Unit_Discount>
                    <Promotion>100%</Promotion>
                    <Promotion_Coupon_Code>123</Promotion_Coupon_Code>
                    <SKU>NewSubscriptionPurchase</SKU>
                    <Subscription>
                        <Licence>New Acquisition</Licence>
                    </Subscription>
                    <Avangate_subscription_reference>
                        <Licence>22C4327A7E</Licence>
                    </Avangate_subscription_reference>
                    <RenewalStatus>Auto</RenewalStatus>
                    <DIS_Cost>0.00</DIS_Cost>
                    <DIS_Profit>0.00</DIS_Profit>
                    <Billing_Cycle>N/A</Billing_Cycle>
                    <Billing_Cycles_Left>N/A</Billing_Cycles_Left>
                    <Current_Billing_Cycle>N/A</Current_Billing_Cycle>
                    <Affiliate_Commision>11.14</Affiliate_Commision>
                    <NetIncomePerProduct>69.44363157894736</NetIncomePerProduct>
                    <Product_Additional_Fields>
                        <Product_Additional_Field_Item>
                            <Field_Label>CustomField</Field_Label>
                            <Field_Value/>
                        </Product_Additional_Field_Item>
                    </Product_Additional_Fields>
                    <Pricing_Options_Name>1 User</Pricing_Options_Name>
                    <Pricing_Options_Code>oneuser1</Pricing_Options_Code>
                    <Fulfillment_information>
                        <Code>___TEST___CODE____</Code>
                    </Fulfillment_information>
                </Product>
            </Products>
            <Order_No>971</Order_No>
            <Order_status>COMPLETE</Order_status>
            <Test_Order>Yes</Test_Order>
            <Reference_No>43312351</Reference_No>
            <External_Reference_No/>
            <Affiliate_ID>58259</Affiliate_ID>
            <Pay_Method>Visa</Pay_Method>
            <Order_Date>2015-10-22 11:09:35</Order_Date>
            <Order_Finish_Date>2015-10-22 11:11:12</Order_Finish_Date>
            <Currency>USD</Currency>
            <General_Discount>0</General_Discount>
            <Shipping>0</Shipping>
            <Shipping_VAT>0</Shipping_VAT>
            <General_Total>94.05</General_Total>
            <Processing_fee>8.9895</Processing_fee>
            <Company/>
            <Client>2Checkout Blue</Client>
            <Address>Address </Address>
            <Phone/>
            <Email>example@test.com</Email>
            <City>LA</City>
            <Zip_Code>90810</Zip_Code>
            <Country>United States of America</Country>
            <State>Alabama</State>
            <Fiscal_Code/>
            <Registration_Number/>
            <End_user_company/>
            <End_user_name>2Checkout Blue</End_user_name>
            <End_user_address>Address </End_user_address>
            <End_user_phone_number/>
            <End_user_email_address>example@test.com</End_user_email_address>
            <End_user_city>LA</End_user_city>
            <End_user_ZIP_Code>90810</End_user_ZIP_Code>
            <End_user_country>United States of America</End_user_country>
            <End_user_state>Alabama</End_user_state>
            <Affiliate>2Checkout Green</Affiliate>
            <Affiliate_website>test.greener.com</Affiliate_website>
            <Approval_status>Finished</Approval_status>
            <Invoice_Number_Prefix/>
            <Invoice_Number/>
            <EndUserIP>91.220.121.21</EndUserIP>
            <Payment_Currency/>
            <Exchange_Rate/>
            <Final_Exchange_Rate>NO</Final_Exchange_Rate>
            <Shopper_Invoice_No/>
            <Tracking_Order_Id/>
            <Tracking_Id/>
            <Order_Flow>REGULAR</Order_Flow>
            <Net_Profit>61.54</Net_Profit>
            <Sale_Source>www.Mysource.com</Sale_Source>
            <Refund_Comment/>
            <Refund_Reason/>
            <Delivered_Filename/>
            <Downloads_Count>0|</Downloads_Count>
            <URL>http://www.2CheckoutLearningCenter.com</URL>
            <Shopper_Partner_Reference_Number/>
            <Initial_Renewal_Type>N/A</Initial_Renewal_Type>
            <Subscription_Billing_Cycle_Expiration_Date/>
            <Client_First_Name>2Checkout</Client_First_Name>
            <Client_Last_Name>Blue</Client_Last_Name>
            <End_User_First_Name>2Checkout</End_User_First_Name>
            <End_User_Last_Name>Blue</End_User_Last_Name>
            <Media_Type/>
            <Origin>Web</Origin>
            <Gateway_Response>N/A</Gateway_Response>
            <Order_Additional_Fields>
                <Order_Additional_Field_Item>
                    <Field_Label>Where did you hear about our company?</Field_Label>
                    <Field_Value/>
                </Order_Additional_Field_Item>
            </Order_Additional_Fields>
            <Pricing_Options_Value>0.00</Pricing_Options_Value>
            <Pricing_Options_Operator>ADD</Pricing_Options_Operator>
            <Initial_dispute_request/>
            <Chargeback_Close_Date/>
            <Chargeback_Reason/>
            <Chargeback_Reason_Code/>
            <Chargeback_Status/>
            <Original_External_Reference_No/>
            <Original_Sale_Source/>
        </Order></Orders><Timezone>
</OrdersSearchExport>

 

The XML structure groups orders under the Orders element, marked with the <Orders></Orders> tags.

Orders elements include the order export items, namely one or multiple orders. Order-level elements are included under Order, such as Products, when multiple offerings are acquired via the same order, while product-level elements are placed under Product.

Add promotion translations

Request

<?php 

class Client
{
    protected static $merchantCode;
    protected static $loginDate;
    protected static $hash;
    protected static $baseUrl;
    protected static $callCount = 0;
    protected static $sessionId = '';

    protected static $client;

    public static function setCredentials($code, $key)
    {
        static::$merchantCode = $code;
        static::$loginDate = gmdate('Y-m-d H:i:s');
        static::$hash = hash_hmac('md5', strlen($code) . $code . strlen(static::$loginDate) . static::$loginDate, $key);
        static::$sessionId = static::login();
    }

    public static function setBaseUrl($url)
    {
        static::$baseUrl = $url;
    }

    public static function login()
    {
        $client = static::getClient();
        return $client->login(static::$merchantCode, static::$loginDate, static::$hash);
    }

    public static function __callStatic($name, $arguments = array())
    {
        $client = static::getClient();

        array_unshift($arguments, static::$sessionId);
        $response = call_user_func_array(array($client, $name), $arguments);

        return $response;
    }

    protected static function getClient()
    {
        $opts = array(
            'http'=> ['user_agent' => 'PHPSoapClient'],
            'ssl' => [
                'verify_peer' => false,
                'verify_peer_name' => false,
            ],
        );

        if (null === static::$client) {
            static::$client = new \SoapClient(static::$baseUrl . '?wsdl', [
                'location' => static::$baseUrl,
                'cache_wsdl' => WSDL_CACHE_NONE,
                'stream_context' => stream_context_create($opts),
            ]);
        }

        return static::$client;
    }
}

Client::setBaseUrl('https://api.avangate.com/soap/3.1/');
Client::setCredentials('YOUR_MERCHANT_CODE', 'YOUR_SECRET_KEY');
Client::login();

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

// Defining a translation for German shoppers
$promotionTranslation1 = new stdClass;
$promotionTranslation1->Language = 'de'; 
$promotionTranslation1->Name = 'YOUR_GERMAN_PROMOTION_NAME';

// Defining a translation for Bulgarian shoppers
$promotionTranslation2 = new stdClass;
$promotionTranslation2->Language = 'bg'; 
$promotionTranslation2->Name = 'YOUR_BULGARIAN_PROMOTION_NAME';

$translations = [$promotionTranslation1, $promotionTranslation2];

$response = Client::addPromotionTranslations($promotionCode,$translations); // Add translations to selected promotions
var_dump($response);

UnitPrice Object structure

Structure

Parameters Type/Description
Currency String
  Partner currency ISO code - ISO 4217.
NetPricePerUnit Double
  The net price per unit of product, representing the costs incurred by the partner, minus the margin and taxes (if applicable).
PartnerMarginPerUnit Double
  New purchase partner margin calculated per unit of product.
VatPerUnit Double
  VAT or sales taxes applied to the value of a single product unit.

 

Subscription additional information fields

Overview

Use this object to create, update and retrieve additional information fields from your subscriptions.

Attributes

Parameters Type/Description

fieldName

String

 

The name of the additional information field. Used for identifying additional information fields.

fieldValue

String

 

The value of the additional information field.

 

Order object

Overview

Use this object to create new orders and collect payments from shoppers. 

Supported payment methods

  1. Credit/Debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
  2. PayPal and PayPal Express
  3. Purchase Order
  4. Wire
  5. Check
  6. Previous order references - In addition to the payment methods enumerated above, 2Checkout also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts. 

Currency support

Check with 2Checkout support for a list of currencies available for each payment method. 

Parameters

Order object parameters Type/Description

RefNo

Optional (string)

 

Unique, system-generated, order reference number.

 

Do not include it when placing new orders or send it as NULL.

Currency

Required (string)

 

The currency ISO code for the payment - ISO 4217. Example: “usd.”

Country

Required (string)

 

Shopper country. ISO 3166 two-letter code. Example: “us.”

Language

Optional (string)

 

ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”

ExternalReference

Optional (string)

 

Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included in Buy-Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client-side.

Source

Optional (string)

 

The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.

 

Maximum length 255 characters.

AffiliateId

Optional (int)

 

Identifier belonging to affiliates who refer orders.

CustomerReference

Optional (Int)

 

System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.

Items

Required (array of objects)

  Details below. 

 

OrderItem

Object

      Details below. 

 

 

Code

Required (string)

 

 

 

Unique product identifier your control. Max length 256 characters.

 

 

Quantity

Required (integer)

 

 

 

Number of units

 

 

PriceOptions

Optional (array of strings)

 

 

 

Array of price option codes.

 

 

SKU

Optional (string)

 

 

 

SKU identifier.

 

 

Price

Object - Can be NULL

 

 

 

 

OrderPrice

Object - Can be NULL

 

 

 

 

 

Currency

Optional (string)

 

 

 

 

 

 

The currency ISO code for the payment - ISO 4217. Example: usd.

 

 

 

 

 

NetPrice

Optional (double)

 

 

 

 

 

 

Order value excluding sales tax/VAT expressed in the payment currency.

 

 

 

 

 

GrossPrice

Optional (double)

 

 

 

 

 

 

Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.

 

 

 

 

 

NetDiscountedPrice

Optional (double)

 

 

 

 

 

 

The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.

 

 

 

 

 

GrossDiscountedPrice

Optional (double)

 

 

 

 

 

 

Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout, and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

For example:

 

  • Currency: "usd"
  • NetPrice: 396
  • GrossPrice: 486.29
  • NetDiscountedPrice: 376.2
  • GrossDiscountedPrice: 466.49
  • Discount: 19.8
  • VAT: 90.29

AffiliateCommission: 94.05

 

 

 

 

 

Discount

Optional (double)

 

 

 

 

 

 

Value of the discounts for an order expressed in the payment currency.

 

 

 

 

 

VAT

Optional (double)

 

 

 

 

 

 

Value of sales tax/VAT expressed in the payment currency.

 

 

 

 

 

AffiliateCommission

Optional (double)

 

 

 

 

 

 

Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.

 

 

 

 

UnitNetPrice

Optional (double)

 

 

 

 

 

The value per product unit, excluding sales tax/VAT expressed in the payment currency.

 

 

 

 

UnitGrossPrice

Optional (double)

 

 

 

 

 

Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

 

 

 

 

UnitVAT

Optional (double)

 

 

 

 

 

Sales tax/VAT per product unit expressed in the payment currency.

 

 

 

 

UnitDiscount

Optional (double)

 

 

 

 

 

Value of the discount per product unit expressed in the payment currency.

 

 

 

 

UnitNetDiscountedPrice

Optional (double)

 

 

 

 

 

The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.

 

 

 

 

UnitGrossDiscountedPrice

Optional (double)

 

 

 

 

 

Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

 

 

 

UnitAffiliateCommission

Optional (double)

 

 

 

 

 

Value of the affiliate commission per product unit calculated expressed in the payment currency.

 

2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

 

2Checkout does not take into account shipping costs when calculating affiliate commissions.

 

NULL when 2Checkout does not apply an affiliate commission.

 

 

CrossSell

Object – Can be NULL

        Details below. 

 

 

 

ParentCode

Optional (string)

 

 

 

 

The product code of the master product you set to trigger the campaign.

 

 

 

CampaignCode

Optional (string)

 

 

 

 

Unique, system-generated identifier for cross-sell campaigns.

 

 

Trial

Optional (Object) – Can be NULL

        Details below. 

 

 

 

Period

Optional (integer)

 

 

 

 

The length of the trial subscription lifetime in days.

 

 

 

Price

Optional (double)

 

 

 

 

Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.

 

 

AdditionalFields

Optional (array of objects) – Can be NULL

 

 

 

AdditionalFieldSet

Optional (Object) – Can be NULL

 

 

 

 

Code

Optional (string)

 

 

 

 

 

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

 

 

 

 

Value

Optional (string)

 

 

 

 

 

Selected field value.

    SubscriptionStartDate Optional (string)
     

Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.

Send empty or NULL to activate subscriptions on the same date when customers purchase them.

You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.

 

 

Promotion

Optional (Object)

        Details below. 

 

 

 

Name

Optional (string)

 

 

 

 

Promotion name.

 

 

 

Description

Optional (string)

 

 

 

 

Promotion description.

 

 

 

StartDate

Optional (string)

 

 

 

 

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

 

 

 

EndDate

Optional (string)

 

 

 

 

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

 

 

 

MaximumOrdersNumber

Optional (integer)

 

 

 

 

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.

 

 

 

MaximumQuantity

Optional (integer)

 

 

 

 

Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

 

 

 

InstantDiscount

Optional (boolean)

 

 

 

 

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

 

 

 

Coupon

Optional (string)

 

 

 

 

Promotion coupon/voucher.

 

 

 

DiscountLabel

Optional (string)

 

 

 

 

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

 

 

 

Enabled

Optional (string)

 

 

 

 

true or false, depending on whether a promotion is active or disabled. 

 

 

 

Type

Optional (string)

 

 

 

 

  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.

BillingDetails

Required (Object)

    Details below. 

 

Person

Object

      Details below. 

 

 

FirstName

Required (string)

 

 

 

Shopper name.

 

 

LastName

Required (string)

 

 

 

Shopper surname.

 

 

CountryCode

Required (string)

 

 

 

Shopper country. ISO 3166 two-letter code.

 

 

State

Required (string)  for US, Brazil and Romania

 

 

 

The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

 

 

City

Required (string)

 

 

 

Shopper city.

 

 

Address1

Required (string)

 

 

 

Shopper address.

 

 

Address2

Optional (string)

 

 

 

Shopper address.

 

 

Zip

Required (string)  for US, Brazil and Romania

 

 

 

ZIP/ Postal code.

 

 

Email

Required (string)

 

 

 

Shopper email address.

 

 

Phone

Optional (string) 

 

 

 

Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.

 

 

Company

Optional (string)

 

 

 

Company name. Can be null for end users. When present, you also need to provide the FiscalCode.

 

FiscalCode

Optional (string) – Required for Brazil

 

 

• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Can be NULL for end users.

DeliveryDetails

Required (Object)

    Details below. 

 

Person

Object

      Details below. 

 

 

FirstName

Required (string)

 

 

 

Shopper name from the delivery details.

 

 

LastName

Required (string)

 

 

 

Shopper surname from the delivery details.

 

 

CountryCode

Optional (string)

 

 

 

Shopper country. ISO 3166 two-letter code from the delivery details.

 

 

State

Optional (string) – Required for US, Brazil and Romania

 

 

 

The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

 

 

City

Optional (string)

 

 

 

Shopper city from the delivery details.

 

 

Address1

Optional (string)

 

 

 

Shopper address from the delivery details.

 

 

Address2

Optional (string)

 

 

 

Shopper address from the delivery details.

 

 

Zip

Optional (string)

 

 

 

ZIP/ Postal code from the delivery details.

 

 

Email

Optional (string)

 

 

 

Shopper email address from the delivery details.

 

 

Phone

Optional (string)

 

 

 

Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.

 

 

Company

Optional (string)

 

 

 

Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.

PaymentDetails

Required (Object)

 

Adapt this object to the desired payment method.

 

Type

Required (string)

 

 

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • ENCRYPTED_PAYMENT_DATA (client-side encryption)
  • PAYPAL
  • PAYPAL_EXPRESS
  • TEST (for test orders).
  • PREVIOUS_ORDER (place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.

 

 

Currency

Required (string)

 

 

The currency ISO code for the payment - ISO 4217. Example: “usd.”

 

PaymentMethod

Required (string)

 

 

Object structure and parameters differ according to the payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)).

 

NULL for 0 value orders for which you’re not requiring customers to enter payment details.

                                                                          RecurringEnabled Optional (boolean)
   

true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.

false – shopper doesn’t check the auto-renewal checkbox.

 

 

 

CardPayment

Optional (object)

          Details below. 

 

 

 

 

CardNumber

Optional (string)

 

 

 

 

 

The credit/debit card number.

 

 

 

 

CardType

Optional (string)

 

 

 

 

 

visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo

 

 

 

 

ExpirationYear

Optional (string)

 

 

 

 

 

The year in which the card expires.

 

 

 

 

ExpirationMonth

Optional (string)

 

 

 

 

 

The month in which the card expires.

 

 

 

 

HolderName

Optional (string)

 

 

 

 

 

Card holder name.

 

 

 

 

CCID

Optional (string)

 

 

 

 

 

Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.

        HolderNameTime Optional (float)
         

The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.

        CardNumberTime

Optional (float)

         

The interval of time in seconds in which shopper enters their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.

        InstallmentsNumber  Optional (Int)
          Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments. 

 

 

 

PayPalExpress

Optional (object)

          Details below. 

 

 

 

 

Email

Optional (string)

 

 

 

 

 

Email address customers use for their PayPal account.

 

 

 

 

ReturnURL

Optional (string)

 

 

 

 

 

The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs in to PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.

 

 

 

 

CancelURL

Optional (string)

 

 

 

 

 

The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.

 

 

 

PreviousOrder

Optional (Object)

          Details below. 

 

 

 

 

RefNo

Optional (string)

 

 

 

 

 

Order reference a previous purchase that reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of the order should be AUTHRECEIVED or COMPLETE.

 

Check the validity of references with the isValidOrderReference method.

 

The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.

 

 

 

PurchaseOrderPaymentDetails

Optional (Object)

          Details below. 

 

 

 

 

InternalPONumber

Optional (string)

 

 

 

 

 

Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.

 

 

 

 

AutoApprove

Optional (boolean)

 

 

 

 

 

TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders.

FALSE - Default. Send this if the PO AutoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders.

 

Can be NULL.

 

 

 

EXISTING_PAYMENT_DATA

Optional (Object)

 

 

 

 

By using EXISTING_PAYMENT_DAT you no longer require shoppers to enter any payment details.

 

 

 

 

TransientToken

Optional (string)

 

 

 

 

 

Returned as a part of the process of retrieving customer information by SSOToken.

 

CustomerIP

Required (string)

 

 

Shopper IP.

Promotions

Optional (Array of strings)

 

Array of promotion codes.

AdditionalFields

 

    Details below. 

 

Code

Optional (string)

 

 

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

 

Text

Optional (string)

 

 

Field text visible to shoppers in the cart.

 

Value

Optional (string)

 

 

Selected field value.

LocalTime

Optional (string)

 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.

GiftDetails

Optional (object)

 

Contains contact details for the recipient of gift purchase.

 

FirstName

Optional (string)

 

 

First name of gift recipient.

 

LastName

Optional (string)

 

 

Last name of gift recipient.

 

Email

Optional (string)

 

 

Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.

 

GiftNote

Optional (string)

 

 

Custom text shoppers provide as a message to the gift recipient.

 

 

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