| Verifone Developer Portal

Overview

Extract information on a single subscription. Use the getSubscription 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. 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
Subscription	Object

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

try {
    $subscriptionInfo = $client->getSubscription($sessionID, $subscriptionReference);
}
catch (SoapFault $e) {
    echo "subscriptionInfo: " . $e->getMessage();
    exit;
}
var_dump("subscriptionInfo", $subscriptionInfo);

Overview

Use the Product object to create, update and retrieve subscription plans/products for your account. Use 2Checkout's API and control the following product attributes:

Product information
Pricing
Subscription plan settings and renewal configuration
Subscription plan recurring billing
Fulfillment
Shipping classes
Localization

Parameters

Use the parameters below to add new products into your 2Checkout catalog.

Parameters	Type/Description
Product	Object/Required Product details.
ProductCode	String/Required
	The product code that you can define for each of your offerings. Needs to be unique.
ProductType	String/Optional
	REGULAR or BUNDLE Defaults to REGULAR.
ProductName	String/Required
	The name of the product
ProductVersion	String/Optional
	The product version number
PurchaseMultipleUnits	Boolean/Optional
	Possible values: TRUE - customers can purchase multiple units of this product. FALSE - customers can purchase only one unit at a time. The default value is TRUE.
ShippingClass	Object/Optional
	Existing shipping class object with the structure detailed below.
	Name	String
		The name of the shipping class
	Amount	Decimal
		The shipping costs
	Currency	String
		The currency ISO code used for shipping costs - ISO 4217.
	ApplyTo	String
		Possible values: • PRODUCT • ORDER
	Type	Possible values: • FIXED • PERCENT
GiftOption	Boolean / Optional
	True or false depending on whether the product can be gifted or not.
ShortDescription	String / Optional
	The product's short description
LongDescription	String / Optional
	The product's long description
SystemRequirements	String / Optional
	System requirements
ProductCategory	String / Optional
	Product category
Platforms	Array of Platform objects / Optional
	Array of objects detailing the platforms supported by the application. Details below.
	PlatformName	String
		The label of the platform per the product configuration.
	Category	String
		Platform category per product configuration.
ProductImages	Array of Image objects / Optional
	Image object. Details below. Read-only.
	Default	Boolean
		True or False depending on whether you set the image stored at the address in the URL parameter as default or not.
	URL	String
		The location of the image on the 2Checkout system.
TrialUrl	String (anyURI) / Optional
	The URL from where shoppers can download trial software.
TrialDescription	String / Optional
	Descriptive text entered for trials.
Enabled	Boolean / Optional
	True/false depending on whether the products are active or disabled. When empty, 2Checkout marks the product as disabled.
AdditionalFields	Array of AdditionalFieldAssigned objects / Optional
	Array of existing additional fields assigned to products. Details below.
	Label	String
		The name of the additional field assigned to a product.
	Code	String
		The code of the additional field assigned to a product.
	Enabled	Boolean
		True or false depending on whether the assigned product field is enabled or not.
	Required	Boolean
		True or false depending on whether the assigned product field is required or not.
	URLParameter	String
		The value of the system generated URL parameter for the product field that can be used in Buy Links.
Translations	Array of ProductTranslation objects / Optional
	Details below.
	LongDescription	String
		The translated long description in the language corresponding to the Translation object.
	TrialUrl	String
		The trial URL for users speaking the language corresponding to the Translation object.
	TrialDescription	String

	SystemRequirements	String
		Localized system requirements.
	Name	String
		Localized product name.
	Description	String
		Localized product short description.
	Language	String
		ISO 639-1 two-letter code.
PricingConfigurations	Array of PricingConfiguration objects/Required
	Details below. 2Checkout creates pricing configurations during the process when you add a product.
	Name	String
		Pricing configuration name
	Code	String
		System-generated identifier.
	Default	boolean
		True for the default pricing configuration
	BillingCountries	Array of strings
		ISO codes of the countries assigned to the pricing configuration. Empty unless specific countries are assigned to a pricing configuration.
	PricingSchema	String
		DYNAMIC – With a base price FLAT – Without a base price
	PriceType	String
		Possible values: NET / GROSS
	DefaultCurrency	String
		The ISO code of the default currency for the pricing configuration
	Prices	Object
		Details below.
	Regular	Array of objects
		Details below.
	Amount	Int
		The price of the product.
	Currency	String
		ISO code of the currency for the product price.
	MinQuantity	Int
		The minimum quantity of volume discounts. Default is 1.
	MaxQuantity	Int
		The maximum quantity of volume discounts. Default is 99999.
	OptionCodes	Array of objects
		Details below.
	Code	String
		Price option identifier.
	Options	Array of strings
		The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
	Renewal	Array of objects
		Details below.
	Amount	Int
		The price of the product.
	Currency	String
		ISO code of the currency for the product price.
	MinQuantity	Int
		The minimum quantity of volume discounts. Default is 1.
	MaxQuantity	Int
		The maximum quantity of volume discounts. Default is 99999.
	OptionCodes	Array of PriceOptionCode objects
		Details below.
	Code	String
		Price option identifier.
	Options	Array of strings
		The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
	PriceOptions	Array of AssignedPriceOptionGroup objects
		Details below.
	Code	String
		System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
	Required	Boolean
		True or False depending on whether you want to make it mandatory for shoppers to select the price option during the puyrchase process.
BundleProducts	Array of BundleProductCode objects / Optional
	Details below.
	ProductId	String
		Unique, system-generated product ID.
	ProductCode	String
		Editable product code that you control.
Fulfillment	String / Required
	BY_2CHECKOUT NO_DELIVERY – The 2Checkout system finalizes orders immediately after it receives payment confirmation. BY_VENDOR – you are responsible for delivering/fulfilling orders
Prices	Array of Price objects / Required
	Use this object only when Pricing Configurations are not available for your account. Details below.
	Amount	Int
		The price of the product.
	Currency	String
		ISO code of the currency for the product price.
	MinQuantity	Int
		The minimum quantity of volume discounts. Default is 1.
	MaxQuantity	Int
		The maximum quantity of volume discounts. Default is 99999.
	OptionCodes	Array of objects
		Details below.
	Code	String
		Price option identifier.
	Options	Array of strings
		The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
GeneratesSubscription	Boolean / Required
	TRUE or FALSE depending on whether you set the product to generate subscriptions or not. NULL for bundles for which you set the following subscription management option: “Use the subscription settings of each product in the bundle”
SubscriptionInformation	ProductSubscriptionInformation Object / Optional
	Details below. NULL for bundles which you set to use the renewal settings of child products and not of the parent bundle.
	DeprecatedProducts	Array
		Deprecated products.
	BundleRenewalManagement String
		Possible values: GLOBAL INDIVIDUAL Can be NULL.
	BillingCycle	String
		The number of subscription billing cycle units (months or days). Possible values: 0 (zero represents a one-time fee) Days 7 8 9 10 11 12 13 14 Months 1 2 3 6 12 15 18 24 36 (max)
	BillingCycleUnits	String
		The units of the billing cycle: M - months D - days
	IsOneTimeFee	Boolean
		True or False depending on whether the subscription is evergreen or not.
	ContractPeriod	Object
		Details below.
	Period	Int
		The contract period in months or days. -1 for unlimited contracts.
	PeriodUnits	String
		The contract period units days \| months
	IsUnlimited	Boolean
		This flag is true if the contract is for an unlimited period
	Action	String
		The action performed after the subscription expires. Possible values CANCEL \| RESTART
	EmailsDuringContract Boolean
		True or False depending on whether you suppress renewal notification emails throughout the duration of the contract or not.
	UsageBilling	Int
		The usage billing interval must be smaller than or equal to the grace period. Interval of time within the grace period, when the 2Checkout system attempts to automatically charge customers for recurring costs and additional metered usage fees (in arrears). 2Checkout renews subscriptions only after subscribers make all outstanding payments per the renewal settings (from the expiration or the renewal date). If automatic renewal and usage charges fail, subscriptions can be manually renewed only by the end of the grace period, after which they expire. Can be NULL.
	GracePeriod	Object
	Type	String
		CUSTOM – you configured grace period setting at product level. GLOBAL – global grace period settings apply.
	Period	String
		Number of days set for the grace period.
	PeriodUnits	String
		D - Days.
	IsUnlimited	Boolean
		TRUE or FALSE depending on whether you set the grace period to unlimited or not.
	RenewalEmails	Object
		Details below. Can be NULL. Available only in Product API 2.5 and later.
	Type	String
		GLOBAL - Send emails according to the global renewal notification settings. CUSTOM – per product renewal notification settings
	Settings	Object (can be NULL)
		Details below.
	ManualRenewal	Object (can be NULL)
		Details below.
	Before30Days	Boolean
		True or False.
	Before15Days	Boolean
		True or False.
	Before7Days	Boolean
		True or False.
	Before1Day	Boolean
		True or False.
	OnExpirationDate	Boolean
		True or False.
	After5Days	Boolean
		True or False.
	After15Days	Boolean
		True or False.
	AutomaticRenewal	Object (can be NULL)
		Details below.
	Before30Days	Boolean
		True or False.
	Before15Days	Boolean
		True or False.
	Before7Days	Boolean
		True or False.
	Before1Day	Boolean
		True or False.
	OnExpirationDate	Boolean
		True or False.
	After5Days	Boolean
		True or False.
	After15Days	Boolean
		True or False.
FulfillmentInformation	Object / Optional
	Details below. Can be NULL. Available only in Product API 2.5 and later.
	IsStartAfterFulfillment	Boolean
		True or False. Depending on whether you want the subscription lifetime to start afther the completion of the fulfillment process or not.
	IsElectronicCode	Boolean
		True or False. Depending on whether you configure the delivery of keys/codes for the product or not.
	IsDownloadLink	Boolean
		True or False. Depending on whether you configure the delivery of a product file or not.
	IsBackupMedia	Boolean
		True or False. Depending on whether you configure the delivery of backup media or not.
	IsDownloadInsuranceService	Boolean
		True or False. Depending on whether you enable the Download Insurance Service or not, for a product for which you configure a product file.
	IsInstantDeliveryThankYouPage	Boolean
		True or False. Depending on whether you enable instant delivery in the Thank You page or not.
	IsDisplayInPartnersCPanel	Boolean
		True or False. Depending on whether you share access to the product file with your channel partners or not.
	ReturnMethod	Object
		Information on the customer redirect method after a successful purchase.
	Type	String
		Possible values: DIRECT_RETURN HEADER_REDIRECT HTML_LINK
	URL	String
		Website to which customers are redirected after a successful purchase. Example: "http://mySuccessURL.com"
	CodeList	Object (can be NULL)
		Details below.
	Code	String
		The unique code list identifier.
	Name	String
		Name of the code list.
	Type	String
		Code list type: STATIC DYNAMIC
	BackupMedia	Object (can be NULL)
		Details below.
	Code	String
		The unique backup media identifier.
	Name	String
		Name of the backup CD/DVD.
	Type	String
		Media type: CD
	ProductFile	Object (can be NULL)
		Details below.
	Code	String
		Unique product file identifier.
	Name	String
		Display name.
	File	String
		Name of the product file.
	Version	String
		File version.
	Size	String
		File size.
	Type	String
		File type.
	LastUpdate	String
		YYYY-MM-DD HH-MM-SS. Date time stamp when you last updated the file.
	AdditionalInformationByEmail	String (can be NULL)
		The text you set up in the Additional fulfillment information - by email area.
	AdditionalInformationEmailTranslations	Object (can be NULL)
		Array of localized Additional fulfillment information - by email texts.
	AdditionalThankYouPage	String (can be NULL)
		The text you set up in the Additional fulfillment information - "Thank you" page area.
	AdditionalThankYouPageTranslations	Array (can be NULL)
		Array of localized Additional fulfillment information - "Thank you" page texts.

Overview

Update subscription plan/product pricing using the Price Options Group and the Pricing Configuration objects in SOAP API 4.

Price options group

Use this object to add/create and edit/update price options for your account.

Parameters

PriceOptionsGroup	Array of objects
Name	String
	Price option group name. Use this parameter when adding a new price options group. To edit the name of a price option group use the Name parameter under the Translations object.
Description	String
	Pricing option group description.
Translations	Array of objects
	Details below.
Code	String
	Unique code that The 2Checkout system generates or set for each pricing options group.
Type	String
	The type of the pricing options group. Possible values: · RADIO · CHECKBOX · INTERVAL · COMBO
Options	Array of objects
	Details below.
Required	boolean
	True if you made the pricing option group mandatory.

Options	Object
Name	String
	Pricing option child name.
Description	String
	Pricing option child description.
Translations	Array of objects
	Details below.
Code	String
	The code you set or that the 2Checkout system generated for each pricing option child inside a pricing options group parent.
ScaleMin	Int
	The minimum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.
ScaleMax	Int
	The maximum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.
SubscriptionImpact	Object
	Details below.
PriceImpact	Object
	Details below.
Default	Boolean
	TRUE for preselected options. Missing for options that are not preselected.

SubscriptionImpact	Object
Months	String
	The value in months the 2Checkout system adds or subtracts from the initial billing cycle of a subscription.
Impact	String
	Possible values: ADD SUBTRACT LIFETIME

PriceImpact	Object
ImpactOn	String
	Possible values: BASE corresponding to impact on base price GLOBAL for impact on calculated sum.
Impact	String
	Impact on price per unit: ADD SUBTRACT
Percent	String
	The value of the percentage out of the price per product unit, when you use PERCENT for Method.
Method	String
	Possible values: · PERCENT · FIXED
Amounts	Array of objects.
	Details below.

Amount	Object
Currency	String
	Currency ISO code - ISO 4217.
Amount	String
	The amount defined for each specific currency active for your account, when you use FIXED for Method.

Translations	Object
Name	String
	Localized product pricing options group name under PriceOptionGroup. Localized pricing option child name under Options.
Description	String
	Localized product pricing options group description under PriceOptionGroup. Localized pricing option child description under Options.
Language	String
	ISO language code. (ISO 639-1 two-letter code).

Price option group

Use this object to search for, retrieve information on price option groups (including those assigned to specific products) for your account.

Parameters

PriceOptionGroup	Array of objects
Name	String
	Price option group name. Use this parameter when adding a new price options group. To edit the name of a price option group use the Name parameter under the Translations object.
Description	String
	Pricing option group description.
Translations	Array of objects
	Details below.
Code	String
	Unique code that The 2Checkout system generates or set for each pricing options group.
Type	String
	The type of the pricing options group. Possible values: RADIO CHECKBOX INTERVAL COMBO
Options	Array of PriceOption objects
	Details below.

PriceOption	Object
Code	String
	The code you set or that the 2Checkout system generated for each pricing option child inside a pricing options group parent.
ScaleMin	Int
	The minimum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.
ScaleMax	Int
	The maximum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.
SubscriptionImpact	SubscriptionLifetimeImpact object
	Details below.
PriceImpact	Object
	Details below.
Default	Boolean
	TRUE for preselected options. Missing for options that are not preselected.
Name	String
	Pricing option child name.
Description	String
	Pricing option child description.
Translations	Array of objects
	Details below.

SubscriptionLifetimeImpact	Object
Months	String
	The value in months the 2Checkout system adds or subtracts from the initial billing cycle of a subscription.
Impact	String
	Possible values: ADD SUBTRACT LIFETIME

PriceImpact	Object
ImpactOn	String
	Possible values: BASE corresponding to impact on base price GLOBAL for impact on calculated sum.
Impact	String
	Impact on price per unit: ADD SUBTRACT
Percent	String
	The value of the percentage out of the price per product unit, when you use PERCENT for Method.
Method	String
	Possible values: · PERCENT · FIXED
Amounts	Array of objects.
	Details below.

Amount	Object
Currency	String
	Currency ISO code - ISO 4217.
Amount	String
	The amount defined for each specific currency active for your account, when you use FIXED for Method.

Translations	Object
Name	String
	Localized product pricing options group name under PriceOptionGroup. Localized pricing option child name under Options.
Description	String
	Localized product pricing options group description under PriceOptionGroup. Localized pricing option child description under Options.
Language	String
	ISO language code. (ISO 639-1 two-letter code).

Pricing configuration

Use this object to add/create and update/edit pricing configurations for your account. You can assign one or multiple price option groups to pricing configurations.

You identify a pricing configuration using its unique identifier: Code

Parameters

PricingConfiguration	Object
Name	String
	Pricing configuration name.
Code	String
	System-generated identifier. Read-only.
Default	Boolean
	True for the default pricing configuration
BillingCountries	Array of strings
	ISO codes of the countries assigned to the pricing configuration. Empty unless specific countries are assigned to a pricing configuration.
PricingSchema	String
	DYNAMIC – With a base price FLAT – Without a base price
PriceType	String
	Possible values: • NET • GROSS
DefaultCurrency	String
	The ISO code of the default currency for the pricing configuration
Prices	Object
	Details below.
PriceOptions	Array of objects
	Details below.

Prices	Object
Regular	Array of objects
	Details below.
Renewal	Array of objects
	Details below.

Regular	Object
Amount	Int
	The price of the product. Use -1 to delete it.
Currency	String
	ISO code of the currency for the product price.
MinQuantity	Int
	The minimum quantity of volume discounts. Default is 1.
MaxQuantity	Int
	The maximum quantity of volume discounts. Default is 99999.
OptionCodes	Array of objects
	Details below.

Renewal	Object
Amount	Int
	The price of the product. Use -1 to delete it.
Currency	String
	ISO code of the currency for the product price.
MinQuantity	Int
	The minimum quantity of volume discounts. Default is 1.
MaxQuantity	Int
	The maximum quantity of volume discounts. Default is 99999.
OptionCodes	Array of objects
	Details below.

PriceOptions	Object
Code	String
	System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
Options	StringArray
	The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.

Overview

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

Supported payment methods

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

Object parameters

Parameters								Type/Description
RefNo								Optional (string)
								Unique, system-generated, order reference number. Do not include it when placing new orders or send it as NULL.
Currency								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.
AffiliateId								Optional (int)
								Identifier belonging to affiliates who refer orders.
CustomerReference								Optional (Int)
								System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.
MachineId								Optional (string)
								Unique, system generated code for each unique customer, identifying returning customers.
Items								Required (array of objects)
								Details below.
	OrderItem							Object
								Details below.
			Code					Required (string)
								Unique product identifier your control. Max length 256 characters.
			Quantity					Required (integer)
								Number of units
			PriceOptions					Optional (array of strings)
								Array of price option codes.
			SKU					Optional (string)
								SKU identifier.
			Price					Object - Can be NULL
							OrderPrice	Object - Can be NULL
							Currency	Optional (string)
								The currency ISO code for the payment - ISO 4217. Example: usd.
							NetPrice	Optional (double)
								Order value excluding sales tax/VAT expressed in the payment currency.
							GrossPrice	Optional (double)
								Total order value, including sales tax/VAT expressed in the payment currency. GrossPricedoes not reflect any discounts.
							NetDiscountedPrice	Optional (double)
								The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.
							GrossDiscountedPrice	Optional (double)
								Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts. For example: Currency: "usd" NetPrice: 396 GrossPrice: 486.29 NetDiscountedPrice: 376.2 GrossDiscountedPrice: 466.49 Discount: 19.8 VAT: 90.29 AffiliateCommission: 94.05
							Discount	Optional (double)
								Value of the discounts for an order expressed in the payment currency.
							VAT	Optional (double)
								Value of sales tax/VAT expressed in the payment currency.
							AffiliateCommission	Optional (double)
								Value of the affiliate commission for the order calculated from the NetDiscountedPriceexpressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
							UnitNetPrice	Optional (double)
								The value per product unit, excluding sales tax/VAT expressed in the payment currency.
							UnitGrossPrice	Optional (double)
								Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
							UnitVAT	Optional (double)
								Sales tax/VAT per product unit expressed in the payment currency.
							UnitDiscount	Optional (double)
								Value of the discount per product unit expressed in the payment currency.
							UnitNetDiscountedPrice	Optional (double)
								The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.
							UnitGrossDiscountedPrice	Optional (double)
								Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
							UnitAffiliateCommission	Optional (double)
								Value of the affiliate commission per product unit calculated expressed in the payment currency. 2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions. 2Checkout does not take into account shipping costs when calculating affiliate commissions. NULL when 2Checkout does not apply an affiliate commission.
			CrossSell					Object – Can be NULL
								Details below.
					ParentCode			Optional (string)
								The product code of the master product you set to trigger the campaign.
					CampaignCode			Optional (string)
								Unique, system-generated identifier for cross-sell campaigns.
			Trial					Optional (Object) – Can be NULL
								Details below.
					Period			Optional (integer)
								The length of the trial subscription lifetime in days.
					Price			Optional (double)
								Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
			AdditionalFields					Optional (array of objects) – Can be NULL
					AdditionalFieldSet			Optional (Object) – Can be NULL
							Code	Optional (string)
								The alpha-numeric characters, underscores and dashes that are set as the field identifier.
							Value	Optional (string)
								Selected field value.
			SubscriptionStartDate					Optional (string)
								Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST. Send empty or NULL to activate subscriptions on the same date when customers purchase them. You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
			Promotion					Optional (Object)
								Details below.
					Name			Optional (string)
								Promotion name.
					Description			Optional (string)
								Promotion description.
					StartDate			Optional (string)
								The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
					EndDate			Optional (string)
								The date when you set the promotion to end. NULL for promotions you want active indefinitely.
					MaximumOrdersNumber			Optional (integer)
								2Checkout only applies the promotion to a maximum number of orders you define. Can be NULL if you want the promotion to apply to an unlimited number of orders.
					MaximumQuantity			Optional (integer)
								Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
					InstantDiscount			Optional (boolean)
								The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
					Coupon			Optional (string)
								Promotion coupon/voucher.
					DiscountLabel			Optional (string)
								Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.
					Enabled			Optional (string)
								true or false, depending on whether a promotion is active or disabled.
					Type			Optional (string)
								REGULAR – product/cart line level discounts. ORDER – quantity discounts. GLOBAL – order-level discounts.
BillingDetails								Required (Object)
								Details below.
	Person							Object
									Details below.
		FirstName							Required (string)
									Shopper name.
		LastName							Required (string)
									Shopper surname.
		CountryCode							Optional (string)
									Shopper country. ISO 3166 two-letter code.
		State							Optional (string) – Required for US, Brazil, India and Romania The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, 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 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, Brazil and Romania
									The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
		City							Optional (string)
									Shopper city from the delivery details.
		Address1							Optional (string)
									Shopper address from the delivery details.
		Address2							Optional (string)
									Shopper address from the delivery details.
		Zip							Optional (string)
									ZIP/ Postal code from the delivery details.
		Email							Optional (string)
									Shopper email address from the delivery details.
		Phone							Optional (string)
									Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company							Optional (string)
									Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails								Required (Object)
								Adapt this object to the desired payment method.
	Type							Required (string)
								The payment method: CC (credit/debit card - including local Brazilian cards). ENCRYPTED_PAYMENT_DATA (client-side encryption) PAYPAL PAYPAL_EXPRESS CCNOPCI(credit/debit card for non-PCI certified merchants). 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)
								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.
	RecurringEnabled							Optional (boolean)
								true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process. false – shopper doesn’t check the auto-renewal checkbox.
				CardPayment				Optional (object)
								Details below.
						CardNumber		Optional (string)
								The credit/debit card number.
						CardType		Optional (string)
								visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
						ExpirationYear		Optional (string)
								The year in which the card expires.
						ExpirationMonth		Optional (string)
								The month in which the card expires.
						HolderName		Optional (string)
								Card holder name.
						CCID		Optional (string)
								Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
						HolderNameTime		Optional (float)
								The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
						CardNumberTime		Optional (float)
								The interval of time in seconds in which shopper 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.
				PayPalExpress				Optional (object)
								Details below.
						Email		Optional (string)
								Email address customers use for their PayPal account.
						ReturnURL		Optional (string)
								The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
						CancelURL		Optional (string)
								The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.
				PreviousOrder				Optional (Object)
								Details below.
						RefNo		Optional (string)
								Order reference a previous purchase which reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of order should be AUTHRECEIVED or COMPLETE. Check the validity of references with the isValidOrderReference method. The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
				PurchaseOrderPaymentDetails				Optional (Object)
								Details below.
						InternalPONumber		Optional (string)
								Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
						AutoApprove		Optional (boolean)
								TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders. FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders. Can be NULL.
				WE_CHAT_PAY				Optional (string)
								Details below
						ReturnURL		Optional (string)
								The return URL is the page to which your customers are redirected after their successful payment.
						CancelURL		Optional (string)
								The cancel URL is the page to which your customers are redirected after their failed payment attempt.
				IDEAL				Optional (string)
								Details below
						ReturnURL		Optional (string)
								The return URL is the page to which your customers are redirected after their successful payment.
						CancelURL		Optional (string)
								The cancel URL is the page to which your customers are redirected after their failed payment attempt.
						BankCode		Required (string)
								String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
				EXISTING_PAYMENT_DATA				Optional (Object)
								By using EXISTING_PAYMENT_DATA you no longer require shoppers to enter any payment details.
						TransientToken		Optional (string)
								Returned as a part of the process of retrieving customer information by SSOToken.
	CustomerIP							Required (string)
								Shopper IP.
Promotions								Optional (Array of strings)
								Array of promotion codes.
AdditionalFields
								Details below.
	Code							Optional (string)
								The alpha-numeric characters, underscores and dashes that are set as the field identifier.
	Text							Optional (string)
								Field text visible to shoppers in the cart.
	Value							Optional (string)
								Selected field value.
LocalTime								Optional (string)
								Local shopper time in the following format: Y-m-d H:i:s. This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.
GiftDetails								Optional (object)
								Contains contact details for the recipient of a gift purchase.
	FirstName							Optional (string)
								First name of gift recipient.
	LastName							Optional (string)
								Last name of gift recipient.
	Email							Optional (string)
								Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
	GiftNote							Optional (string)
								Custom text shoppers provide as a message to the gift recipient.

Overview

Assign API roles to your users, for allowing them to perform a task that requires access to the 2Checkout API.

Creating API roles

Login to the 2Checkout Control Panel using your master account.
Go to Account settings.
Click Manage user access.
Go to the View roles tab.
Click Add new role.
Fill in a role name and description.
Select the API access privileges.
Click Save role.

Assign the role to the users you want to provide with access to 2Checkout API.

If a merchant on the PSP business model (2Sell & 2Subscribe) has multiple 2Checkout accounts, which means they have multiple unique domains processing with 2Checkout, then they must have set up a unique API user per account.

Overview

Use the addProductGroup method to create product groups for your account:

Send null for product group Code. 2Checkout ignores any values you send for Code and generates identifiers itself.
Use unique product group names.
2Checkout throws an exception if you send a blank product group.
If you send only the name of the product group 2Checkout creates the new product group 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.
ProductGroup	Required (object)
	Use this object to create product groups. Send null for the Code. 2Checkout generates unique product group code identifiers.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = null;//Send null for the Code. 2Checkout generates unique product group code identifiers.
$ProductGroup->TemplateName = 'Default Template';//'001 - Two Column Billing'; //the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = true;

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

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

?>

Overview

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

Create promotion Update promotion Retrieve a promotion Search promotions

Promotion object

Parameters		Type/Description
CouponCodes		Array of strings
		Array of coupon/voucher codes when Coupon / Voucher type is Multiple. Otherwise, empty array.
ChannelType		String
		Possible values: ECOMMERCE CHANNEL_MANAGER ALL
CouponType		String
		Possible values: SINGLE MULTIPLE
DiscountType		String
		Possible values: FIXED PERCENT
Type		String
		REGULAR
Discount		Int
		The value of the discount. Example, for a $30 USD discount 2Checkout returns the value 30 and for a 25% price cut, 2Checkout returns 25.
Products		Array
		Array of product codes for the products impacted by the promotion.
Name		String
		Promotion name.
Description		String
		Promotion description.
StartDate		String
		Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created.
EndDate		String
		Ending date. The date when you set the promotion to end. Is NULL for promotions that you want active indefinitely.
MaximumOrdersNumber		Int
		When the maximum number of orders is reached the promotion stops. Can be NULL if you want the promotion to apply to an unlimited number of orders.
MaximumQuantity		Int
		Discount only applies to a specific number of product, smaller than the maximum quantity you defined. Can be NULL if you want the promotion to apply to an unlimited number units. Any extra quantity added to the cart will be sold at full price.
InstantDiscount		Boolean
		Selecting the instant discount option will auto-apply the discount for ALL the selected products for all shoppers, without the need to enter the discount coupon.
Coupon		String
		The promotion/voucher for which you are extracting the information.
DiscountLabel		String
		Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.
Enabled		Boolean
		Can be TRUE if promotion is enabled, or FALSE if otherwise.
Currency		String
		Currency code available for the default currency of FIXED promotions. Missing for PERCENT promotions.
Code		String
		Unique, system-generated identifier 2Checkout associates with promotion campaigns.
PriceThreshold		Object
		Limits discount use only when total order value (taxes included) exceeds the threshold you configure.
	Amount	Decimal
		The minimum threshold you defined for the default currency.
	Currency	String
		Currency code available for the default currency of custom threshold settings.

2Checkout API - general information

Overview

Learn how to leverage the 2Checkout API to build your integration with the 2Checkout system, which will enable you to place and manage orders, manage subscriptions and customers, create, update and extract product catalog and pricing information for your account.

Availability

2Checkout API is available for all accounts.

Protocols and versioning

The 2Checkout API is accessible under three protocols across a number of major and minor versions.

The URL for each API protocol and version is composed by following this rule:

https://api.2checkout.com/{protocol}/{version}

The 2Checkout API is accessible under three protocols:

REST - under https://api.2checkout.com/rest/
SOAP - under https://api.2checkout.com/soap/
JSON-RPC (standard RPC protocol with the payload being JSON encoded) - under https://api.2checkout.com/rpc/

In order to maintain backward compatibility, any changes or new features that would break existing integrations are published under a new API version. You can use multiple versions of the API in parallel, allowing for easier integration of new functionalities, but we do not recommend this practice.

Accessing a certain version of the 2Checkout API is easy, as the API version is used in the API URL: https://api.2checkout.com/{protocol}/{version}.

The API is versioned with both major and minor versions. The current latest version of the 2Checkout API is API version 6.0 (publicly launched in December 2019).

Pagination in API

All main resources used in the 2Checkout API support searching and pagination.

This is achieved by using two standard parameters: page and limit. Both parameters are integers, optional, and can be passed as NULL.

"Pagination": {
    "Page": 1,
    "Limit": 10,
   }

The page and limit parameters can be sent directly in the payload of the request, or, in some cases, under a Pagination object.

Typically, the response for a search call will return a list of items, as well as the provided pagination options. Additionally, a total count of items is provided in order to facilitate navigation.

 "Pagination": {
    "Page": 1,
    "Limit": 10,
    "Count": 230
  }

Customer

Attributes

Parameters				Type/Description
CustomerDetails				Object
	AvangateCustomerReference			Optional (Int)
				System-generated Avangate customer reference. null when you create a new customer. The Avangate system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to Buy links.
	ExternalCustomerReference			Optional (string)
				Unique customer alphanumeric (string) identifiers you control. Aggregate subscriptions under the same Customer account by adding the CUSTOMERID (case sensitive) parameter to Buy links.
	FirstName			Required (string)
				Customer's first name.
	LastName			Required (string)
				Customer's last name.
	Company			Optional (string)
				Company name.
	FiscalCode			Optional (string)
				Can be null for end users. For companies, it needs to be the VAT ID, which Avangate validates. Avangate throws an error if the VAT ID is invalid/incorrect. When present, you also need to provide the company name. Can be null for end users.
	Address1			Required (string)
				Customer's address.
	Address2			Optional (string)
				Customer's address.
	City			Required (string)
				Customer's city.
	State			Optional (string)
				Customer's state. For example, "Alabama","Alaska","Arizona".
	Zip			Required (string)
				Zip code.
	CountryCode			Required (string)
				Customer's country code (ISO 3166 two-letter code).
	Phone			Optional (string)
				Customer's phone number.
	Fax			Optional (string)
				Customer's fax number.
	Email			Required (string)
				Customer's email.
	ExistingCards			Optional (Array of objects)

		TransientToken		Optional (Object)
				Populated only with when you retrieve customer information by SSOToken.
			Token	Optional (string)
				Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your Avangate account.
		CardType		Optional (string)
				visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb
		LastDigits		Optional (string)
				Last four digits of the credit card.
		ExpirationMonth		Optional (string)
				Card expiration month.
		ExpirationYear		Optional (string)
				Card expiration year.
		NameOnCard		Optional (string)
				Card holder name.
	Enabled			Optional (boolean)
				true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription. Possible customer statuses: Active - Customer account status is Active even if Trial and Cancelled/Expired subscriptions exist for the customer, along as there's at least one Active subscription. Customers with a single subscription featuring the Past due status (expired but in the grace period) are considered Active. Inactive - All subscriptions associated to this Customer account are cancelled, expired or both. Trial - Customer account status is Trial if all Active subscriptions for this customer are trials, regardless of any Cancelled/Expired subscriptions.
	Trial			Optional (boolean)
				true or false, depending on whether the customer account features only trials or also paid subscriptions.
	Language			Optional (string)
				ISO 639-1 two-letter code. Example: “en.”

Assign a product group

Overview

Use the assignProductGroup method to assign a product to a product group. Following the assignation, the 2Checkout system uses the shopping cart template associated with the product group as the default cart design when shoppers purchase a subscription plan/product.

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.
productCode	Required (string)
	The code of the product you wish assigned to the group.
groupCode	Required (string)
	Unique, system-generated identifier assigned to product groups.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$productCode = "YOUR_PRODUCT_CODE";
$groupCode = "YOUR_PRODUCT_GROUP_CODE";

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'assignProductGroup',
'params' => array($sessionID, $productCode,$groupCode)
);

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

?>

Overview

Parameters

Response

Request

Overview

Parameters

Overview

Price options group

Parameters

Price option group

Parameters

Pricing configuration

Parameters

Overview

Supported payment methods

Object parameters

Overview

Creating API roles

Overview

Parameters

Response

Request

Overview

Promotion object

Overview

Availability

Protocols and versioning

Pagination in API

Attributes

Overview

Parameters

Response

Request

Need help?

Not yet a Verifone customer?