Skip to main content

Retrieve subscription payment information

Overview

Use the getSubscriptionPaymentInformation method via SOAP 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 = "YOUR_SUBSCRIPTION_REFERENCE";

try {
    $paymentInformation = $client->getSubscriptionPaymentInformation($sessionID, $subscriptionReference);
} catch (SoapFault $e) {
    echo  $e->getMessage();
}
var_dump($paymentInformation);

 

Place orders via API using a 2Pay.js token

Overview

You can use a 2Pay.js token to place orders via APIv6 by following the flow below.

How to use a 2Pay.js token

Placing orders using 2Pay.js tokens in API works like a normal credit card order. Once a token has been obtained using the 2Pay.js library, this can be used to place an order by using API version 6.

In order to do this, the payment type used in the payment details of the placeOrder call must be EES_TOKEN_PAYMENT and the token must be specified in the payment method object.

Place an order with 2Pay.js Token example

{
  "Country": "br",
  "Currency": "brl",
  "CustomerIP": "91.220.121.21",
  "CustomerReference": "GFDFE",
  "ExternalCustomerReference": "IOUER",
  "ExternalReference": "REST_API_AVANGTE",
  "Language": "en",
  "Source": "testAPI.com",
  "Affiliate": {},
  "BillingDetails": {
    "Address1": "Test Address",
    "City": "LA",
    "CountryCode": "BR",
    "Email": "customer@2Checkout.com",
    "FirstName": "Customer",
    "FiscalCode": "056.027.963-98",
    "LastName": "2Checkout",
    "Phone": "556133127400",
    "State": "DF",
    "Zip": "70403-900"
  },
  "Items": [
    {
      "Code": "my_subscription_1",
      "Quantity": "1"
    }
  ],
  "PaymentDetails": {
    "Currency": "BRL",
    "CustomerIP": "91.220.121.21",
    "PaymentMethod": {
      "EesToken": "7b88d2cf-6121-4cac-90a1-8eefc4cb3e6e",
      "Vendor3DSReturnURL": "www.test.com",
      "Vendor3DSCancelURL": "www.test.com"
    },
    "Type": "EES_TOKEN_PAYMENT"
  }
}

Place a test order with 2Pay.js token example

To place a test order with 2Pay.js token, use the above code sample and simply replace the value of the TYPE parameter with "Type": "TEST".

Response errors

If a token is invalid, then an HTTP 400 response containing the INVALID_EES_TOKEN error code is returned. In this case, a new token must be generated via the 2Pay.js library.

Once payment is placed successfully, then the standard processing flow of any credit card payment will continue. For transactions that require 3D Secure for authorization, the standard flow needs to be followed; this can be found here.

How to use a 2Pay.js token with API 3D Secure

  1. When placing an order via API 3D Secure, the Return and Cancel URLs must be provided​.
  2. Once the order is placed successfully, the response provides the URL where the shopper needs to be redirected (the redirect URL must be built from the base URL + the provided list of parameters as a GET request)​
  3. Once the 3D Secure step is fulfilled, the shopper is redirected to the 3D Secure Return parameter specified when placing the order​.

Recurring Payments and 1-Click Purchases with 2Pay.js Token

Recurring payments and 1-click purchases with previous order references are available​ when using the 2Pay.js token.

​Recurring payment​

Recurring payments for an order are enabled in the same way as for credit card orders​.

$CartObj->PaymentDetails->PaymentMethod->RecurringEnabled = true;

1-Click Purchase​

1-click purchase is supported out of the box​. An order paid via a 2Pay.js token works just like a regular credit card order.

$CartObj->PaymentDetails->Type = "PREVIOUS_ORDER";
$CartObj->PaymentDetails->PaymentMethod->RefNo = "11658744";

Assign a subscription to another customer

Overview

Use the setSubscriptionCustomer method. 2Checkout moves subscription under the customer for which you provide the 2Checkout customer reference or the External customer reference during the subscription update process.

json_diagram.png

Requirements

To move a subscription from a source customer to a target customer:

  • Use 2Checkout customer references or External customer references belonging to the target customer. 2Checkout re-assigns the subscription to the target customer. 
  • Customer references must be valid and associated to the target customer entity under which you move the subscription.
  • If you provide both the 2Checkout customer reference and External customer reference they need to belong to the same target customer entity.

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.

2CheckoutCustomerReference

Required (int)

 

System-generated customer reference. Required unless you prefer to use ExternalCustomerReference.

ExternalCustomerReference

Optional (string)

 

External customer reference that you control. Optional when you use 2CheckoutCustomerReference. If you include it, it needs to belong to the same customer as the 2CheckoutCustomerReference.

Response

Boolean

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

Request


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

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

 

Use custom pricing

Overview

Place an order with on the fly pricing using catalog products defined in your Control Panel. Set the Items→Price→Type parameter to CUSTOM, while adding the dynamic price to the Items→Price→Amount parameter.

Payment methods

You can place orders with dynamic pricing using the following payment methods:

  • Credit cards
  • PayPal
  • WeChat Pay
  • iDEAL
  • Purchase Order

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

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]->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->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Amount = 11; // set the price of the order
$Order->Items[0]->Price->Type = 'CUSTOM'; // must be sent as CUSTOM in order to use dynamic pricing

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

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC'; // you can also use TEST, PAYPAL, PURCHASEORDER, WE_CHAT_PAY, IDEAL, CHECK. The flow and requirements are different for each payment method.
$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->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);

 

Upgrade subscription

Overview

Use the setSubscriptionUpgrade method to upgrade a subscription.

Requirements

You can only upgrade subscriptions with automatic renewal enabled.

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.

productCode

Required (string)

 

Unique identifier of the target product for the subscription upgrade process. You control the product code and can set it up in the Control Panel.

options

Optional (string)

 

Pricing options of the target product for the subscription upgrade process.

 

String - ';' separated list of 'OptionValue' returned by getProductUpgradeOptions function.

If the pricing options groups is "scale" (interval), the Options parameter should be sent like this: [option group unique code] + "=" + value

e.g. Users=7

customPrice

Optional (string)

 

The price you want to charge customers for the upgrade. The currency used by default is the same as in the previous payment customers made.

Response

Parameters Type/Description

Boolean

true or false depending on whether or not the operation succeeded.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$productCode = 'YOUR_PRODUCT_CODE';
$options = 'YOUR_PRICE_CODES'; //case sensitive; include only price options codes (exclude spaces)
$customPrice = 1;

$jsonRpcRequest = array (
'method' => 'setSubscriptionUpgrade',
'params' => array($sessionID, $subscriptionReference, $productCode, $options, $customPrice),
'id' => $i++,
'jsonrpc' => '2.0');

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

Retrieve session content

Overview

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

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

OrderContents

Object

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 = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
 
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 = '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;
try {
    $CartContents = $client->getContents    ($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "CartContents: " . $e->getMessage();
    exit;
}
var_dump("CartContents", $CartContents);
?>

 

Use Bank transfers

Overview

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

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

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 = 'Test Cosmin API';
$Order->BillingDetails->LastName = 'Cosmin 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 = 'john.doe@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'WIRE';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();

$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 contents with Prefill

Overview

Use the getContentsWithPreFill method to get info on all the products added to the cart by the shopper in the current session, while pre-filling the customer information based on the subscription reference.

Products added in the 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.

SubscriptionReference Required (String)
  Unique subscription identified, generated by 2Checkout.

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 = 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]->RenewalInformation = new stdClass();
$Order->Items[0]->RenewalInformation->SubscriptionReference = '63A6FE10AD'; // subscription based on which the customer information is pre-filled

$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->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

 

Retrieve upgrade price

Overview

Use the getProductUpgradeOptionsPrice method to retrieve information about the costs a customer incurs when upgrading a specific subscription. Retrieve information about the costs a customer incurs when upgrading a specific subscription.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

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

subscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

productCode

Required (string)

 

Unique identifier of the target product for the subscription upgrade process. You control the product code and can set it up in the Control Panel.

currency

Required (string)

 

ISO 4217 code.

options

Required (string)

 

Pricing options of the target product for the subscription upgrade process.

 

String - ';' separated list of 'OptionValue' returned by getProductUpgradeOptions function.

If the pricing options groups is "scale" (interval), the Options parameter should be sent like this: [option group unique code] + "=" + value

e.g. Users=7

Response

Parameters Type/Description

UpgradePrice

Object

    Details below.
  BillingPrice Int
    Net billing price available for  the upgrade process.
  BillingGrossPrice Int
    Gross billing price available for  the upgrade process.
  BillingCurrency String
    Billing currency available for the upgrade process.
  Quantity String
    Quantity available for the upgrade process.
  DisplayPrice Int
    Net display price available for the upgrade process.
  DisplayGrossPrice Int
    Gross display price available for the upgrade process.
  DisplayCurrency String
    Display currency available for the upgrade process.
  Discount     Float
    Applied discounts
  DiscountedProratedPrice Float
    Prorated net price for the upgrade with applied discounts
  DiscountedProratedGrossPrice     Float
    Prorated gross price for the upgrade with applied discounts
  DiscountedBillingPrice     Float
    Net billing price available for  the upgrade process with applied discounts
  DiscountedBillingGrossPrice     Float
    Gross billing price available for  the upgrade process with applied discounts
  DisplayDiscount     Float
    Discount displayed for the upgrade process
  DiscountedDisplayPrice Float
    Net display price available for the upgrade process with applied discounts
  DiscountedDisplayGrossPrice     Float
    Gross display price available for the upgrade process with applied discounts

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$productCode = 'my_subscription_123';
$currency = 'usd';
$options = 'emailsupport;oneuser1';

$jsonRpcRequest = array (
'method' => 'getProductUpgradeOptionsPrice',
'params' => array($sessionID, $subscriptionReference, $productCode, $currency, $options),
'id' => $i++,
'jsonrpc' => '2.0');

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

 

 

Place orders with dynamic product information

Overview

Use this object to create new orders and collect payments from shoppers using products with dynamic information. 

Purchase types available are PRODUCT, TAX, SHIPPING, and COUPON. The surcharge defined in the pricing option is used for calculating the order renewal price, when applicable.

For more details about how to be PCI compliant before accepting CC payments, see this page.

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
  3. Free orders (no payment information required).

How to test?

Place test orders with dynamic product information by following the instructions from this article.

Requirements

The product code must be sent as null. The order currency must match with the payment currency otherwise, an error is thrown. The isDynamic parameter of the Items object must be true.

For credit card orders placed using API 5.0 or newer versions, you need to pass through additional parameters that support the 3D Secure flow. 3D Secure works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or password to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with customers having to go through an extra layer of authentication.

Send the following parameters as part of the PaymentMethod object:

Parameters Description
Vendor3DSReturnURL Required (string)
  URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
Vendor3DSCancelURL Required (string)
  URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.

Limitations



Placing an order with both catalog and dynamic product information is not possible. Recurring options can be set only for purchase type PRODUCT and TAX.

Parameters

Parameters Type/Description

Currency

Optional (string)

 

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

Country

Optional (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 into 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.

CustomerReference

Optional (Int)

 

External customer ID you can attach to the customer.

MachineId

Optional (string)

 

Unique, system generated code for each unique customer, identifying returning customers.

Items

Required (array of objects)

 

 

 

Details below. 

 

 

Code

Optional (string)

 

 

 

Should be sent as NULL. Any other value is ignored.

 

 

Quantity

Required (integer)

 

 

 

Number of units purchased.

  ProductExternalReference Optional (string)
  isDynamic Required (bool)
    Send TRUE for orders with dynamic product information.
  Tangible Required (bool)
   

Possible values:

  • FALSE for products delivered electronically.
  • TRUE for tangible products, that require physical delivery.
  PurchaseType Required (string)
   

Purchase types available are:

  • PRODUCT - Item purchased by the customer. Is mandatory to send the name and price of the product item. Can also have pricing options and recurring options attached.
  • TAX - additional handling fee added to the purchase.
  • SHIPPING - shipping fee applied to purchase.
  • COUPON - amount deducted from total order price. Send positive values.
  PriceOptions Optional (array of objects)
    Array of price option groups.
    Name   Optional (string) 
        Name of the pricing option group.
    Options   Optional (array of objects)
        Array of pricing options.
    Name Optional (string)
      Pricing option name. 
    Value Optional (string)
      Pricing option code. 
    Surcharge Optional (double)
      Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order. 
  RecurringOptions Optional (Object)
      Contains recurring options.
    CycleLength Optional (int)
      The length of the recurring billing cycle.
    CycleUnit Optional (string)
      Unit of measuring billing cycles (years, months).
    CycleAmount Optional (int)
      The amount to be billed on each renewal.
    ContractLength Optional (int)
      The contact length for which the recurring option will apply.
    ContractUnit Optional
      Unit of measuring contact length (years, months).
  Name   Required (String)

 

 

Price

Required (Object)

    Details below.
    Amount Required (Int)
      Amount of the product.
    Type Optional (string)
      Send "CUSTOM" for dynamic pricing.

 

 

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

        Details below
        Code Optional (string)
          Identifier code for the additional field.
        Text Optional (string)
          Text displayed in the additional field.
        Value Optional (string)
          Additional 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.

BillingDetails

Required (Object)

 

 

Details below. 

 

Person

Object

 

 

 

             

Details below. 

 

 

FirstName

Required (string)

 

 

 

             

Shopper name.

 

 

LastName

Required (string)

 

 

 

             

Shopper surname.

 

 

CountryCode

Optional (string)

 

 

 

             

Shopper country. ISO 3166 two-letter code.

 

 

State

Optional (string) – Required for US, Turkey, India and Romania

 

 

 

             

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

 

 

City

           

Optional (string)

 

 

 

             

Shopper city.

 

 

Address1

Optional (string)

 

 

 

             

Shopper address.

 

 

Address2

Optional (string)

 

 

 

             

Shopper address.

 

 

Zip

             

Optional (string)

 

 

 

             

ZIP/ Postal code.

 

 

Email

Optional (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).

Mandatory when you set India as the Billing Country, and purchase is made by a Company.

• 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, Turkey, and Romania

 

 

 

             

The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Turkey, 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.

DeliveryInformation

Object / Optional

For products that require physical delivery, use this object to send the shipping method.

    ShippingMethod          

Object

Details below

        Code         String
  System-generated identified for your shipping method configuration.

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.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.

 

 

Currency

Optional (string)

 

 

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

 

PaymentMethod

Optional (object)

                                                          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.

 

 

Object structure and parameters differ according to 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.

 

 

 

CardPayment

Optional (object)

 

 

 

 

 

Details below. 

 

 

 

 

CardNumber

Required (string)

 

 

 

 

 

The credit/debit card number.

 

 

 

 

CardType

Required (string)

 

 

 

 

 

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

 

 

 

 

ExpirationYear

Required (string)

 

 

 

 

 

The year in which the card expires.

 

 

 

 

ExpirationMonth

Required (string)

 

 

 

 

 

The month in which the card expires.

 

 

 

 

HolderName

Required (string)

 

 

 

 

 

Card holder name.

        Vendor3DSReturnURL Required (string)
          URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
        Vendor3DSCancelURL Required (string)
          URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.

 

 

 

 

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 enter 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. 

 

CustomerIP

Required (string)

 

 

Shopper IP.

Promotions Optional (Array of strings)
  Array of promotion codes.

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.

 

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