Skip to main content

Retrieve installment information

Overview

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

Supported payment methods

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

Parameters

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

Attributes Type/Description

InstallmentsOption

Array of objects

 

Details below.

 

Number

Int

 

 

Number of installments.

 

Amount

Double

 

 

Standalone installment value. (Total order value/Number of installments)

 

Currency

String

 

 

Order currency.

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 = "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 = "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);
 
$Order = new stdClass();
$Order->RefNo = null;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = null;
$Order->Source = null;
$Order->AffiliateId = null;
$Order->CustomerReference = null;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1; 
$Order->Items[0]->PriceOptions = null;
$Order->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 = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = null;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = null;
$Order->DeliveryDetails = null;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->Promotions = null;
$Order->AdditionalFields = null;
$Order->LocalTime = null;
$Order->GiftDetails = null;

$jsonRpcRequest = array (
'method' => 'getInstallments',
'params' => array($sessionID, $Order),
'id' => $i++,
'jsonrpc' => '2.0'
);
echo '<BR>';
echo 'The content of the current session:';
echo '<BR>';
$installments = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($installments);
?>

Place an order with installments

Overview 

Use the placeOrder method to create an order and collect the payment.

Supported payment methods 

Credit/Debit cards: Visa, MasterCard and AMEX local Brazilian cards.

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)

 

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

Requirements

  1. Payment methods: Visa, MasterCard and AMEX
  2. Country: Brazil
  3. Currency BRL
  4. Specified number of installments under the PaymentMethod object. (Minimum installment threshold is 5 BRL.)
    • Phone number
    • Fiscal code (CPF/CNPJ)
  5. Mandatory billing information must include:

  6. Transaction: non-recurring
  7. Installments are available only for:
    • Brazilian customers
    • Local Visa, MasterCard and AMEX cards
    • Non-recurring transactions


<?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 = "MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "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;
}
 
var_dump($sessionID);
 
$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->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 = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;
 
$Order->DeliveryDetails = NULL;
 
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
 
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;
 
 
try {
    $OrderInstallments = $client->getInstallments($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "Order_Installments: " . $e->getMessage();
    exit;
}
var_dump("Order_Installments", $OrderInstallments);

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1; 
$Order->Items[0]->PriceOptions = NULL;
$Order->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 = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->InstallmentsNumber = 2;
$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;
try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}
var_dump("newOrder", $newOrder);

 

Retrieve session content

Overview

Use the getContents method to get info on all the products added to cart by the shopper in the current session.

Products added in cart can be either defined in your catalog, or created with dynamic information.    

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)

 

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

Response

Parameters Type/Description
SessionContents 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'; // you can also send products with dynamic information
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = array();
$Order->Items[0]->PriceOptions[0] = new stdClass();
$Order->Items[0]->PriceOptions[0]->Options = array();
$Order->Items[0]->PriceOptions[0]->Options[0] = new stdClass();
//$Order->Items[0]->PriceOptions[0]->Options[0]->Value ="standarduniqueone";
$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 = 'CC';
$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'
);

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

 

 

Disable recurring billing

Overview

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

Parameters

Parameters Type/Description

sessionID

Required (string)

 

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

subscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

Response

Parameters Type/Description

Boolean

true or false depending on whether the changes were successful or not.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Add/Import test subscriptions without credit/debit card data

Overview

Import test subscription and data from your or a third-party system and test advanced renewal and upgrade scenarios in the Avangate platform. Contact Avangate directly for additional details.

Use the addSubscription method to import a test subscription into the Avangate system.

Requirements

Test subscriptions can be imported only for eStore orders. 

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.

Subscription import

Required (Object)

 

Object designed to provide Avangate with all the information to create a subscription.

Test Optional (integer)
  To add test subscriptions, set the Test parameter to 1. Default value is 0, and belongs to regular subscriptions.

Response

Parameters Type/Description

SubscriptionReference

String

 

Unique, system-generated subscription identifier.

Request

<?php

require ('PATH_TO_AUTH');

$Product = new stdClass ();
$Product->ProductCode = 'my_subscription_1';
$Product->ProductId = 4639321;
$Product->ProductName = 'Avangate Subscription Imported';
$Product->ProductVersion = 1.0;
$Product->ProductQuantity = 3;
$Product->PriceOptionCodes = array();

$EndUser = new stdClass ();
$EndUser->Address1 = 'Address line 1';
$EndUser->Address2 = 'Address line 2';
$EndUser->City = 'LA';
$EndUser->Company = 'Company Name';
$EndUser->CountryCode = "US";
$EndUser->Email = 'customerAPI@avangate.com';
$EndUser->FirstName = 'Customer';
$EndUser->Language = 'en';
$EndUser->LastName = 'Avangate';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Fax = NULL;
$EndUser->Zip = '90210';

$Subscription = new stdClass();
$Subscription->ExternalSubscriptionReference = '12345678912ImportedSubscription';
$Subscription->SubscriptionCode= NULL;
$Subscription->StartDate = '2013-01-01';
$Subscription->ExpirationDate = '2017-12-30';
$Subscription->Product = $Product;
$Subscription->EndUser = $EndUser;
$Subscription->ExternalCustomerReference = '12354678ExtCustRef';
$Subscription->Test = 1; // send 1 for test subscription, 0 for regular subscriptions.

try {
    $importedSubscriptionNoPayData = $client->addSubscription($sessionID, $Subscription);
}
catch (SoapFault $e) {
    echo "importedSubscriptionNoPayData: " . $e->getMessage();
    exit;
}
var_dump("importedSubscriptionNoPayData", $importedSubscriptionNoPayData);

Use Checks

Overview 

Place an order using catalog products, and collect the payment using Check.

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)

 

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

 

Workflow 

  1. Customer places the order using Check as payment option.
  2. After order is confirmed, customer receives the payment instructions via e-mail, including the address to which the check should be sent.
  3. Order is finalized as soon as the payment is confirmed into 2Checkout's bank account.

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 = 'customer@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = 'ABC Company';
$Order->DeliveryDetails = NULL;


$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CHECK';
$Order->PaymentDetails->Currency = 'USD';
$Order->PaymentDetails->PaymentMethod = new stdClass ();

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

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

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

Retrieve VAT or sales tax

Overview

Use the getContents method to calculate the tax charge based on current session contents. Follow the steps below to learn how you can retrieve the VAT or sales tax amount:

  1. Populate the Order object with information. 2Checkout 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. 2Checkout 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

Parameters Type/Description

SessionContents

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

Retrieve the history of a subscription

Overview

Retrieve information on the evolution of a subscription in the Avangate system, including details of the initial acquisition and the subsequent renewals and upgrades. Use the getSubscriptionHistory method to retrieve details about a subscription. 

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

Parameters

Parameters Type/Description

sessionID

Required (string)

 

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

subscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

Response

Parameters Type/Description

SubscriptionHistory

Object

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Payment flow with Credit Cards with Installments

Overview

The following payment methods are supported for the payment flow with credit cards with installments: local cards with installments for Turkey (Bonus, World, CardFinans, BankAsya, Paraf, Maximum, Axess) & Brazil (Elo card, Hipercard).

Availability

Available for all 2Checkout accounts.

Requirements

The functionality for orders with installments needs to be enabled for your 2Checkout account. Please contact 2Checkout for activation. 

How payments with installments work

Installments are available for Brazilian and Turkish shoppers with local Visa, MasterCard, or AMEX cards for non-recurring transactions.

The minimum installment threshold is 5 BRL/TRY. The maximum number of installments is 6.

Mandatory information for payments also includes a shopper phone number and Fiscal Code (CPF/CNPJ).

In order to validate the number of installments, before placing the order, an API call must be made to getInstallments (on SOAP and JSON-RPC) or GET/orders​/0​/installments​/ (on REST). 

The getInstallments method receives as an input the same input as the placeOrder method, and will return the number of installments and their value:

{
  "0": {
    "Amount": "384.45",
    "Currency": "BRL",
    "Number": "1"
  },
  "1": {
    "Amount": "192.23",
    "Currency": "BRL",
    "Number": "2"
  },
  "2": {
    "Amount": "128.15",
    "Currency": "BRL",
    "Number": "3"
  },
  "3": {
    "Amount": "96.11",
    "Currency": "BRL",
    "Number": "4"
  },
  "4": {
    "Amount": "76.89",
    "Currency": "BRL",
    "Number": "5"
  },
  "5": {
    "Amount": "64.08",
    "Currency": "BRL",
    "Number": "6"
  }
}

Payment method Object structure

Field name Type Required/Optional Description

Phone Number

String

Required

Shopper phone number.

Fiscal Code

String

Required

For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

CardNumber 

String

Required

The card number.

CardType 

String

Optional

Can be Visa, Visa electron, Mastercard, Maestro, Amex, Discover, Dankort, Carte Bancaire, JCB, Hipercard, Elo card

ExpirationYear 

String

Required

Card expiration year.

ExpirationMonth 

String

Required

Card expiration month.

CCID 

String

Required

The CVV/card security code.

HolderName 

String

Required

Card holder name.

InstallmentsNumber

Int

Optional

Number of installments. Available only when customers in Brazil or Turkey pay with Visa or MasterCard using Brazilian Real or Turkish Lira as the order currency.

Use 1 or exclude the parameter for full payments. 

Vendor3DSReturnURL 

String

Required

URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.

Vendor3DSCancelURL 

String

Required

URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.

RecurringEnabled

Boolean

Optional

True or False, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.

 Request example

The full JSON used to place an order with credit cards would look like:

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

The API will respond with the full order object (for orders placed successfully) or an error message.

Notes on orders with installments

  • The 2Checkout payout for the full order value, regardless of the number of installments (this is covered directly by the banks). 

Integration test cases

Using the test credit cards available here, follow the next steps:

  1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API, the response contains an order object (order was placed successfully).
  2. Handle the 3DS flows, both when 3DS is mandatory (and the shopper needs to be redirected to authorize the transaction), as well as where this is not needed (order is created with status AUTHRECEIVED or COMPLETE).
  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. 

 

Use PayPal

Overview

Place an order using catalog products defined in your Control Panel, and collect the payment using PayPal.

Currency support

Check with 2Checkout support for a list of currencies available for PayPal. 

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)

 

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

To place an order with PayPal rather than PayPal Express, use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. See code sample

Workflow

  1. Create the order object. Use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. Place the order.
  2. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING. 2Checkout responds with the Order information object.
  3. Redirect shoppers to the RedirectURL from the Order information object you receive as a response from 2Checkout.
  4. Once shoppers log into their PayPal account and complete the transaction, they're redirected to the ReturnURL you set in the order object. 2Checkout also authorizes the order and updates the status to AUTHRECEIVED. 

Response

Parameters Type/Description

Order information

Object

  Object containing order information.

 

<?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 = 'Test API';
$Order->BillingDetails->LastName = 'API';
$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 = 'email@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'PAYPAL';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '91.220.121.21';
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'http://yoururl.com';
$Order->PaymentDetails->PaymentMethod->Email= 'email@2checkout.com';

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

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

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