| Verifone Developer Portal

API Migration Guide

Overview

Use this guide to prepare and migrate your 2Checkout API implementation from version 1.0 to 3.0. This document features deprecations, updates and enhancements, providing guidance on how to upgrade your implementation to the latest version of the 2Checkout API.

API 1.0 discontinuation

2Checkout plans to discontinue API 1.0 as of the end of February 2017. The end-of-support date implies ceasing all development of bug fixes and patches for API 1.0.

API 3.0 availability

Version 3.0 of the 2Checkout API is available as of June, 2016, following an extensive public testing phase started in November 2015. 2Checkout recommends that you migrate to the latest version of the API (v3.0) to enjoy support for your implementation.

API 3.0 what’s new and benefits

Full REST support for existing platform functionalities in addition to SOAP and JSON-RPC.
Simplify interactions with single-entry point (one endpoint, one client, single-authentication).
Centralized all previous functionality under 3.0 (plus new capabilities).
Unified WSDL for Order, Subscription, and Product scenarios.

Serializations 1.0 vs. 3.0

Single API URL per serialization format

https://api.avangate.com/rpc/3.0 /
https://api.avangate.com/soap/3.0 /
https://api.avangate.com/rest/3.0 /
https://api.avangate.com/3.0 / redirects to https://api.avangate.com/rest/3.0 / by default

WSDL 1.0 vs. 3.0

When you migrate from API 1.0 to 3.0, stop using https://secure.2checkout.com/api/merchant/?wsdl in favor of https://api.2checkout.com/soap/3.0/?wsdl.

Methods 1.0 vs. 3.0

API 1.0	Status	API 3.0 equivalent
addLicense	Updated. Use:	addSubscription
addProduct	Deprecated	N/A. The placeOrder scenario now requires a single method.
clearProducts	Deprecated	N/A. The placeOrder scenario now requires a single method.
deleteProduct	Deprecated	N/A. The placeOrder scenario now requires a single method.
disableLicense	Updated. Use:	cancelSubscription
disableLicenseRecurring	Updated. Use:	disableRecurringBilling
enableLicense	Updated. Use:	enableSubscription
enableLicenseRecurring	Updated. Use:	enableRecurringBilling
extendLicense	Updated. Use:	extendSubscription
getAvailableCountries	Updated. Use:	getAvailableCountries
getAvailableCurrencies	Updated. Use:	getAvailableCurrencies
getAvailableLanguages	Updated. Use:	getAvailableLanguages
getContents	Updated. Use:	getContents
getInvoice	Updated. Use:	getInvoices
getLicense	Updated. Use:	getSubscription
getLicensePaymentDetails	Updated. Use:	getPaymentInformation
getLicenseProductUpgradeOptions	Updated. Use:	getProductUpgradeOptions
getNextRenewalPrice	Updated. Use:	getNextRenewalPrice
getOrder	Updated. Use:	getOrder
getOrderStatus	Updated. Use:	getOrder
getPrice	Updated. Use:	getPrice
getProductByCode	Updated. Use:	getProductByCode
getProductById	Updated. Use:	getProductByCode
getProductUpgradeOptionsPrice	Updated. Use:	getProductUpgradeOptionsPrice
getRenewalPrice	Updated. Use:	getRenewalDetails
getSingleSignOn	Updated. Use:	getSingleSignOn
getTimezone	Updated. Use:	getTimezone
isValidOrderReference	Updated. Use:	isValidOrderReference
login	Updated. Use:	login
placeOrder	Updated. Use:	placeOrder
renewLicense	Updated. Use:	renewSubscription
searchLicense	Updated. Use:	getSubscriptions
searchProducts	Updated. Use:	searchProducts
setBillingDetails	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setClientIP	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCountry	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCurrency	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCustomer	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCustomRenewalPrice	Updated. Use:	setCustomRenewalPrice
setDeliveryDetails	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setExternalRef	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setLanguage	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setLicenseEmailSubscription	Updated. Use:	setRenewalNotificationStatus
setLicenseUpgrade	Updated. Use:	setSubscriptionUpgrade
setPaymentDetails	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setSource	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setStaticPrice	Deprecated.	N/A. The placeOrder scenario now requires a single method.
updateLicense	Updated. Use:	updateSubscription
updateLicenseCustomer	Updated. Use:	updateSubscriptionEndUser

New use cases API 3.0

SOAP	JSON-RPC	REST
Product Add a subscription plan/product Retrieve product info by code Retrieve subscription plan/product info Update a subscription plan/product Enable/Disable products Pricing Add a pricing configuration Assign a PricingOption Group Create price option groups Retrieve assigned price option groups Retrieve a price option group Retrieve a pricing configuration by code Retrieve a pricing configuration by name Retrieve price option groups Retrieve pricing configurations Unassign a PricingOption Group Update price options Update pricing configuration Save prices Product group Assign a product group Create a product group Retrieve a product group Retrieve product groups Unassign a product group Update a product group Promotion Retrieve a promotion Retrieve information on promotions Order field Add order/product additional fields Assign order/product additional fields Retrieve an order field Retrieve assigned additional fields Retrieve order fields Unassign order/product additional fields Update order/product additional fields Cross-sell Retrieve cross-sell campaigns Retrieve cross-sell campaign texts Retrieve a cross-sell campaign Shipping class Retrieve a shipping class Retrieve shipping classes Order object Place an order Retrieve PayPal redirect URL 1-click purchase Validate order references as payment Orders with installments Retrieve installment information Place an order with installments Order session content object Retrieve session content Subscription import Add/Import subscriptions without payment data Add/Import subscriptions with credit/debit data Subscription Update a subscription and assign it to another customer Assign a subscription to another customer Retrieve a customer’s subscriptions Retrieve specific list of subscriptions Set grace period Next renewal price Custom subscription renewal price C onvert a trial Subscription history Retrieve the history of a subscription Renew a subscription Extend a subscription Customer Create a new customer Retrieve a customer Update a customer Retrieve a customer’s subscription C opy payment info Single Sign On (SSO) Single Sign On by customer reference Single Sign On in cart Retrieve Single Sign On customer info by SSOToken Control myAccount UI display language	Product Add a subscription plan/product Retrieve product info by code Retrieve subscription plan/product info Update a subscription plan/product Enable/Disable products Pricing Add a pricing configuration Assign a PricingOption Group Create price option groups Retrieve assigned price option groups Retrieve a price option group Retrieve a pricing configuration by code Retrieve a pricing configuration by name Retrieve price option groups Retrieve pricing configurations Unassign a PricingOption Group Update price options Update pricing configuration Save prices Product group Assign a product group Create a product group Retrieve a product group Retrieve product groups Unassign a product group Update a product group Promotion Retrieve a promotion Retrieve information on promotions Order field Add order/product additional fields Assign order/product additional fields Retrieve an order field Retrieve assigned additional fields Retrieve order fields Unassign order/product additional fields Update order/product additional fields Cross-sell Retrieve a product’s cross-sell campaigns Retrieve cross-sell campaigns Retrieve cross-sell campaign texts Shipping class Retrieve a shipping class Retrieve shipping classes Order object Place an order Retrieve PayPal redirect URL 1-click purchase Validate order references as payment Orders with installments Retrieve installment information Place an order with installments Order session content object Retrieve session content Subscription import Add/Import subscriptions without payment data Add/Import subscriptions with credit/debit data Subscription Update a subscription and assign it to another customer Assign a subscription to another customer Retrieve a customer’s subscriptions Retrieve specific list of subscriptions Set grace period Next renewal price Custom subscription renewal price C onvert a trial Subscription history Retrieve the history of a subscription Renew a subscription Extend a subscription Customer Create a new customer Retrieve a customer Update a customer Retrieve a customer’s subscriptions C opy payment info Single Sign On (SSO) Single Sign On by customer reference Single Sign On in cart Retrieve Single Sign On customer info by SSOToken Control myAccount UI display language	Product Add a subscription plan/product Retrieve product info by code Retrieve subscription plan and product info Update a subscription plan or product Enable products and subscription plans Disable products and subscription plans Product group Create a product group Retrieve a product group Retrieve product groups Assign a product to a product group Unassign a product from a product group Pricing configuration Add a pricing configuration Retrieve pricing configurations Retrieve a pricing configuration Update a pricing configuration Price options group Create price option groups Update price options Retrieve price option groups Retrieve a price options group Retrieve assigned price option groups Additional fields Create additional fields Retrieve additional fields Retrieve an additional field Retrieve additional field texts Shipping fees Retrieve shipping fees Retrieve a shipping fee configuration Cross-sell Retrieve cross-sell campaigns Retrieve cross-sell campaign texts Retrieve a product's cross-sell campaigns Promotions Retrieve all promotions set for a product Retrieve all active promotions Retrieve a product's promotion Retrieve a promotion Order Place an order Retrieve order status Retrieve PayPal Express redirect URL 1-Click purchase Use an order reference for a 1-click purchase Validate order references as payment Orders with installments Retrieve installment information Place an order with installments Order session Retrieve session content Order information Retrieve an order Invoices Retrieve invoices Retrieve invoices for refunds Subscription import Import subscriptions Subscription Retrieve subscriptions Retrieve a subscription Update a subscription Assign a subscription to another customer Enable a subscription Disable a subscription Trial conversion Convert a trial Subscription renewal Renew a subscription Retrieve renewal links and recurring billing status Enable recurring billing Disable recurring billing Enable renewal notifications Disable renewal notifications Set a custom grace period Renewal price Retrieve a subscription's next renewal price Set a custom subscription renewal price Subscription upgrade Upgrade a subscription Retrieve upgrade options for a subscription Subscription payment info Retrieve the payment info for a subscription Subscription history Retrieve the history of a subscription Retrieve a subscription's purchase, renewal or upgrade details Customer Retrieve a customer Create a customer Retrieve a subscription’s customer End user Retrieve a subscription's end user Update end user info Single Sign On SSO by subscription reference SSO in cart SSO by customer reference

SOAP

JSON-RPC

REST

Product

Enable/Disable products

Pricing

Save prices

Product group

Promotion

Order field

Cross-sell

Shipping class

Order object

1-click purchase

Validate order references as payment

Orders with installments

Order session content object

Retrieve session content

Subscription import

Subscription

Next renewal price

Custom subscription renewal price

C onvert a trial

Subscription history

Customer

C opy payment info

Single Sign On (SSO)

Product

Enable/Disable products

Pricing

Product group

Validate order references as payment

Orders with installments

Order session content object

Retrieve session content

Subscription import

Subscription

Next renewal price

Custom subscription renewal price

C onvert a trial

Subscription history

Customer

C opy payment info

Single Sign On (SSO)

JavaScript affiliate checker

Overview

Use the JavaScript Affiliate Checker to keep track of sales generated by members of the 2Checkout Affiliate Network for services/products that you sell using a third-party eCommerce platform.

3rd party eCommerce provider -> JAVASCRIPT affiliate checker -> detects 2Checkout cookie -> 2Checkout buy-links
3rd party eCommerce provider -> JAVASCRIPT affiliate checker -> does not detect 2Checkout cookie -> 3rd party buy links

Requirements

In order to use JavaScript Affiliate Checker, the following requirements must be met:

The 2Checkout Affiliate Network is enabled for your account.
Products sold through a third-party platform and available to 2Checkout Affiliates must be configured within the 2Checkout platform as well, and need to be assigned to commissions lists associated with 2Checkout Affiliates. Make sure to specify a commission you're willing to pay for affiliate referrals.

How does the JavaScript Affiliate Checker work?

Take advantage of the JavaScript Affiliate Checker to customize the content of your online store for those shoppers that feature the 2Checkout affiliate cookie.

Installing the JavaScript Affiliate Checker

To install, copy and customize the 2Checkout Affiliate Checker JavaScript code and place the code between the <head></head> tags on your site.

<script language="JavaScript">
var vId = 'UNIQUE CODE FOR YOUR ACCOUNT';
var scriptSRC = '/check_affiliate_v2.js';
var protocol = window.location.protocol;
if (protocol.indexOf("https") === 0) document.write(unescape("%3Cscript src='https://secure.2Checkout.com/content" + scriptSRC + "' type='text/javascript'%3E%3C/script%3E"));
else document.write(unescape("%3Cscript src='http://content.2Checkout.com" + scriptSRC + "' type='text/javascript'%3E%3C/script%3E"));
</script>
<script language="JavaScript">
var avgParams = _checkAvgParams();
var alreadyChecked = false;
if (avgParams != null) {
_AVGSetCookie('_avgCheck', avgParams);
alreadyChecked = true;
}
var avgProds = _avgProds(_AVGGetCookie('_avgCheck'), alreadyChecked, vId); //redirect
var AVG_AFF = false;var AVG_PRODS = new Array();
if (avgProds != "-") {
AVG_AFF = true;
if(avgProds != 'all') {AVG_PRODS = avgProds.split(',');}
}
</script>

The JavaScript code inserted into your site will help check and identify shoppers that feature the 2Checkout affiliate cookie and will return a set of results (response JavaScript variables):

AVG_AFF - boolean - having the following possible values
- true - the customer has an active tracking cookie
- false - the customer does not have an active tracking cookie
AVG_PRODS - JavaScript array - an associative array with all products that are tracked by 2Checkout or empty value is a general referral cookie is set.

AVG_AFF = false	AVG_PRODS = empty array, not applicable
AVG_AFF = true	AVG_PRODS = JavaScript array if no general cookie is set and specific product cookies are set
AVG_AFF = true	AVG_PRODS = empty array, general cookie is set

AVG_SET_DATE – delivers the date when the cookie was set in the user’s browser
- Format: YYYY-MM-DDTHH:MM:SS (E.G: 2019-10-18T15:27:54)

Use the results to:

Build efficient landing pages for your affiliates;
Display custom information on your pages;
Prevent affiliate leaks by displaying the correct buy buttons;
Get extra information about your affiliate activity.

You will need to use the responses returned by the script in order to redirect shoppers to either the 2Checkout shopping cart, if a 2Checkout affiliate ID is detected, meaning they there were redirected to your website from a 2Checkout affiliate; or to the third-party shopper platform of your choice.

When redirecting customers to the 2Checkout shopping cart, use Buy Links generated via the Control Panel.

Orders placed by shoppers that used the Buy Links from 2Checkout affiliates will immediately be visible in the Order search area of the Control Panel.

Start Using the Affiliate Network

Subscription import

Overview

Add/import subscriptions in the Avangate system. Include card data with your subscription import only if you contacted Avangate to enable this functionality for your account. Otherwise, the import process results in a failure. Contact Avangate or your account manager directly for more details.

Attributes

Parameters				Type/Description
ExternalSubscriptionReference				Required (string)
				Unique identifier for your subscription. Mandatory when importing subscription data.
StartDate				Required (string)
				Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration.
ExpirationDate				Required (string)
				Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration.
Product				Required (object)
				The product for which Avangate generated the subscription. Details below.
	ProductCode			String
				Unique product identifier that you control.
	ProductId			Int
				Unique, system-generated product identifier.
	ProductName			String
				Product name.
	ProductQuantity			Int
				Ordered number of units.
	ProductVersion			String
				Product version.
	PriceOptionCodes			Array
				The product options codes the customer selected when acquiring the subscription. Pricing options codes are case sensitive.
EndUser				Required (object)
				The end user of the subscription. Details below.
	Person			Object
				Details below.
		FirstName		String
				End user's first name
		LastName		String
				End user's last name
		CountryCode		String
				End user country code [ISO3166-1 Alpha 2].
		State		String
				End user state.
		City		String
				End user city.
		Address1		String
				End user first address line.
		Address2		String
				End user second address line.
		Zip		String
				End user zip code.
		Email		String
				End user email address.
		Phone		String
				End user phone number.
		Company		String
				Company name.
	Fax			String
				End user fax.
	Language			String
				Language [ISO639-2] the Avangate system uses for communications.
DeliveryInfo				Optional (object)
				The object contains information about the delivery/fulfillment made to the customer.
	Description			String
				Delivery description.
	Codes			Array of objects
				Details below.
		Code		String
				Delivered activation key/code.
		Description		String
				Code description for dynamic lists from your key generator.
		ExtraInfo		Object
				Info set by your key generator for dynamic lists only.
			CodeExtraInfo	Object
			Type	String
			Label	String
			Value	String
		File		Array of objects
				Details below.
			Content	String
				Content of the file (base64 encoded).
			ContentLength	Int
				File size.
			Filename	String
				The name of the delivered file.
			FileType	String
				The type of the delivered file.
PartnerCode				Optional (string)
				Empty: for ecommerce orders Partner Code (mandatory)
ExternalCustomerReference				Optional (string)
				Customer identifier you control.
SubscriptionValue				Optional (double)
				Subscription value. The total costs incurred by the customer through the lifecycle of the subscription before you imported the item into the Avangate system. When you send this parameter you must accompany it by ValueCurrency.
SubscriptionValueCurrency				Optional (string)
				Mandatory when you also send the Value parameter. The currency associated to the subscription value.
AdditionalInfo				Optional (string)
				Extra information that you can attach to a subscription, such as the source of the initial purchase.
NextRenewalPrice				Optional (double)
				The future costs that subscribers would incur when their subscriptions are renewed. When provided, you must accompany it by NextRenewalPriceCurrency and CustomPriceBillingCyclesLeft.
NextRenewalPriceCurrency				Optional (string)
				Mandatory when you send CustomPriceBillingCyclesLeft. The currency associated with the subscription next renewal price value.
CustomPriceBillingCyclesLeft				Optional (string)
				Mandatory when you send NextRenewalPrice. Avangate applies the next renewal price to the number of billing cycles you define.
Test				Optional (integer)
				Available only for eStore subscriptions. Use 1 to import a test subscription. Exclude the parameter or set the value to 0 to import regular subscriptions. Test subscriptions enable you to try out flows like manual and auto renewal, and upgrade.
CardPayment				Optional (object)
				Include payment (credit/debit card) information that Avangate uses for recurring billing to renew imported subscriptions. Importing subscriptions with payment data is available only to eligible Avangate accounts. Contact Avangate directly for additional details.

Card payment

Add credit/debit card details when importing subscriptions. Avangate uses payment information in the recurring billing process.

For imports of test subscriptions, use the credit card information from this article.

Parameters	Type/Description
CardPayment	Object
CardNumber	Required (string)
	The credit/debit card number.
CardType	Required (string)
	VISA, VISAELECTRON, MASTERCARD, MAESTRO, AMEX, DISCOVER, DANKORT, CARTEBLEUE, JCB.
ExpirationYear	Required (string)
	The year in which the card expires.
ExpirationMonth	Required (string)
	The month in which the card expires.
HolderName	Required (string)
	Card holder name.
CCID	Required (string)
	Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
HolderNameTime	Required (int)
	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.
AutoRenewal	Optional (bool)
	True or false, depending on whether the customer or you enabled or disabled subscription auto-renewals.
CardNumberTime	Optional (int)
	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.

Offline payments guidance

Use the variables in the list below to customize the Offline payments guidance shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.

Variable name	Description	Test value	Mandatory
ADDRESS1	First section of the delivery address	[123, Main Street]	No
ADDRESS1_D	First section of the delivery address	[123, Main Street]	No
ADDRESS2	Second section of the delivery address	0	No
ADDRESS2_D	Second section of the delivery address	0	No
AVANGATE_LOGO	Avangate logo URL	https://secure.avangate.com/images/e...endor_logo.png	Yes
BANKACCOUNT	Avangate bank account	[123456789]	No
BANKIBAN	Avangate bank IBAN	[XX12XXXX12345678]	No
BANKNAME	Avangate bank name	[Bank Name]	No
BANKROUTINGNUMBER	Avangate bank routing number	[12345678]	No
BANKSWIFT	Avangate bank swift code	[SWIFTXXXXX]	No
BOLETO_SLIP_URL	URL pointing to Boleto slip	0	No
BUSINESS_CITY	Avangate city	0	No
BUSINESS_COMPANY	Avangate company name	[Avangate]	Yes
BUSINESS_COUNTRY	Avangate country	0	No
BUSINESS_FAX	Avangate fax number	0	No
BUSINESS_HOTLINE	Avangate support phone	0	No
BUSINESS_OPEMAIL	Avangate operational email address	0	No
BUSINESS_OPFAX	Avangate operational fax number	0	No
BUSINESS_PHONE	Avangate phone number	0	No
BUSINESS_REG_NUMBER	Avangate registration number	0	No
BUSINESS_STATE	Avangate state	0	No
BUSINESS_STREET	Avangate street address	0	No
BUSINESS_SUPEMAIL	Avangate support email address	support@avangate.com	No
BUSINESS_VAT_ID	Avangate tax id	0	No
BUSINESS_ZIP	Avangate ZIP code	0	No
CBANKACCOUNT	Shopper's bank account used on the billing information	0	No
CBANKNAME	Shopper's bank name used on the billing information	0	No
CITY	Shopper's city used on the billing information	[Anytown	No
CITY_D	Shopper's city used on the delivery information	[Anytown	No
COMMERCIALNAME	Merchant's commercial name	[Software Company Name]	No
COMPANY	Shopper's company name used on the billing information	[Customer company]	No
COMPANY_D	Shopper company name used on the delivery information. If no delivery information is available. no company name is displayed.	[Customer company]	No
COUNTRY	Shopper's country used on the billing information	[U.S.A]	No
COUNTRY_D	Shopper's country used on the delivery information	[U.S.A]	No
CURRENCY	Order billing currency	USD]	Yes
CURRENCY_ORIGINAL	Original order currency (applicable to refunds)	0	No
CUSTOMEREMAIL	Shopper's email address used on the billing information	example@customer-email.com	No
DELIVERABILITY	Order delivery status	0	No
DELIVRABILITY	The delivery status of the loaded order	0	No
ENCRYPTED_MERCHANT_CODE	Encrypted merchant code	XXXXXXX	No
FIRSTNAME	Shopper's first name used on the delivery information	[John	No
FIRSTNAME_D	Shopper's first name used on the delivery information	[John	No
FISCALCODE	Shopper's fiscal code used on the billing information	0	No
GENERALTOTAL	Total order price	[56.50	Yes
GLOBALDISCOUNT	Order total discount	[3.00	No
HAS_BACKUPCD	Order has CD delivery	1	No
HAS_RENEWAL_PRODUCTS	Flag that indicates whether at least one product has renewal settings	0	No
HOTLINE_NUMBER	0	0	No
HOTLINE_NUMBERS.NG_PHONE[index1]	0	0	No
HOTLINE_NUMBERS.NG_PHONE[index1].HotlineName	Countries where Avangate support information is available.	0	No
HOTLINE_NUMBERS.NG_PHONE[index1].HotlineValue	Avangate phone number(s) for shopper support.	0	No
IDCOUNTRY	ID for shopper's country used on the billing information	0	No
IS_RENEWAL	Flag that indicates whether at least one product has renewal settings	0	No
LASTNAME	Shopper's last name used on the delivery information	Doe]	No
LASTNAME_D	Shopper's last name used on the delivery information	Doe]	No
LINK2UPLOADPOFILE	Link to the uploaded file when the order has been made	https://secure.avangate.com	No
NAMES_OF_PRODUCTS	Names of all products in the order, comma separated	0	No
ORDERDATE	Order placement date	[2011-01-01]	Yes
ORDERFLOW	The purchase flow used to place the order	0	No
ORDER_AMOUNT_ORIGINAL	Original order value (applicable to refunds)	0	No
ORDER_CONF_PDF_URL	Download link for the order confirmation document	0	No
ORDER_DATE_STANDARD_FORMAT	Standard format used for the order placement date	0	No
ORDER_FLOW	Purchase flow used to place the order	0	No
ORDER_STATUS	Order status	0	No
PAYABLE_TO	Payee name (applicable to wire transfer)	[Avangate]	No
PAYMENT_REFERENCE	Payment reference for wire transfer	0	No
PAYMENT_TYPE_INFO	English payment method name. Includes last four card digits (if applicable).	0	No
PAYTYPE	Identification number for the payment method selected during ordering process	15	No
PAY_BY_CHECK_ADDRESS1	Avangate address (first section) to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_ADDRESS2	Avangate address (second section) to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_CITY	Avangate city to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_COMPANY	Avangate company name to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_COUNTRY	Avangate country to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_STATE	Avangate state to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_STREET	Avangate street name to be used by shoppers selecting check as payment method	0	No
PAY_BY_CHECK_ZIP	Avangate ZIP code to be used by shoppers selecting check as payment method	0	No
PHONE_D	Shopper's phone number used on the delivery information	[555-555-555]	No
PRODUCTS		0	No
PRODUCTS[index1].DISCOUNT	Product discount value per product line	[2.00	No
PRODUCTS[index1].INFO	Additional product information defined by merchant when generating buy links	[Product info 1]	No
PRODUCTS[index1].LICENSE_TYPE	Type of purchased subscription	0	No
PRODUCTS[index1].PCODE	Product code.	[P_CODE_1]	No
PRODUCTS[index1].PID	Product ID number	1001	No
PRODUCTS[index1].PNAME	Product name	[Test product name 1]	No
PRODUCTS[index1].PRICE	Product unit price	[20.00	No
PRODUCTS[index1].PROMONAME	Name of the promotion applied to the product	[Some promotion]	No
PRODUCTS[index1].QUANTITY	Purchased product quantity	[2]	No
PRODUCTS[index1].SHORT_DESCRIPTION	Short product description	0	No
PRODUCTS[index1].TOTAL	Total gross price per product line (before applying discounts)	[45.60	No
PRODUCTS[index1].VAT	VAT/Sales tax value per product line	[3.80	No
PRODUCTS_DATA[index1].IdProduct	Product ID number	0	No
PRODUCTS_DATA[index1].PRODUCT_SHORT_DESCRIPTION	Short product description	0	No
PRODUCTS_NO	Number of products in cart	0	No
PRODUCT_OPTIONS[index1][index2]	0	0	No
PRODUCT_OPTIONS[index1][index2].OptionText	0	0	No
PURCHASEORDERDATA	0	0	No
PURCHASEORDERDATA.POrderExtendedData	0	0	No
PURCHASEORDERDATA.POrderExtendedData.PurchaseOrderDelay	Number of days for the shopper to make the payment (starting with the moment the Purchase Order was approved by the merchant)	0	No
PURCHASEORDERDATA.POrderExtendedData.PurchaseOrderMaxDate	Date when the Purchase Order expires	0	No
PURCHASEORDERDATA.POrderExtendedStatus	Status of the Purchase Order	0	No
QR_CODE_SRC	The QR code URL to be used for payments with bank/wire transfer.	0	No
REFNO	Order reference number	[9xxxxxx]	Yes
REGISTRATIONNUMBER	Shopper's registration number used on the billing information	0	No
RETRYLINK	Payment retry link	0	No
RETRY_LINK	Payment retry link	0	No
SELLERCOMPANY	Merchant's company name	0	No
SHIPPING	Shipping fee amount	[0.00	No
SHOPPER_REFERENCE_NUMBER	Shopper reference number	PO12345	No
STATE	Shopper's state used on the billing information	Anystate	No
STATE_D	Shopper's state used on the delivery information	Anystate	No
SUBTOTAL	The order amount without vat and shipping	[56.50	No
SUPPORTEMAIL	Merchant support email address	0	No
TOTALEQUIV	The order amount converted to all the merchant's currencies	0	No
UPLOADLINK	File upload link	0	No
UPLOAD_LINK	File upload link	0	No
WEBSITE	Website where the shopper placed the order	http://www.software-company-website.com	Yes
ZIPCODE	Shopper's ZIP code used on the billing information	12345]	No
ZIPCODE_D	Shopper's ZIP code used on the delivery information	12345]	No

Refund an order

Overview

Refund a sale made in 2Checkout via the issueRefund API method. You can issue a refund for only a sale line item, issue a partial refund on the total amount, or refund the entire order amount.

Requirements

The payment for the refundable order needs to be collected.

You cannot issue a refund for an amount higher than the total order amount.

Parameters

Parameters		Type/Description
RefNo		String / Required The order reference number of the sale for which the refund is issued. Example: '721924012'.
Amount		Double / Required Refundable amount. Required as a supplementary check for partial refunds. Example: '26.00'.
Comment		String / Optional Comments are displayed to customers in the refund confirmation they receive. Example: 'Let us know if you are satisfied with the refund process'.
Reason		String / Required In case you have custom refund reasons defined on your account, send one of the reasons. If not, send one of the platform defined reasons. Read more about 2Checkout refund reasons. Example: 'Unwanted auto-renewal'.
Items		Array / Required only for partial refunds In case you issue a partial refund, send the array with the information below.
	ProductCode	String / Required Send the product code belonging to the products to be refunded. The product code is available at product level, in the Information tab.
	Quantity	Integer / Required Quantity to be refunded. Send only positive values.
	Amount	Double / Required Total amount of the refunded line item, not the unit amount.

Subscriptions

Subscription import

Overview

Add/import subscriptions in the 2Checkout system. Include card data with your subscription import only if you contacted 2Checkout to enable this functionality for your account. Otherwise, the import process results in a failure. Contact 2Checkout or your account manager directly for more details.

Parameters

Parameters				Type/Description
ExternalSubscriptionReference				Required (string)
				Unique identifier for your subscription. Mandatory when importing subscription data.
StartDate				Required (string)
				Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration.
ExpirationDate				Required (string)
				Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration.
Product				Required (object)
				The product for which 2Checkout generated the subscription. Details below.
	ProductCode			String
				Unique product identifier that you control.
	ProductId			Int
				Unique, system-generated product identifier.
	ProductName			String
				Product name.
	ProductQuantity			Int
				Ordered number of units.
	ProductVersion			String
				Product version.
	PriceOptionCodes			Array
				The product options codes the customer selected when acquiring the subscription. Pricing options codes are case sensitive.
EndUser				Required (object)
				The end user of the subscription. Details below.
	Person			Object
				Details below.
		FirstName		String
				End user's first name
		LastName		String
				End user's last name
		CountryCode		String
				End user country code [ISO3166-1 Alpha 2].
		State		String
				End user state.
		City		String
				End user city.
		Address1		String
				End user first address line.
		Address2		String
				End user second address line.
		Zip		String
				End user zip code.
		Email		String
				End user email address.
		Phone		String
				End user phone number.
		Company		String
				Company name.
	Fax			String
				End user fax.
	Language			String
				Language [ISO639-2] the 2Checkout system uses for communications.
DeliveryInfo				Optional (object)
				The object contains information about the delivery/fulfillment made to the customer.
	Description			String
				Delivery description.
	Codes			Array of objects
				Details below.
		Code		String
				Delivered activation key/code.
		Description		String
				Code description for dynamic lists from your key generator.
		ExtraInfo		Object
				Info set by your key generator for dynamic lists only.
			CodeExtraInfo	Object
			Type	String
			Label	String
			Value	String
		File		Array of objects
				Details below.
			Content	String
				Content of the file (base64 encoded).
			ContentLength	Int
				File size.
			Filename	String
				The name of the delivered file.
			FileType	String
				The type of the delivered file.
PartnerCode				Optional (string)
				Empty: for ecommerce orders Partner Code (mandatory)
ExternalCustomerReference				Optional (string)
				Customer identifier you control.
SubscriptionValue				Optional (double)
				Subscription value. The total costs incurred by the customer through the lifecycle of the subscription before you imported the item into the 2Checkout system. When you send this parameter you must accompany it by ValueCurrency.
SubscriptionValueCurrency				Optional (string)
				Mandatory when you also send the Value parameter. The currency associated to the subscription value.
AdditionalInfo				Optional (string)
				Extra information that you can attach to a subscription, such as the source of the initial purchase.
NextRenewalPrice				Optional (double)
				The future costs that subscribers would incur when their subscriptions are renewed. When provided, you must accompany it by NextRenewalPriceCurrency and CustomPriceBillingCyclesLeft.
NextRenewalPriceCurrency				Optional (string)
				Mandatory when you send CustomPriceBillingCyclesLeft. The currency associated with the subscription next renewal price value.
CustomPriceBillingCyclesLeft				Optional (string)
				Mandatory when you send NextRenewalPrice. 2Checkout applies the next renewal price to the number of billing cycles you define.
Test				Optional (integer)
				Available only for eStore subscriptions. Use 1 to import a test subscription. Exclude the parameter or set the value to 0 to import regular subscriptions. Test subscriptions enable you to try out flows like manual and auto renewal, and upgrade.
CardPayment				Optional (object)
				Include payment (credit/debit card) information that 2Checkout uses for recurring billing to renew imported subscriptions. Importing subscriptions with payment data is available only to eligible 2Checkout accounts. Contact 2Checkout directly for additional details.

Card payment

Add credit/debit card details when importing subscriptions. 2Checkout uses payment information in the recurring billing process.

For imports of test subscriptions, use the credit card information from this article.

Parameters	Type/Description
CardPayment	Object
CardNumber	Required (string)
	The credit/debit card number.
CardType	Required (string)
	VISA, VISAELECTRON, MASTERCARD, MAESTRO, AMEX, DISCOVER, DANKORT, CARTEBLEUE, JCB.
ExpirationYear	Required (string)
	The year in which the card expires.
ExpirationMonth	Required (string)
	The month in which the card expires.
HolderName	Required (string)
	Card holder name.
CCID	Required (string)
	Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
HolderNameTime	Required (int)
	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.
AutoRenewal	Optional (bool)
	True or false, depending on whether the customer or you enabled or disabled subscription auto-renewals.
CardNumberTime	Optional (int)
	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.

Save prices

Overview

Use the savePrices method to update product prices for a specific pricing configuration.

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.
Prices	BasicPrice Object
	Details below.
Quantities	Object
	Details below.
PriceOptions	Required (PriceOptionsAssigned object)
	Details below.
PricingConfigCode	Required (string)
	System-generated unique pricing configuration code. Read-only.
type	Require (string) • REGULAR • RENEWAL

Parameters	Type/Description
BasicPrice	Object
Currency	String
	The currency ISO code used for shipping costs - ISO 4217.
Amount	Float
	Basic price.

Parameters	Type/Description
Quantities	Object
MinQuantity	String
	The minimum quantity of volume discounts. Default is 1.
MaxQuantity	String
	The maximum quantity of volume discounts. Default is 99999.

Parameters	Type/Description
PriceOptionsAssigned	Object
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.

Response

bool(true)

<?php
require ('PATH_TO_AUTH');

/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Dynamic pricing configuration
 *
 * Send two prices, including the required one for the default currency
 * The method will append the prices for the sent entries, without removing the previous values
 *
 * If the quantities intervals were not defined then they will be set.
 * If the quantities overlap with existing defined intervals, an Exception will be thrown.
 */
 
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 140;
$Price->Currency = 'USD';
$Prices[] = $Price;
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 10;
 
$PriceOptions = array();
 
$PricingConfigurationCode = '5553603382';
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);

$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
// will output:
// bool(true)

 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the VOLTAGE pricing option group assigned and marked as required.
 * If prices are sent WITHOUT setting the pricing option group and options will set the price but without setting values for the options prices.
 */
 
// Call the login method for authentication
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
 
$i = 1; // counter for api calls
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
$sessionID = callRPC($jsonRpcRequest, $host);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
// if PricingOption group is not required, will set price for combination of QuantityInterval - no-pricing-option-value.
$PriceOptions = array();
 
// if PricingOption group is required, then send options by assigning a PriceOptionsAssigned object (group code and options)
// $optionAssigned = new stdClass(); // PriceOptionsAssigned
// $optionAssigned->Code = 'VOLTAGE';
// $optionAssigned->Options = array('220V'); // radio option group
// $PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
 
 
/**
 * ProductCode = 'PDOWNFILE'
 * Default currency: EUR
 *
 * Flat pricing configuration
 * Has the COLOR and scalenotmandatory pricing option group assigned and marked as required.
 */
// Call the login method for authentication
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
 
$i = 1; // counter for api calls
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
$sessionID = callRPC($jsonRpcRequest, $host);
 
// make call
$Prices = array();
 
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 10;
$Price->Currency = 'EUR';
$Prices[] = $Price;
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'COLOR'; // checkbox pricing option group, multiple values are allowed
$optionAssigned->Options = array('cyan', 'magenta');
$PriceOptions = array($optionAssigned);
 
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'scalenotmandatory'; // interval pricing option group
$optionAssigned->Options = array('scalenotmandatory-1-5');
$PriceOptions = array($optionAssigned);
 
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
 
$PriceOptions = array();
 
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
 
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'savePrices',
    'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
 
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
?>

Orders with dynamic product information

Overview

Dynamic products are a mechanism designed to enable you to pass purchase information directly from your system into 2Checkout without first configuring the products in your Control Panel or via API. Bypass the need for handling 2Checkout's catalog products and create orders with product information sent dynamically via API or through ConvertPlus URL parameters. Receive payments from your customers by using the products defined in your own system, or in your shopping cart applications.

Availability

This functionality is available only for merchants on the 2Sell and 2Subscribe accounts (PSP business model), for orders that are placed both through ConvertPlus/InLine ordering engines and API calls.

Dynamic Products Parameters

2Checkout allows you to create orders and receive payments by using the following product types:

PRODUCT - Item purchased by the customer. It is mandatory to send the name and price of the product item.
- Products can have pricing and recurring options assigned.
TAX - Additional fee/charge that will be considered 'Tax' in the ordering process. Taxes may have recurring options assigned.
SHIPPING - Item that contains the name and amount corresponding to the shipping method.
COUPON - Item that contains the discount to be applied to the entire order.

Orders with dynamic information allow you to control, without an existing setup, the following product attributes:

Price
- You have full control over the price applied to the purchase. Example: $20 price for product A.
Product pricing options (together with name and prices)
- You can pass the pricing options information dynamically. Example: A pricing option named users that adds a surcharge of $5 for option 3-5 users, and $10 for option 5-10 users.
Product purchase type
- Set the purchase type (tangible or intangible). Example: intangible for products delivered electronically.
Recurring options
- Set the product recurring options that include the contract length and unit, cycle length and unit, and recurring amount to be charged. Example: a recurring charge of $20, on a monthly basis for the next 2 years.

Reporting dynamic products

Orders placed with dynamic product information are included in your account reports and can be found in your Order Search area of the Control Panel, and in the Products Reports based on which your sales invoices are generated.

Dynamic products are not displayed in the Products section of the 2Checkout Control Panel.

How to place orders with dynamic information

Orders with dynamic products via API

Place orders via 2Checkout's latest API version and send the product information as part of the call. Create orders with dynamic product information, that contain the following product types: product, tax, shipping, and coupon.

Requirements

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

Limitations

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

How to test it?

You can place test orders via API with dynamic product information. Set the Payment details type to TEST in order to create an order in a test environment.

Place your first order with dynamic products

Read the documentation for guidance:

Orders with dynamic products via convertplus

Use ConvertPlus to create a dynamic ordering process by passing the product information to ConvertPlus through buy links parameters. With ConvertPlus dynamic ordering, you control the product name, price, recurring and pricing options, and many other product properties.

Learn more about ConvertPlus buy link parameters and dynamic ordering.

Alternatively, you can generate buy links for dynamic products directly from your Control Panel. Learn more about ConvertPlus dynamic ordering via Control Panel.

Overview

API 1.0 discontinuation

API 3.0 availability

API 3.0 what’s new and benefits

Serializations 1.0 vs. 3.0

WSDL 1.0 vs. 3.0

Methods 1.0 vs. 3.0

New use cases API 3.0

Overview

Requirements

How does the JavaScript Affiliate Checker work?

Installing the JavaScript Affiliate Checker

Overview

Attributes

Card payment

Overview

Requirements

Parameters

Overview

Parameters

Card payment

Overview

Parameters

Response

Overview

Availability

Dynamic Products Parameters

Reporting dynamic products

How to place orders with dynamic information

Orders with dynamic products via API

Limitations

How to test it?

Place your first order with dynamic products

Orders with dynamic products via convertplus

Need help?

Not yet a Verifone customer?