| Verifone Developer Portal

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

?>

Update a product group

Overview

Use the updateProductGroup method to create a new product group for your account.

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 update product groups.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = 'DBA13A4268';
$ProductGroup->TemplateName = 'Default Template'; // the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = false;

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

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

One click (1-click) purchase

Overview

2Checkout supports 1-click purchases for returning customers who paid for their previous orders with:

Credit/Debit cards
PayPal
iDEAL
Alipay
UnionPay

How does this work?

Identify returning customers.
Access data on the previous purchases of returning customers.
Validate previous order references for 1-click purchase scenarios using the isValidOrderReference method (explained below).
Place a new order using a valid previous order reference as the payment method.
2Checkout charges returning customers using their payment-on-file information, either a card or their PayPal account.

Requirements

Use only references to previous orders with one of the following statuses AUTHRECEIVED or COMPLETE.
The email address of the BillingDetails object is mandatory and it needs to match the email address used as a part of the billing details of the initial order whose reference you're now using to place a new order. 2Checkout checks whether the email addresses are identical, and throws an error if they're not, blocking the order placement process. Note: You need to provide only the email address of the shopper, and can ignore the rest of the required customer billing information. If you enter any billing details in addition to the email address, you'll have to provide all information required in the BillingDetails object.
For orders paid with PayPal, the original order must have automatic renewal enabled so that it can be reused for future 1-click purchases.

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
	Object containing order information.

Validate previous order reference

<?php

require('PATH_TO_AUTH');

$orderReference = '670174996';
$jsonRpcRequest = array (
'method' => 'isValidOrderReference',
'params' => array($sessionID, $orderReference),
'id' => $i++,
'jsonrpc' => '2.0'
);

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

Place an order using previous order reference

<?php

require('PATH_TO_AUTH');

$oldOrderExistent = callRPC((Object)$jsonRpcRequest, $host, true);
$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->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$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->BillingDetails = new stdClass();
$Order->BillingDetails->Email = $oldOrderExistent->BillingDetails->Email;;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'PREVIOUS_ORDER';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->RefNo = $orderReference;
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

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

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

Overview

Parameters

Response

Request

Overview

How does this work?

Requirements

Parameters

Response

Validate previous order reference

Place an order using previous order reference

Need help?

Not yet a Verifone customer?