| Verifone Developer Portal

Subscription renewal

Overview

Use this section to handle the renewal of your subscriptions.

You can retrieve information regarding the renewal status of a subscription, including the manual renewal link that a customer needs to access in order to renew.

Enable or disable the recurring billing for a subscription using the API methods displayed below.

A/B testing campaigns for shopping cart templates

Overview

Set up A/B testing campaigns for shopping cart templates to identify the best converting template.

Requirements & limitations

Parameters sent through buy links will overwrite campaigns variables. The A/B testing campaigns will not trigger if the buy link contains a parameter that overwrites an experiment variable.

When generating buy links in the platform via the Generate Links section, you'll notice that selecting a specific order template from the additional options area adds an extra parameter in the URL such as: &ORDERSTYLE=nLW45ZS5kH4=

When links with ORDERSTYLE parameters are used, they override A/B testing campaign variables. While shoppers will be able to complete the purchase without any issues, their order will not be registered as a part of the Shopping Cart Templates A/B test.

What you need to do is to make sure that the links used point directly to https://secure.2checkout.com/order/checkout.php.

For example, if the link you generated for a product looks like this:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&QTY=1&CART=1&ORDERSTYLE=nLW0npaphH4=, then remove&ORDERSTYLE=nLW0npaphH4= to make sure that customers using the link to order will provide data for the Shopping Cart Templates A/B test. In this case, you would need to use this link:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&QTY=1&CART=1

Important

When the shopper places the order, the test is considered successful regardless of the order or payment status.

Setup

Go to the A/B Testing page and click the Overview tab.
Click New campaign in the Shopping cart templates section. If you already have an unfinished campaign, click Edit.
Fill in the details of the new campaign, such as the campaign name, maximum number of tests and the date when the campaign should end.
Add the test variations by allocating traffic to each of them and selecting the desired cart template from the drop-down menu.
Click Add variation.
Repeat steps 4 and 5 until you have used the entire available traffic.
Click Save campaign.
Go back to the Overview tab and click Start Campaign when you want the campaign to begin.

Retrieve pricing list information

Overview

Get the extended info about the pricing list available for a partner, including the products and their pricing options, based on the pricing list code.

Requirements

Parameters

Parameter	Type/Description
sessionID	Required (string)
	Session identifier, which is the output of the Login method. An exception will be thrown if the values are incorrect
pricingListCode	Required (string)
	The unique identifier of the pricing list.

Response

Parameter	Type/Description
PricingList	Object

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner

$pricingListCode = 'EFBECC428A';

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

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

Error

Error	Description
INVALID_PARTNER	No partner is set.
PARTNER_PRICING_LISTS_NOT_FOUND	There are no pricing lists with provided code.

Retrieve a customer

Overview

Use the getCustomerInformation method to retrieve the details of a customer entity from the 2Checkout system.

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

Customer

Object

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;
}
$customerReference = 298084139;
$externalCustomerReference = 'Apitest123456'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference
try {
    $customerInfo = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}
catch (SoapFault $e) {
    echo "customerInfo: " . $e->getMessage();
    exit;
}
var_dump("customerInfo", $customerInfo);

Retrieve customer

Overview

Use the getCustomerInformation method to retrieve the details of a customer entity from the 2Checkout system.

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.
CustomerReference	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 CustomerReference. If you include it, it needs to belong to the same customer as the CustomerReference.

Response

Parameters	Type/Description
Customer	Object

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXT_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference


try {
    $customerInfo = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}
catch (SoapFault $e) {
    echo "customerInfo: " . $e->getMessage();
    exit;
}
var_dump("customerInfo", $customerInfo);

Additional fields

Overview

This object is returned directly or within a successful response from the following API requests:

Retrieve an additional field Retrieve assigned additional fields Retrieve all additional fields

Additional fields object

Parameters	Object
Label	String
	Field text.
Code	String
	Field identifier. Alpha-numeric chars, underscores and dashes.
Type	String
	Field type: LISTBOX CHECKBOX TEXT HIDDEN
ApplyTo	Sting
	ORDER PRODUCT
Values	Array of values
	Custom values you control.
ValidationRule	String
	The validation rule restricting the type of information shoppers can enter in the additional field during the purchase process.
Translations	Array of objects
	Details below.
Label	String
	Field text translated in the language of the Translations object.
Values	Object
	Custom values you control translated in the language of the Translations object.
Language	String
	ISO language code. (ISO 639-1 two-letter code).

Subscription upgrade

Overview

The object below is returned directly or within a successful response from the following API requests:

Retrieve upgrade options

Subscription upgrade object

Parameters			Type/Description
ProductInfo			Object
			Details below.
	ProductId		Int
			Unique, system-generated product identifier belonging to the upgrade product.
	ProductCode		String
			Unique product identifier that you control belonging to the upgrade product.
	ProductName		String
			Product name
	ProductVersion		String
			The product version number that you control.
	ProductEnabled		Boolean
			Possible values: 0 – You disabled this product. 1 – You enabled this product.
	ProductType		String
			REGULAR or BUNDLE
	Currency		String
			The currency for prices. The currency ISO code used for the payment - ISO 4217.
	DefaultCurrency		String
			The product's default currency which is set in the Control Panel. The currency ISO code to be used for the payment - ISO 4217.
	Price		Double
			Product price. Can be null for flat pricing schemes. You need to call getPrice with Quantity, Currency and Price Options parameters to get a valid price.
	GiftOption		String
			True or false depending on whether the product can be gifted or not.
	IdGroup		Int
			Product Group ID number.
	GroupName		String
			The name of the Product Group.
	ShortDescription		String
			The product's short description.
	ProductImage		String
			URLs to the product images uploaded into the Avangate platform.
	Languages		Array of strings
			Array of ISO language codes for the product - ISO 639-1.
	PriceIntervals		Array of objects
			Pricing intervals.
	PriceType		String
			NET or GROSS
	PriceSchema		String
			FLAT or DYNAMIC
Quantity			Int
			Number of units available for the upgrade order.
PriceOptions			Array of objects
			Details below.
	Id		String
			Pricing options ID.
	Name		String
			Pricing options group name.
	Description		String
			The description of the Pricing options group
	Required		Boolean
			True or False depending on whether you set the Pricing options group asrequired or not.
	Type		String
			Pricing options group type: COMBO CHECKBOX RADIO INTERVAL
	Options		Array of objects
			Details below.
		Name	String
			The name of the option inside the Pricing options group
		Value	String
			The code of the option inside the Pricing options group
		Default	Boolean
			True or false.
		Description	String
			The description of the option inside the Pricing options group.
		MinValue	Int
			Start value of a scale interval.
		MaxValue	Int
			End value of a scale interval.

Order session content object

Overview

Use this object to retrieve session content and to guide shoppers through advanced payment flows, such as those of PayPal, PayPal Express, Wire, Check, etc.

Attributes

Order session contents				Type/Description
Errors				Optional (StringArray)
				Payment gateway processing errors.
Items					Array of objects
					Details below.
	ProductDetails				Object
					Details below.
		Name			Optional (string)
					Product name.
		ExtraInfo			Optional (string)
					The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.
		RenewalStatus			Optional (boolean)
					true for orders renewing subscriptions. false for all other orders: new purchases, upgrades.
		Subscriptions			Object
					Details below.
			SubscriptionReference		Optional (string)
					Unique, system-generated subscription identifier.
			PurchaseDate		Optional (string)
					The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the Avangate system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00. e.g. 2015-08-11 15:18:52
			SubscriptionStartDate		Optional (string)
					Example: 2015-09-29 17:57:59
			ExpirationDate		Optional (string)
					The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00. e.g. 2015-09-11 15:18:52
			Lifetime		Optional (boolean)
					true – For non-recurring, evergreen subscriptions. false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.
			Trial		Optional (boolean)
					true – For trial subscriptions. false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.
			Enabled		Optional (boolean)
					true – For active and past due subscriptions. false – For expired and cancelled subscriptions.
			RecurringEnabled		Optional (boolean)

	PriceOptions				Optional (Array of strings)
					Product price options.
	Price				Object
					This object returns the price per unit at order line level. In the case of trials, the object returns the costs for the trial to full subscription conversion.
		UnitNetPrice			Optional (double)
					The value per product unit, excluding sales tax/VAT expressed in the payment currency.
		UnitGrossPrice			Optional (double)
					Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
		UnitVAT			Optional (double)
					Sales tax/VAT per product unit expressed in the payment currency.
		UnitDiscount			Optional (double)
					Value of the discount per product unit expressed in the payment currency.
		UnitNetDiscountedPrice			Optional (double)
					The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which Avangate deducts the unit discount.
		UnitGrossDiscountedPrice			Optional (double)
					Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.
		UnitAffiliateCommission			Optional (double)
					Value of the affiliate commission per product unit calculated expressed in the payment currency. Avangate deducts discounts from the costs incurred by shoppers before calculating affiliate commissions. Avangate does not take into account shipping costs when calculating affiliate commissions. NULL when Avangate does not apply an affiliate commission.
		Currency			Optional (string)
					The currency ISO code for the payment - ISO 4217. Example: usd.
		NetPrice			Optional (double)
					The value per order line, excluding sales tax/VAT expressed in the payment currency.
		GrossPrice			Optional (double)
					Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
		NetDiscountedPrice			Optional (double)
					The NetPrice value per order line, excluding sales tax/VAT, from which Avangate deducts discounts. NetDiscountedPrice is expressed in the payment currency.
		GrossDiscountedPrice			Optional (double)
					Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts. Example: UnitNetPrice: 99 UnitGrossPrice: 120.39 UnitVAT: 21.39 UnitDiscount: 9.9 UnitNetDiscountedPrice: 89.1 UnitGrossDiscountedPrice: 110.49 UnitAffiliateCommission: 22.28 Currency: "usd" NetPrice: 198 GrossPrice: 240.77 NetDiscountedPrice: 178.2 GrossDiscountedPrice: 220.97 Discount: 19.8 VAT: 42.77 AffiliateCommission: 44.56
		Discount			Optional (double)
					Value of the discounts per order line expressed in the payment currency.
		VAT			Optional (double)
					Value of sales tax/VAT per order line expressed in the payment currency.
		AffiliateCommission			Optional (double)
					Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions.
	Code				Optional (string)
					Unique product identifier your control. Max length 256 characters.
	Quantity				Optional (integer)
					Number of units
	SKU				Optional (string)
					SKU identifier.
	CrossSell				Optional (Object)
					Details below.
		ParentCode			Optional (string)
					The product code of the master product you set to trigger the campaign.
		CampaignCode			Optional (string)
					Unique, system-generated identifier for cross-sell campaigns.
	Trial				Optional (Object)
					Details below.
		Period			Optional (integer)
					The length of the trial subscription lifetime in days.
		GrossPrice			Optional (double)
					Total trial price in the payment currency before Avangate deducts any taxes, discounts, etc.
		VAT			Optional (double)
					The total value of taxes for the trial in the payment currency, before Avangate deducts any discounts.
		NetPrice			Optional (double)
					Total trial price in the payment currency, not including taxes, before Avangate deducts any discounts.
	AdditionalFields				Optional (array of objects)
					Details below.
		Code			Optional (string)
					The alpha-numeric characters, underscores and dashes that are set as the field identifier.
		Text			Optional (string)
					Field text visible to shoppers in the cart.
		Value			Optional (string)
					Selected field value.
	Promotion				Optional (object)
					Details below.
		Name			Optional (string)
					Promotion name.
		Description			Optional (string)
					Promotion description.
		StartDate			Optional (string)
					The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
		EndDate			Optional (string)
					The date when you set the promotion to end. NULL for promotions you want active indefinitely.
		MaximumOrdersNumber			Optional (integer)
					Avangate only applies the promotion to a maximum number of orders you define. Can be NULL if you want the promotion to apply to an unlimited number of orders.
		MaximumQuantity			Optional (integer)
					Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
		InstantDiscount			Optional (boolean)
					The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
		Coupon			Optional (string)
					Promotion coupon/voucher.
		DiscountLabel			Optional (string)
					Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.
		Enabled			Optional (string)
					true or false, depending on whether a promotion is active or disabled.
		Type			Optional (string)
					REGULAR – product/cart line level discounts. ORDER – quantity discounts. GLOBAL – order-level discounts.
Promotions					Optional (Array of objects)
					Details below.
	Name				Optional (string)
					Promotion name.
	Description				Optional (string)
					Promotion description.
	StartDate				Optional (string)
					The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
	EndDate				Optional (string)
					The date when you set the promotion to end. NULL for promotions you want active indefinitely.
	MaximumOrdersNumber				Optional (integer)
					Avangate only applies the promotion to a maximum number of orders you define. Can be NULL if you want the promotion to apply to an unlimited number of orders.
	MaximumQuantity				Optional (integer)
					Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
	InstantDiscount				Optional (boolean)
					The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
	Coupon				Optional (string)
					Promotion coupon/voucher.
	DiscountLabel				Optional (string)
					Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.
	Enabled				Optional (string)
					true or false, depending on whether a promotion is active or disabled.
	Type				Optional (string)
					REGULAR – product/cart line level discounts. ORDER – quantity discounts. GLOBAL – order-level discounts.
AdditionalFields					Optional (array of objects)
					Details below.
	Code				Optional (string)
					The alpha-numeric characters, underscores and dashes that are set as the field identifier.
	Text				Optional (string)
					Field text visible to shoppers in the cart.
	Value				Optional (string)
					Selected field value.
Currency					Optional (string)
					The currency ISO code for the payment - ISO 4217. Example: usd.
NetPrice					Optional (double)
					Order value excluding sales tax/VAT expressed in the payment currency.
GrossPrice					Optional (double)
					Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.
NetDiscountedPrice					Optional (double)
					The NetPrice order value excluding sales tax/VAT, from which Avangate deducts discounts. NetDiscountedPrice is expressed in the payment currency.
GrossDiscountedPrice					Optional (double)
					Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts. For example: Currency: "usd" NetPrice: 396 GrossPrice: 486.29 NetDiscountedPrice: 376.2 GrossDiscountedPrice: 466.49 Discount: 19.8 VAT: 90.29 AffiliateCommission: 94.05
Discount					Optional (double)
					Value of the discounts for an order expressed in the payment currency.
VAT					Optional (double)
					Value of sales tax/VAT expressed in the payment currency.
AffiliateCommission					Optional (double)
					Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions.

Retrieve order fields

Overview

Use the getAdditionalOrderFields method to extract information about additional fields you set up for your account.

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.

Request

<?php

require ('PATH_TO_AUTH');

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

?>

Response

Parameters	Type/Description
AdditionalFields	Array of orders

Subscription history

Overview

The object below is returned directly or within a successful response from the following API requests:

Retrieve subscription history

Subscription history object

Parameters	Type/Description
ReferenceNo	String
	Unique, system-generated order reference number.
Type	String
	Purchase type: SALE RENEWAL UPGRADE
SubscriptionReference	String
	Unique, system-generated subscription reference.
StartDate	String
	Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration.
ExpirationDate	String
	Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration.
Lifetime	Boolean
	Possible values: True – the subscription is evergreen False – the subscription has a recurring billing cycle less than or equal to three years.
SKU	String
	Stock keeping unit you defined.
DeliveryInfo	Object
	Object with information about the delivery made to the customer - structure described below
PartnerCode	String
	Possible values: Empty = ecommerce order Partner Code

Overview

Overview

Requirements & limitations

Setup

Overview

Requirements

Parameters

Response

Request

Error

Overview

Parameters

Response

Request

Overview

Parameters

Response

Request

Overview

Additional fields object

Overview

Subscription upgrade object

Overview

Attributes

Overview

Parameters

Request

Response

Overview

Subscription history object

Need help?

Not yet a Verifone customer?