Skip to main content

Assign order/product additional fields

Overview

Use the assignAdditionalField method to update additional fields for your account.

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.

FieldCode

Required (string)

 

Field identifier. Alpha-numeric chars, underscores and dashes.

Required

Boolean

 

True or False depending on whether you want make the field mandatory or not.

ProductCode

Required (string)

 

The unique product code that you control not the system-generated product identifier.

Response

bool(true)

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 = "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;
}

$ProductCode = 'AAA4643116';
$FieldCode = 'NewsletterPolicy123457106';
$Required = true;
try {
    $AssignedAdditionalField = $client->assignAdditionalField($sessionID, $FieldCode, $Required, $ProductCode);
}

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

var_dump("AssignedAdditionalField", $AssignedAdditionalField);

?>

 

Use test orders

Overview

Place a test order using catalog products defined in your Control Panel.

Requirements

Set the Payment details type to TEST in order to create an order in a test environment.

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.

Order

Required (Object)

 

An object designed to collect all data necessary for an order, including billing, product/subscription plan, and payment details.

 

 

Response 

Parameters Type/Description

Order information

Object

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$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->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'cosmin.deftu@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$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';
$Order->PaymentDetails->PaymentMethod->Vendor3DSReturnURL = "http://yoursuccessurl.com"; // used for 3DS ordering
$Order->PaymentDetails->PaymentMethod->Vendor3DSCancelURL = "http://yourcancelurl.com"; // used for 3DS ordering

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}

var_dump("newOrder", $newOrder);

 

Retrieve account balance

Overview

Use getPendingPayout to retrieve a detailed estimation of the amount that 2Checkout owes you, based on the sales from your current payout period.

The amounts returned by this API method are approximations, and may not represent the final amount that 2Checkout will pay you at the end of the billing period.

Parameters

Parameters Type/Description
inputParameters

Object (Optional)

Details below

  Currency String (Optional)
   

Use this parameter to show the balance only for a single order currency. Example: 'USD'.

If not sent, or sent as NULL, 2Checkout sends the balance for all order currencies.

  TotalCurrency String (Optional)
   

Use this parameter to show the total account balance in the preferred currency. Example: 'EUR'.

If not sent, or sent as NULL, 2Checkout sends the total balance in the default account currency.

Request

<?php

require('PATH_TO_AUTH');

$inputParameters = new StdClass();
$inputParameters->Currency = 'USD';
$inputParameters->TotalCurrency = 'EUR';

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

echo "<pre>";

var_dump("getPendingPayout", callRPC((Object)$jsonRpcRequest, $host));

Response

Pending Payout Object

Parameters   Type/Description
Currencies

Array of objects

Details below

  CurrencyObject

Object

Details below

    Currency

String

      Order currency.
    OrdersTotal

Object

Total order amounts, divided per order source.

                        estore Float
      eStore order amounts from the current payout cycle.
                       affiliates Float
      Amounts from your affiliates orders, during the current payout cycle.
                       partner Float
      Amounts from your partner sales, during the current payout cycle.
                        total Float
      Total sales amount made in the order currency from this object, during the current payout cycle.
  RetainedToDisputesBalance Float
      Amounts retained to your dispute balance reports, in the object order currency.
  ReleasedFromDisputesBalance Float
      Amounts released from your dispute balance reports, in the object order currency.
  RetainedToRollingReserveBalance Float
      Amounts retained to your rolling reserve, in the object order currency.
  ReleasedFromRollingReserveBalance Float
      Amounts retained to your rolling reserve, in the object order currency
  ChargebackFees Float
      Chargeback fees retained in the object order currency.
  ProcessingFees Float
      Processing fees retained by 2Checkout in the object order currency.
  AffiliatesCommission Float
      Affiliate commissions paid by 2Checkout in the object order currency.
  TaxCollected Float
      Tax collected by 2Checkout in the object order currency.
  EstimatedTotalRevenue Float
      The estimated total revenue for the object order currency.
Total    

Object

Total account balance amount

  Currency  

String

      Currency used for expressing the account balance.. If not sent in the API call, 2Checkout uses the account default currency.
  OrdersTotal

 

Object

Total order amounts, divided per order source.

    estore Float
      Amounts from total eStore orders during the currency payout cycle.
                      affiliates Float
      Amounts from total affiliates orders during the currency payout cycle.
                      partner Float
      Amounts from total partner orders during the currency payout cycle.
                      total Float
      Total sales amount during the currency payout cycle.
  RetainedToDisputesBalance Float
      Total amounts retained to your dispute balance during the current payout cycle.
  RetainedFromDisputesBalance Float
      Total amounts released from your dispute balance during the current payout cycle.
  RetainedToRollingReserveBalance Float
      Total amounts retained to your rolling reserve during the current payout cycle.
  RetainedFromRollingReserveBalance Float
      Total amounts released from your rolling reserve during the current payout cycle.
  ChargebackFees Float
      Total chargeback fees retained from your account during the currency payout cycle.
  ProcessingFees Float
      Total processing fees retained by 2Checkout during the current payout cycle.
  AffiliatesCommission Float
      Total affiliates commissions paid by 2Checkout during the current payout cycle.
  TaxCollected Float
      Total tax amount collected by 2Checkout during the current payout cycle.
  EstimatedTotalRevenue Float
      Total estimated revenue for the current payout cycle.

 

Subscription additional information fields

Overview

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

Parameters

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.

 

 

Retrieve Single Sign On customer info by SSOToken

Overview

Use the getCustomerInformationBySSOToken method to retrieve the details of a customer entity from the Avangate system. Send the SSO token you create by generating tokenized cart payment links.

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.
SingleSignOnToken Required (string)
  The SSO token you create by generating tokenized cart payment links.

Response

Customer Object

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 = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$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;
}
$IdCustomer = '352365983';
$CustomerType = 'AvangateCustomerReference';
$Url = 'https://store.avancart.com/order/checkout.php?PRODS=4639321&QTY=1&CART=1&CARD=2';
$ValidityTime = 50;
$ValidationIp = null;
try {
    $ssoLINK = $client->getSingleSignOnInCart($sessionID, $IdCustomer, $CustomerType, $Url, $ValidityTime, $ValidationIp);
}
catch (SoapFault $e) {
    echo "ssoLINK: " . $e->getMessage();
    exit;
}
var_dump("ssoLINK", $ssoLINK);
parse_str($ssoLINK);
try {
    $CustomerSSOInfo = $client->getCustomerInformationBySSOToken($sessionID, $logintoken);
}
catch (SoapFault $e) {
    echo "CustomerSSOInfo: " . $e->getMessage();
    exit;
}
var_dump("CustomerSSOInfo", $CustomerSSOInfo);

Retrieve subscription payment information

Overview

Use the getSubscriptionPaymentInformation method via JSON-RPC API 4.0 to retrieve information related to the payment made for 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)
  The reference of the subscription you want to retrieve payment information for.

Response

Parameters Type/Description

Type

String

 

Payment method type.

Currency

String

 

ISO code of the order currency.

PaymentMethod

Object

 

FirstDigits

String

 

 

First 4 digits of the card used on the order.

 

LastDigits

String

 

 

Last 4 digits of the card used on the order.

 

CardType

String

 

 

Type of card used on the order.

Request

<?php
require ('PATH_TO_AUTH');

$subscriptionReference = "Subscription_Code";

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'getSubscriptionPaymentInformation';
$jsonRpcRequest->params = array($sessionID, $subscriptionReference);
$jsonRpcRequest->id = $i++;

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

Retrieve specific list of subscriptions

Overview

Extract information on a specific list of subscriptions. Use the getSubscriptions method to retrieve details about a specific list of your account’s subscriptions.

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 (Array of strings)

 

Unique, system-generated subscription identifier.

aggregate

Required (boolean)

 

true - search will work across all your aggregated Avangate accounts.

false - default value. You limit the search to the account whose details you used for authentication.

Response

Parameters Type/Description

Subscription

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferences = array('REFERENCE1', 'REFERENCE2', 'REFERENCE3');

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

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

Retrieve VAT or sales tax

Overview

  1. Populate the Order object with information. Avangate needs the BillingDetails (object) information to calculate taxes. 
  2. Use the getContents method to get info on all the products added to cart by the shopper in the current session.
  3. The output of the getContents method is the Order session content object.
  4. Under the Price, access information including for each product purchased. Find value added tax and sales tax details under the VAT parameter. 
  5. Tax information is also available for the entire order object. Find value added tax and sales tax details under the VAT parameter.
  6. Calculate the VAT/sales tax rates using the VAT and NetPrice values

 

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.

Order

Required (Object)

 

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

Response

OrderContents

Object

Request

<?php


function callRPC($Request, $hostUrl, $Debug = true) {
    $curl = curl_init($hostUrl);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);


    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }

    if (!empty($ResponseString)) {
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

$host = 'https://api.avangate.com/rpc/3.0/';

$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);

$i = 1; // counter for api calls
// call login
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;

$sessionID = callRPC($jsonRpcRequest, $host);

var_dump($sessionID);
$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$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->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$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';
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;
$jsonRpcRequest = array (
'method' => 'getContents',
'params' => array($sessionID, $Order),
'id' => $i++,
'jsonrpc' => '2.0'
);
echo '<BR>';
echo 'The content of the current session:';
echo '<BR>';
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

Payment flow with offline payment methods

Overview

The following payment methods are supported for the offline payment flow: Purchase Order flow, Wire, Check, and Boleto/Pix

Availability

Available for all 2Checkout accounts.

How E-wallet payments work 

Offline payment methods are payment methods where the order is registered by 2Checkout, however, the shopper finalizes the payment offline. 

This type of payment methods include payments done via bank transfers (Purchase Orders, Wire) or in-store payments like Boleto/Pix

Since these payments take longer to process than online payments, once an order is placed it will remain in 'status = Pending' until the order status is updated by the payment provider. Once the payment is processed by them, then the order status will be updated to 'Complete' in the 2Checkout system.

Purchase Order flow

The Purchase Order flow payment method is available only for payments done by companies. The Purchase order (PO) flow is similar to the Wire payment method, as in the data needed for the completion of the payment will be available both in the API response, as well as in the email sent to the email address used in the Billing Details object.

Payment method object structure

Field name Type Required/Optional Description

Company

String

Required

The name of the company.

AutoApprove

Boolean

Optional

Use AutoApprove = true when you want the order to be automatically approved by the merchant. If false, the order needs to be approved manually from the Merchant Control Panel.

Default value: false.

InternalPONumber

String

Optional

Internal unique ID.

Request example

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"133685A7B4",
         "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",
      "Company":"ACME Inc."
   },
   "PaymentDetails":{
      "Type":"PURCHASEORDER",
      "Currency":"USD",
      "PaymentMethod":{
         "AutoApprove":true,
         "InternalPONumber":84864848
      }
   }
}

After the order is placed, it will remain in 'status = Pending' until the payment is completed.

The additional information needed by the shopper to finalize the payment is provided in the PaymentDetails node.

"PaymentDetails":{
      "Type":"WIRE",
      "Currency":"usd",
      "PaymentMethod":{
         "Amount":"24.65",
         "Currency":"usd",
         "PaymentReference":"130738297",
         "RoutingNumber":null,
         "BankAccounts":[
            {
               "BankName":"Silicon Valley Bank USA",
               "BankCountry":"United States of America",
               "BankCity":null,
               "BankAddress":"3003 TASMAN DRIVE, SANTA CLARA, CA  95054, USA",
               "Beneficiary":"Avangate Inc dba 2Checkout",
               "BankAccount":"ABA 121140399 #3300578784",
               "BankAccountIban":null,
               "BankAccountSwiftCode":"SVBKUS6S",
               "Currency":"USD"
            }
         ],
         "Vendor3DSReturnURL":null,
         "Vendor3DSCancelURL":null,
         "InstallmentsNumber":null
      },
      "CustomerIP":"5.12.32.22"
   },

Wire  

Payment method object structure

There are no specific payment method data that is mandatory or optional. 

Request example

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"133685A7B4",
         "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":"WIRE",
      "Currency":"USD",
      "PaymentMethod":{

      }
   }
}

After the order is placed, it will remain in 'status = Pending' until the payment is completed.

The additional information needed by the shopper to finalize the payment is provided in the PaymentDetails node. 

"PaymentDetails":{
      "Type":"WIRE",
      "Currency":"usd",
      "PaymentMethod":{
         "Amount":"24.65",
         "Currency":"usd",
         "PaymentReference":"130738297",
         "RoutingNumber":null,
         "BankAccounts":[
            {
               "BankName":"Silicon Valley Bank USA",
               "BankCountry":"United States of America",
               "BankCity":null,
               "BankAddress":"3003 TASMAN DRIVE, SANTA CLARA, CA  95054, USA",
               "Beneficiary":"Avangate Inc dba 2Checkout",
               "BankAccount":"ABA 121140399 #3300578784",
               "BankAccountIban":null,
               "BankAccountSwiftCode":"SVBKUS6S",
               "Currency":"USD"
            }
         ],
         "Vendor3DSReturnURL":null,
         "Vendor3DSCancelURL":null,
         "InstallmentsNumber":null
      },
      "CustomerIP":"5.12.32.22"
   },

Check  

Payment method object structure

There are no specific payment method data that is mandatory or optional. 

Request example

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"133685A7B4",
         "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":"CHECK",
      "Currency":"USD",
      "PaymentMethod":{

      }
   }
}

After the order is placed, it will remain in 'status = Pending' until the payment is completed.

The additional information needed by the shopper to finalize the payment is provided via email. 

Integration test cases

  1. Build a request with all the relevant information to place a new order. Make sure that when the order is sent in the API the response contains an order object (order was placed successfully).
  2. Make sure that you display the information needed by the shopper to finalize the payment.
  3. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully. 

Calculate and display shopping cart taxes

Overview

When selling internationally, charging the appropriate amount for taxes can be tricky, as the correct taxation can depend on the shopper's country or US state, the product type, and the order total amount. 

However, merchants on the 2Monetize package do not have to worry, as the API calculates and handles the VAT and Sales taxes based on the order information. 

Availability

Available to all 2Checkout accounts.

getContents API Method

Information about VAT and sales taxes is handled by the getContents (for JSON-RPC and SOAP protocols) or by making a PUT request to /orders/0/ on REST.

This API method will take into account the product configuration (NET or GROSS price type, product category, pricing options, etc.), any marketing campaign (like discounts) together with the shopper's location, and return all the information needed to display to the shopper.

Request object

The getContents API call accepts as an input an order object, the same object used for placing an order. However, the only required objects for calculating the taxes are the items information (what products the shopper has in their cart) and the BillingDetails (needed in order to locate the customer and retrieve the taxes that should be applied). 

Switching the currency

Switching the currency and converting prices is supported both for prices set in multiple currencies in the product configuration, as well as on the fly. 

In order to do this, the currency ISO code needs to be updated in the root object Currency element.

Request example

{
    "Country": "DE",
    "Currency": "EUR",
    "Items": [
        {
            "Code": "NIQRPI0GTU",
            "Quantity": 2
        },
        {
            "Code": "0XICS3OVDK",
            "Quantity": 1
        }
    ],
    "BillingDetails": {
        "FirstName": "Customer First Name",
        "LastName": "Customer Last Name",
        "CountryCode": "DE",
        "City": "Bucharest",
        "Address1": "Example Street",
        "Zip": "73331",
        "Email": "example@email.com"
    }
}

Response Object

The API will respond with the full order object, including the price and tax information, both on a line item (unit) level as well as on a cart level.  

{
    "Currency": "eur",
    "NetPrice": 266.71,
    "GrossPrice": 309.38,
    "NetDiscountedPrice": 266.71,
    "GrossDiscountedPrice": 309.38,
    "Discount": 0,
    "VAT": 42.67,
    "AffiliateCommission": 0,
    "Errors": null,
    "Items": [
        {
            "AdditionalFields": null,
            "Code": "NIQRPI0GTU",
            "ExternalReference": "",
            "LineItemReference": "7fe4770c0c95d44dec5c02ee1bc752b568b47808",
            "CrossSell": null,
            "Quantity": 2,
            "Price": {
                "Currency": "eur",
                "NetPrice": 169.88,
                "GrossPrice": 197.06,
                "NetDiscountedPrice": 169.88,
                "GrossDiscountedPrice": 197.06,
                "Discount": 0,
                "VAT": 27.18,
                "AffiliateCommission": 0,
                "UnitNetPrice": 84.94,
                "UnitGrossPrice": 98.53,
                "UnitVAT": 13.59,
                "UnitDiscount": 0,
                "UnitNetDiscountedPrice": 84.94,
                "UnitGrossDiscountedPrice": 98.53,
                "UnitAffiliateCommission": 0,
                "ItemUnitNetPrice": null,
                "ItemUnitGrossPrice": null,
                "ItemNetPrice": null,
                "ItemGrossPrice": null,
                "VATPercent": 16,
                "HandlingFeeNetPrice": 0,
                "HandlingFeeGrossPrice": 0
            },
            "PriceOptions": [],
            "ProductDetails": {
                "Name": "100 USD NET API Product",
                "ShortDescription": "<p>100 USD NET API Product<\/p>",
                "Tangible": false,
                "IsDynamic": false,
                "ExtraInfo": null,
                "RenewalStatus": false,
                "Subscriptions": null,
                "DeliveryInformation": {
                    "Delivery": "NO_DELIVERY",
                    "DownloadFile": null,
                    "DeliveryDescription": "",
                    "CodesDescription": "",
                    "Codes": []
                }
            },
            "Promotion": null,
            "PurchaseType": "PRODUCT",
            "RenewalInformation": null,
            "SKU": null,
            "SubscriptionStartDate": null,
            "Trial": null,
            "SubscriptionCustomSettings": null
        },
        {
            "AdditionalFields": null,
            "Code": "0XICS3OVDK",
            "ExternalReference": "",
            "LineItemReference": "7fe4770c0c95d44dec5c02ee1bc752b568b47808",
            "CrossSell": null,
            "Quantity": 1,
            "Price": {
                "Currency": "eur",
                "NetPrice": 96.83,
                "GrossPrice": 112.32,
                "NetDiscountedPrice": 96.83,
                "GrossDiscountedPrice": 112.32,
                "Discount": 0,
                "VAT": 15.49,
                "AffiliateCommission": 0,
                "UnitNetPrice": 96.83,
                "UnitGrossPrice": 112.32,
                "UnitVAT": 15.49,
                "UnitDiscount": 0,
                "UnitNetDiscountedPrice": 96.83,
                "UnitGrossDiscountedPrice": 112.32,
                "UnitAffiliateCommission": 0,
                "ItemUnitNetPrice": null,
                "ItemUnitGrossPrice": null,
                "ItemNetPrice": null,
                "ItemGrossPrice": null,
                "VATPercent": 16,
                "HandlingFeeNetPrice": 0,
                "HandlingFeeGrossPrice": 0
            },
            "PriceOptions": [],
            "ProductDetails": {
                "Name": "2nd API NET product",
                "ShortDescription": "<p>2nd API NET product<\/p>",
                "Tangible": false,
                "IsDynamic": false,
                "ExtraInfo": null,
                "RenewalStatus": false,
                "Subscriptions": null,
                "DeliveryInformation": {
                    "Delivery": "NO_DELIVERY",
                    "DownloadFile": null,
                    "DeliveryDescription": "",
                    "CodesDescription": "",
                    "Codes": []
                }
            },
            "Promotion": null,
            "PurchaseType": "PRODUCT",
            "RenewalInformation": null,
            "SKU": null,
            "SubscriptionStartDate": null,
            "Trial": null,
            "SubscriptionCustomSettings": null
        }
    ],
    "Promotions": [],
    "AdditionalFields": null,
    "BillingDetails": {
        "FirstName": "Customer First Name",
        "LastName": "Customer Last Name",
        "CountryCode": "de",
        "State": null,
        "City": "Bucharest",
        "Address1": "Example Street",
        "Address2": null,
        "Zip": "73331",
        "Email": "example@email.com",
        "Phone": null,
        "Company": null,
        "FiscalCode": null,
        "TaxOffice": null
    },
    "DeliveryDetails": {
        "FirstName": "Customer First Name",
        "LastName": "Customer Last Name",
        "CountryCode": "de",
        "State": null,
        "City": "Bucharest",
        "Address1": "Example Street",
        "Address2": null,
        "Zip": "73331",
        "Email": "example@email.com",
        "Phone": null,
        "Company": null
    },
    "DeliveryInformation": {
        "ShippingMethod": {
            "Code": null,
            "TrackingUrl": null,
            "TrackingNumber": null,
            "Comment": null
        }
    },
    "Affiliate": {
        "AffiliateCode": null,
        "AffiliateSource": null,
        "AffiliateName": null,
        "AffiliateUrl": null
    },
    "CustomParameters": null
}

Unit price information

Per Line Item, each product contains a Price object, with all relevant information for the product's price and taxes:  

Key name Type Description

Currency

String

The currency ISO 4217 code; This currency is used in all the price values for that product. Example: USD.

UnitNetPrice

Float

The value per product unit (quantity = 1), excluding sales tax/VAT. Discounts are not reflected in this price.

UnitGrossPrice

Float

Total value per product unit (quantity = 1), including sales tax/VAT.  Discounts are not reflected in this price.

UnitVAT

Int

Sales tax/VAT per product unit.

UnitNetDiscountedPrice

Float

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

UnitGrossDiscountedPrice

Float

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

VATPercent

Int

Percentage of VAT charged on the order.

VAT

Float

Value of VAT per order line.

Discount

Float

Value of the discounts per order line expressed in the payment currency.

NetDiscountedPrice

Float

The NetPrice value per order line, excluding sales tax/VAT, from which 2Checkout deducts discounts.

GrossDiscountedPrice

Float

Total costs shoppers incur per order line. This value includes sales tax/VAT, 2Checkout, and affiliate commissions, but 2Checkout deducts the value of any discounts.

Order price information

On order level, in the response object root level, you can find all relevant information for the order's price and taxes:

Key name Type Description

NetPrice

Float

Order value excluding sales tax/VAT.

GrossPrice

Float

Total order value, including sales tax/VAT. GrossPrice does not reflect any discounts.

NetDiscountedPrice

Float

The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts.

GrossDiscountedPrice

Float

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

Discount

Float

Value of the discounts for an order.

VAT

Float

Value of sales tax/VAT.

Integration test cases

  1. Create a simple product (be it a catalog product in the Control Panel, or a dynamic product), using a round number as the price (like 100) in order to be able to easily check the calculated taxes. 
  2. Using the getContents API call, build your checkout flow, and display the taxes as needed. 
  3. As an easy comparison, you can use a catalog product and generate a buy-link in ConvertPlus and compare the way the taxes are displayed.
  4. If needed, implement the currency switching in the checkout flow.  
  • Keep in mind that, where prices in other currencies are specified in the product catalog, they will be used instead of the prices automatically converted by 2Checkout. 

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