| Verifone Developer Portal

Subscription additional information fields

Overview

Use this object to assign, update, retrieve and delete additional information fields from your subscriptions.

Parameters

Parameters	Type/Description
fieldName	String
	The name of the additional information field. Used for identifying additional information fields.
fieldValue	String
	The value of the additional information field.

Overview

Get the price for a product in a new purchase scenario, based on the product ID, the pricing list it's assigned to, and specific pricing options.

Requirements

This method requires you to set a specific partner using setPartner.

Parameters

Parameter	Type/Description
sessionID	Required (string)
	Session identifier, which is the output of the Login method. An exception will be thrown if the values are incorrect.
productId	Required (string)
	The unique identifier of the product from your system.
pricingListCode	Required (string)
	The unique identifier of the pricing list.
priceOptions	Optional (StringArray)
	Array of pricing option codes. These identifiers mark the individual options inside pricing options configuration groups. Can be NULL.

Response

Parameter	Type/Description
UnitPrice	Object
	UnitPrice object.

Request

<?php

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

$productId = 'YOUR_PRODUCT_ID';
$pricingListCode = 'YOUR_PRICING_LIST_CODE';
$priceOptions = array(
'PRICE_OPTION_CODE_1',
'PRICE_OPTION_CODE_2'
);

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

Errors

Error	Description
INVALID_PARTNER	No partner is set.
PRODUCT_ERROR	Invalid product ID.
PARTNER_PRICING_LISTS_NOT_FOUND	There are no pricing lists with the provided code.
PRODUCT_NOT_FOUND	There is no active product with the provided ID in the given pricing list.

Overview

Use the assignPricingConfigurationOptionGroup method to assign a PricingOption Group to a PricingConfiguration.

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.
PricingConfigurationCode	Required (string)
	Unique, system-generated pricing configuration identifier.
PriceOptionsGroupAssigned	Required (Object)
	Details below.

Parameters	Type/Description
PriceOptionsGroupAssigned	Object
Code	Required (string)
	PricingOption Group identifier.
Required	Required (Object)
	True or false depending on whether the pricing options group is required during the purchase process or not.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$PricingConfigurationCode = 'YOUR_CODE';
$PriceOptionsGroupAssigned = new stdClass();
$PriceOptionsGroupAssigned->Code = 'USERSUSERS';
$PriceOptionsGroupAssigned->Required = TRUE;

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

?>

Place orders with dynamic product information

Overview

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

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

You can find a list of common errors that may arise when using the placeOrder call via APIv6 here.

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.

Supported payment methods

Credit/Debit cards: Visa, Visa electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
PayPal
Free orders (no payment information required).
2Pay.js

How to test?

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

Requirements

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

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

Send the following parameters as part of the PaymentMethod object:

Parameters	Description
Vendor3DSReturnURL	Required (string)
	URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
Vendor3DSCancelURL	Required (string)
	URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
WSOrder	String (optional)
	The WSOrder parameter is used to control the website URL displayed in the email messages shoppers receive after they place an order. By default, 2Checkout reports the URL set as Homepage in the Account information area. Adding WSOrder to the buy-links for your products will cause the optional website address set by using the parameter to override and replace the Homepage URL in the email notifications sent to customers. The behavior is similar to the WS_ORDER parameter supported on checkout/cart pages and described here.

Limitations

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

Parameters

Name

Parameters					Type/Description
Currency					Optional (string)
					The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country					Optional (string)
					Shopper country. ISO 3166 two-letter code. Example: “us.”
Language					Optional (string)
					ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference					Optional (string)
					Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.
Source					Optional (string)
					The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters.
CustomerReference					Optional (Int)
					External customer ID you can attach to the customer.
Affiliate					Object/Optional
AffiliateCode					String/Required
					The affiliate unique code (as returned by the affiliates API methods).
AffiliateSource					String/Optional
					The affiliate source.
MachineId					Optional (string)
					Unique, system generated code for each unique customer, identifying returning customers.
Items					Required (array of objects)
					Details below.
	Code				Optional (string)
					Should be sent as NULL. Any other value is ignored.
	Quantity				Required (integer)
					Number of units purchased.
	isDynamic				Required (bool)
					Send TRUE for orders with dynamic product information.
	Tangible				Required (bool)
					Possible values: FALSE for products delivered electronically. TRUE for tangible products, that require physical delivery.
	PurchaseType				Required (string)
					Purchase types available are: PRODUCT - item purchased by the customer. Can have pricing options and recurring properties attached. TAX - additional handling fee added to the purchase. SHIPPING - shipping fee applied to purchase. COUPON - amount deducted from total order price. Send positive values.
	PriceOptions				Optional (array of objects)
					Array of price option groups.
		Name			Optional (string)
					Name of the pricing option group.
		Options			Optional (array of objects)
					Array of pricing options.
			Name		Optional (string)
					Pricing option name.
			Value		Optional (string)
					Pricing option code.
			Surcharge		Optional (double)
					Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order.
	RecurringOptions				Optional (Object)
					Contains recurring options.
		CycleLength			Optional (int)
					The length of the recurring billing cycle.
		CycleUnit			Optional (string)
					Unit of measuring billing cycles (years, months).
		CycleAmount			Optional (int)
					The amount to be billed on each renewal.
		ContractLength			Optional (int)
					The contact length for which the recurring option will apply.
		ContractUnit			Optional
					Unit of measuring contact length (years, months).
	Name				Required (String)
					Product name.
	Price				Required (Object)
					Details below.
		Amount			Required (Int)
					Amount of the product.
		Type			Optional (string)
					Send "CUSTOM" for dynamic pricing.
	Trial				Optional (Object) – Can be NULL
					Details below.
		Period			Optional (integer)
					The length of the trial subscription lifetime in days.
		Price			Optional (double)
					Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
	AdditionalFields				Optional (array of objects) – Can be NULL
		AdditionalFieldSet			Optional (Object) – Can be NULL
					Details below
			Code		Optional (string)
					Identifier code for the additional field.
			Text		Optional (string)
					Text displayed in the additional field.
			Value		Optional (string)
					Additional field value.
	SubscriptionStartDate				Optional (string)
					Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST. Send empty or NULL to activate subscriptions on the same date when customers purchase them. You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
BillingDetails					Required (Object)
					Details below.
	FirstName				Required (string)
					Shopper name.
	LastName				Required (string)
					Shopper surname.
	CountryCode				Required (string)
					Shopper country. ISO 3166 two-letter code.
	State				String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
					The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
	City				Required (string)
					Shopper city.
	Address1				Required (string)
					Shopper address.
	Address2				Optional (string)
					Shopper address.
	Zip				Required (string)
					ZIP/ Postal code.
	Email				Required (string)
					Shopper email address.
	Phone				Optional (string)
					Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
	Company				Optional (string)
					Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
	FiscalCode				Optional (string) – Required for Brazil
					• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name. • Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ). • Mandatory when you set India as the Billing Country, and purchase is made by a Company. • Can be NULL for end users.
	TaxExemptionId				Optional (string)
					Tax Exempt Certification id used to deduct taxes for US orders. Example: `1b80eecc349v`
DeliveryDetails					Required (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				String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
					The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
	City				Optional (string)
					Shopper city from the delivery details.
	Address1				Optional (string)
					Shopper address from the delivery details.
	Address2				Optional (string)
					Shopper address from the delivery details.
	Zip				Optional (string)
					ZIP/ Postal code from the delivery details.
	Email				Optional (string)
					Shopper email address from the delivery details.
	Phone				Optional (string)
					Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
	Company				Optional (string)
					Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
DeliveryInformation					Object / Optional For products that require physical delivery, use this object to send the shipping method.
	ShippingMethod				Object Details below
		Code			String
					System-generated identified for your shipping method configuration.
PaymentDetails					Required (Object)
					Adapt this object to the desired payment method.
	Type				Required (string)
					The payment method: CC (credit/debit card - including local Brazilian cards). ENCRYPTED_PAYMENT_DATA (client-side encryption) PAYPAL PAYPAL_EXPRESS TEST (for test orders). PREVIOUS_ORDER(place new orders using the reference of a previous order). EXISTING_PAYMENT_DATA (use a card one of your customers already used to purchase from your account). WIRE – the placeOrder response includes Wire payment details. CHECK – the placeOrder response includes Check payment details. WE_CHAT_PAY (for WeChat payments). IDEAL (for iDEAL payments). PURCHASEORDER - use for orders with POs. FREE – for 0 value orders for which you’re not requiring customers to provide payment details. EES_TOKEN_PAYMENT (2Pay.js) GOOGLE PAY
	Currency				Required (string)
					The currency ISO code for the payment - ISO 4217. Example: “usd.”
	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.
	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.
		CardPayment			Optional (object)
					Details below.
				CardNumber	Required (string)
					The credit/debit card number.
				CardType	Required (string)
					visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
				ExpirationYear	Required (string)
					The year in which the card expires.
				ExpirationMonth	Required (string)
					The month in which the card expires.
				HolderName	Required (string)
					Cardholder name.
				Vendor3DSReturnURL	Required (string)
					URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
				Vendor3DSCancelURL	Required (string)
					URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
				CCID	Optional (string)
					Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
				HolderNameTime	Optional (float)
					The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
				CardNumberTime	Optional (float)
					The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
				InstallmentsNumber	Optional (Int)
					Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments.
	CustomerIP				Optional (string)
					Shopper IP.
Promotions					Optional (Array of strings)
					Array of promotion codes.
LocalTime					Optional (string)
					Local shopper time in the following format: Y-m-d H:i:s. This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.

Customer IDs

Overview

The 2Checkout system creates Customer IDs by default for all subscriptions it generates.

Unique customer IDs

Customers purchasing products/subscriptions sold through the 2Checkout platform can be assigned a unique customer IDs that you control in addition to the unique 2Checkout customer IDs created and assigned automatically.

External Customer IDs and 2Checkout Customer IDs are complementary.

Customer IDs can be:

Unique alphanumeric ID (string) defined per-customer.
Unique numerical (integer) ID generated by the 2Checkout system automatically.

Create external customer ID

When changing the Customer billing details of an account, you also have the option of providing the external customer ID if none exists.

You can enter any unique alphanumeric ID (string) as long as it's not already used as the external identifier of an existing Customer, in which case you'll receive the following error message: "The External ID you entered is used by another customer account. Please enter a new External ID and try again."

Edit external customer ID

When changing the Customer billing details of an account, you also have the option of editing an existing external customer ID.

External references can be swapped for any unique alphanumeric ID (string) you wish as long as an existing customer account in the 2Checkout system isn't already using the same identifier.

Import customer IDs

When importing subscriptions, the 2Checkout system automatically generates subscriptions to match the data in the CSV file used for the importing process.

The existing importing functionality of the 2Checkout system was expanded to support external customer IDs. In this regard, you can specify an ExternalCustomerId for each of the subscriptions that you import.

Optional Fields	Description	Required
ExternalCustomerId	The identifier for the same customer using one or more subscriptions. ExternalCustomerId is stored into the 2Checkout system and can subsequently be used for management tasks impacting Customers.	NO

Importing a new subscription

Specify the desired ExternalCustomerId in the column of the CSV file when importing a new subscription to have the 2Checkout system create a new Customer Account with the identifier for that specific subscription.

Edit customer IDs

Use the subscription import functionality offered by the 2Checkout platform in order to edit customer IDs.

Specify a new ExternalCustomerId in the column of the CSV file when importing an existing subscription to have the 2Checkout system update the associated Customer account, replacing the old ID with the new identifier.

Customer IDs in LCNs and IPNs

AVANGATE_CUSTOMER_REFERENCE - Default customer numerical (integer) IDs generated automatically by the 2Checkout system.

EXTERNAL_CUSTOMER_REFERENCE - Unique customer alphanumeric (string) identifiers that you control.

The 2Checkout system creates the Avangate Customer ID (AVANGATE_CUSTOMER_REFERENCE) by default for successfully placed orders that include products generating subscriptions. AVANGATE_CUSTOMER_REFERENCE is always included in both IPN and LCN.

Unique customer identifiers (EXTERNAL_CUSTOMER_REFERENCE) that you control are only included in LCN and IPN provided that you set them up via:

The Buy Link using the CUSTOMERID parameter
Orders placed using the 2Checkout API

In scenarios in which you don't provide a unique customer identifier, EXTERNAL_CUSTOMER_REFERENCE will be empty in both IPN and LCN when they're first sent out.

Adding a unique customer identifier after the order was finalized won't trigger the LCN on its own. However, the next time that the LCN is generated for updates impacting the license directly, the notification will also include the EXTERNAL_CUSTOMER_REFERENCE you added. The same behavior applies to scenarios in which you move a subscription under a specific customer.

Buy-link Customer ID Parameter

External customer ID in buy-links

Create new Customer accounts for subscriptions generated when shoppers purchase your products. You can use the CUSTOMERID (case sensitive) parameter to set external identifiers in the buy links of the products purchased by your customers. Note: Products need to have the renewal system enabled and a subscription generated as a part of the purchasing process for Customer accounts to be created or updated accordingly.

Add the CUSTOMERID parameter to a buy link generated using the Sales Links area of the Control Panel. For example, the following link:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567

should be changed to

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&CUSTOMERID=999999a

If the no existing Customer Accounts feature the 999999a identifier, then a new Customer Account will be created using the external reference you specified.

Attribute a subscription to an existing customer

Aggregate subscriptions under the same Customer account if the products they're associated with are purchased by the same shopper by taking advantage of theCUSTOMERID (case sensitive) parameter added to buy links.

You can use and existing external customer ID for a Customer account already generated in the 2Checkout system to place new orders.

Let's assume that a customer account with the 999999a CUSTOMERID (external customer reference) was already created for one of your shoppers for a previous order. When the same shopper places a new order using the 2Checkout platform, the subscriptions generated will automatically be grouped under the same Customer account provided that the purchase is done using a buy link which features &CUSTOMERID=999999a.

For example, the following link:

https://secure.2checkout.com/order/checkout.php?PRODS=1234999

should be changed to

https://secure.2checkout.com/order/checkout.php?PRODS=1234999&CUSTOMERID=999999a

to ensure that any new subscriptions generated will be aggregated under the existing Customer accounts with the 999999a identifier.

Place orders using the Avangate Customer Reference (ID) AV_CUSTOMERID

The 2Checkout system generates default customer numerical (integer) IDs automatically for all orders containing products that feature subscriptions. Once created, Avangate customer references can be used for new acquisitions aggregating new subscriptions under an existing Customer account.

Note: Avangate customer references are spawned automatically by the 2Checkout system. While you're able to use them to place new orders for existing customers, you can't set your own Avangate customer references. However, you can create and edit External customer references according to your needs. External Customer IDs and Avangate Customer IDs can coexist.

Existing system-generated IDs can serve to group new subscriptions under already created Customer accounts, by using the AV_CUSTOMERID (case sensitive) parameter in the Buy Links for orders.

Assume that a Customer account with the 123456789 AV_CUSTOMERID (internal Avangate customer reference) was already created for one of your shoppers for a previous order. When the same shopper places a new order using the 2Checkout platform, the subscriptions generated will automatically be grouped under the same Customer account provided that the purchase is done using a buy link which features &AV_CUSTOMERID=123456789. All subscriptions generated as a result of this order will automatically be grouped under the customer featuring the 123456789 system generated ID.

Note: AV_CUSTOMERID can only be used for new acquisitions made by existing customers, which have already had an internal Avangate customer reference attributed to them.

If parameters for both an Avangate Customer ID and an External Customer ID are used in the Buy Link for the same order, the internal Avangate customer reference will take precedence over the external identifier (that will be ignored by the system. )

Customer reference scenarios
Avangate Customer ID (internal, system-generated customer reference) is used	External Customer ID (external customer reference) is used	Result
NO (new order without AV_CUSTOMERID in the Buy Link)	NO (new order without CUSTOMERID in the Buy Link)	New customer account is generated using the order billing details. New Avangate customer reference is also created for the account.
NO (new order without AV_CUSTOMERID in the Buy Link)	YES (new order with CUSTOMERID in the Buy Link)	New customer account is generated using the order billing details. New Avangate customer reference is also created for the account. The customer account will feature the External customer reference provided.
YES (new order with AV_CUSTOMERID in the Buy Link)	YES (new order with CUSTOMERID in the Buy Link, but identifier is either new or different than the one featured by the customer account for which the Avangate customer reference was provided)	Subscriptions generated are automatically assigned to the customer account featuring the Avangate customer reference provided in the Buy Link.
YES (new order with AV_CUSTOMERID in the Buy Link)	NO (new order without CUSTOMERID in the Buy Link)	Subscriptions generated are automatically assigned to the customer account featuring the Avangate customer reference provided in the Buy Link.
YES (new order with AV_CUSTOMERID in the Buy Link)	YES (new order with CUSTOMERID in the Buy Link, and the identifiers is the same as the one featured by the customer account for which the Avangate customer reference was provided)	Subscriptions generated are automatically assigned to the customer account featuring the Avangate customer reference provided in the Buy Link.
NO (new order without AV_CUSTOMERID in the Buy Link)	YES (new order with CUSTOMERID in the Buy Link, and the identifiers used is an External customer reference for and existing customer account)	Subscriptions generated are automatically assigned to the customer account featuring the External customer reference provided in the Buy Link.

Customer reference scenarios

Avangate Customer ID

(internal, system-generated customer reference)

is used

External Customer ID

(external customer reference) is used

Result

(new order without AV_CUSTOMERID in the Buy Link)

(new order without CUSTOMERID in the Buy Link)

New customer account is generated using the order billing details.

New Avangate customer reference is also created for the account.

(new order without AV_CUSTOMERID in the Buy Link)

YES

(new order with CUSTOMERID in the Buy Link)

New customer account is generated using the order billing details.

New Avangate customer reference is also created for the account.

The customer account will feature the External customer reference provided.

YES

(new order with AV_CUSTOMERID in the Buy Link)

YES

(new order with CUSTOMERID in the Buy Link, but identifier is either new or different than the one featured by the customer account for which the Avangate customer reference was provided)

Subscriptions generated are automatically assigned to the customer account featuring the Avangate customer reference provided in the Buy Link.

YES

(new order with AV_CUSTOMERID in the Buy Link)

(new order without CUSTOMERID in the Buy Link)

Subscriptions generated are automatically assigned to the customer account featuring the Avangate customer reference provided in the Buy Link.

YES

(new order with AV_CUSTOMERID in the Buy Link)

YES

(new order with CUSTOMERID in the Buy Link, and the identifiers is the same as the one featured by the customer account for which the Avangate customer reference was provided)

Subscriptions generated are automatically assigned to the customer account featuring the Avangate customer reference provided in the Buy Link.

(new order without AV_CUSTOMERID in the Buy Link)

YES

(new order with CUSTOMERID in the Buy Link, and the identifiers used is an External customer reference for and existing customer account)

Subscriptions generated are automatically assigned to the customer account featuring the External customer reference provided in the Buy Link.

Network Cross-selling

The Customer ID used in the buy link is limited to the customers of the vendor which owns the shopping cart. Subscriptions from third-party 2Checkout vendors will not be associated with the same customer ID as that of the main vendor.

Order with dynamic products

Overview

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

Attributes

Parameters

Type/Description

RefNo

Optional (string)

Avangate generates unique reference numbers for all orders (purchases). You can use this parameter to retry authorizations for orders with failed transactions by changing the payment method.

NULL when you place new orders.

OrderNo

Optional (string)

The consecutive order number Avangate associates with orders and displays in the Order search area of your account.

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.

ShopperRefNo

Optional (string)

External shopper identifier.

Status

Optional (string)

The status of the order:

AUTHRECEIVED – Avangate blocks the amount corresponding to the transaction, but the process of collecting funds is incomplete.
PENDING - Avangate has yet to block the amount corresponding to the transaction or shoppers used an offline payment method like wire transfer.
COMPLETE – The shopper completed the transaction for the purchase and Avangate or you fulfilled the order (when required).
CANCELED – Avangate cancels orders for which shoppers fail to transfer funds in due time.
REVERSED – Avangate reverses order transactions that never reach the Complete/Finished stage. Shoppers never complete transactions for such purchases.
REFUND – Avangate refunds orders only after they reach the Complete/Finished stage and returns the funds collected to shoppers.

ApproveStatus

Optional (string)

The status of the order resulted from the evaluation by the Avangate anti-fraud system or by a member of the anti-fraud department. This status varies for new purchases and for orders requiring customers to make manual payments.

Possible values:

WAITING: The Avangate anti-fraud system or a member of the anti-fraud department has yet to approve the order.
OK: The Avangate anti-fraud system or a member of the anti-fraud department approved the order.
INVALIDDATA: Shopper-supplied data is invalid – Avangate did not approve the order.
FRAUD: The order is fraudulent.

VendorApproveStatus

Optional (string)

Shows if you approved or not a partner order. Possible values:

OK
WAITING
REJECTED

Language

Optional (string)

ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”

OrderDate

Optional (string)

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when customers place their orders.

FinishDate

Optional (string)

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when the order reach the Complete status.

NULL for order that did not reach the Complete/Finished stage.

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. Cannot be null.

AffiliateSource

Optional (string)

The link source for affiliate referred sales. Similar to the functionality of the SRC (separate link identifier) parameter included into Buy Links, but controlled by the AFFSRC parameter. Affiliates use the AFFSRC parameter to track sale sources for their referrals. Maximum length 255 characters.

AffiliateId

Optional (int)

Identifier belonging to affiliates who refer orders.

AffiliateName

Optional (string)

Affiliate name.

AffiliateUrl

Optional (string)

Affiliate website URL from the Affiliate Details.

RecurringEnabled

Optional (boolean)

true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.

HasShipping

Optional (boolean)

true or false, depending on whether the order requires shipping.

BillingDetails

Optional (Object)

Details below.

FirstName

Optional (string)

Shopper name.

LastName

Optional (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. Avangate 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 the Billing Country is set to Brazil. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when the Billing Country is set to India and purchase is made by a Company.

• Can be null for end users.

DeliveryDetails

Optional (Object)

Optional. When missing, Avangate uses the same details as for the BillingDetails object.

Details below.

FirstName

Optional (string)

Shopper name from the delivery details.

LastName

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

Optional (Object)

Adapt this object to the desired payment method.

Type

Optional (string)

The payment method:

CC (credit/debit card - including local Brazilian cards).
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.
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)). For payments with credit cards, PalPay Express, previous order reference and purchase order use the objects below.

For payments with check and wire, send only the ‘CHECH’ and ‘WIRE’ strings.

null for 0 value orders for which you’re not requiring customers to enter payment details.

PaymentDetailsCard

Optional (object)

Details below.

CardType

Optional (string)

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

FirstDigits

Optional (string)

First four digits of the credit card.

LastDigits

Optional (string)

Last four digits of the credit card.

CheckPaymentDetails

Optional (Object)

Details below.

Beneficiary

Optional (string)

The beneficiary of the payment.

Can be NULL.

CheckPostalAddress

Optional (string)

The address of the beneficiary.

Can be NULL.

Amount

Optional (double)

The total costs incurred by the customer for an order.

Can be NULL.

Currency

Optional (string)

The currency ISO code of the order/payment - ISO 4217.

Can be NULL.

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.

WirePaymentDetails

Optional (Object)

Details below.

Amount

Optional (double)

The total costs customers incur.

Can be NULL.

Currency

Optional (string)

The currency ISO code of the order - ISO 4217.

Can be NULL.

PaymentReference

Optional (string)

Transaction identifier.

Can be NULL.

RoutingNumber

Optional (string)

Identification number assigned to financial institutions.

Can be NULL.

BankAccounts

Optional (Array of objects)

Details below.

Beneficiary

Optional (string)

The beneficiary of the payment.

Can be NULL.

BankName

Optional (string)

The name of the beneficiary's bank.

Can be NULL.

BankCountry

Optional (string)

The country of the beneficiary's bank.

Can be NULL.

BankCity

Optional (string)

The city of the beneficiary's bank.

Can be NULL.

BankAddress

Optional (string)

The address of the beneficiary's bank.

Can be NULL.

BankAccount

Optional (string)

The number for the account in which customers transfer the funds.

Can be NULL.

BankAccountIban

Optional (string)

The IBAN of the beneficiary's bank.

Can be NULL.

BankAccountSwiftCode

Optional (string)

The Swift Code of the beneficiary's bank.

Can be NULL.

Currency

Optional (string)

The currency ISO code for the bank account - ISO 4217.

Can be NULL.

CustomerIP

Optional (string)

Shopper IP.

CustomerDetails

Object

Avangate populates the parameters of the customer entity with information from the customer whose AvangateCustomerReference or ExternalCustomerReference you send during the purchase.

Details below.

AvangateCustomerReference

Optional (Int)

System-generated Avangate customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The Avangate system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.

ExternalCustomerReference

Optional (string)

The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter to buy links.

FirstName

Optional (string)

Customer's first name.

LastName

Optional (string)

Customer's last name.

CountryCode

Optional (string)

Customer's country code (ISO 3166 two-letter code).

State

Optional (string)

Customer's state. For example, "Alabama","Alaska","Arizona".

City

Optional (string)

Customer's city.

Address1

Optional (string)

Customer's address.

Address2

Optional (string)

Customer's address.

Zip

Optional (string)

Zip code.

Email

Optional (string)

Customer's email.

Phone

Optional (string)

Customer's phone number.

Company

Optional (string)

Company name.

FiscalCode

Optional (string)

For companies, it needs to be the VAT ID. Avangate validates this values and throws an error if the VAT ID is invalid/incorrect. When present, you need to also provide Company name.

Can be null for end users.

Fax

Optional (string)

Customer's fax number.

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.

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

ExistingCards

Optional (Array of objects)

Details below.

TransientToken

Optional (Object)

Populated only 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, hipercard, elo

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.

Origin

Optional (String)

Avangate automatically tracks the source of purchases:

Web – When customers use the desktop version of the Avangate shopping cart.
API - When customers use a custom, API-based ordering interface.
Mobile - When customers use the mobile version of the Avangate shopping cart.
Automatic Billing – For auto-renewals and trial conversions.

AvangateCommission

Optional (Int)

Avangate's commission for the order.

OrderFlow

Optional (string)

PURCHASE_ORDER - Sent only when shoppers used Purchase Orders.

REGULAR - Sent in all other cases.

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. Avangate uses this email for the delivery/fulfillment process.

GiftNote

Optional (string)

Custom text shoppers provide as a message to the gift recipient.

PODetails

Object (optional)

Details below.

Status

Optional (string)

PO status. Possible values:

PO status API	PO status cPanel
AWAITING_UPLOAD	Awaiting form submission - Waiting for the customer to submit the PO form
TIME_EXPIRED	Expired, form not received - The customer did not submit the PO form
AWAITING_MERCHANT	Awaiting your confirmation - PO approved by Avangate, awaiting vendor confirmation
MERCHANT_TIME_EXPIRED	Expired, PO not confirmed - You didn't confirm/reject the PO
AWAITING_MERCHANT	Rejected - You rejected the PO
AWAITING_PAYMENT	Awaiting payment - You approved the PO, waiting for payment
AWAITING_PAYMENT	Expired, not paid - The customer did not complete the PO payment. Avangate accepts payments up to 30 days after the PO payment interval expires
NOT_PAID	Canceled, not paid - The customer did not complete the PO payment
NOT_PAID	Canceled by Avangate - Avangate canceled the PO
NOT_PAID	Canceled via API - You canceled the PO (via API)
PAID	Complete - Customer paid the PO. The order is complete

AutoApprove

Optional (Boolean)

TRUE or FALSE, depending on whether you set POs to auto-approve or not.

RequireDocumentUpload

Optional (Boolean)

TRUE or FALSE, depending on whether require document upload or not.

NetPaymentTerms

Optional (Integer)

The term of net payment in days.

CopyPreviousDocuments

Optional (Boolean)

TRUE or FALSE, depending on whether copy documents from previous order or not.

PdfFormUrl

Optional (String)

URL of Purchase Order form which needs to be printed, signed and uploaded.

ExtraInformation

Optional (Object)

Details below.

PaymentLink

Optional (String)

Can be:

1. The PO doc upload link - If you set AutoApprove as FALSE on the original order and before shoppers upload the PO.

2. Payment link for orders with POs. Business customers can use the PaymentLink to finalize payment for orders with POs. If you set AutoApprove as TRUE on the original order and if Avangate and you approve the PO.

PartnerCode

Optional (string)

Partner code you configured for your partner. NULL for eStore orders.

PartnerMargin

Optional (double)

Partner margin you set for the order. NULL for eStore orders.

PartnerMarginPercent

Optional (double)

The percentage of the partner margin from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders.

ExtraMargin

Optional (double)

Extra margin you offer by editing partner orders. NULL for eStore orders.

ExtraMarginPercent

Optional (double)

The percentage of the extra partner margin from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders.

ExtraDiscount

Optional (double)

Extra discount you offer by editing partner orders. NULL for eStore orders.

ExtraDiscountPercent

Optional (double)

The percentage of the partner margin from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders.

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.

TestOrder

Optional (Boolean)

True for test orders. False of regular orders.

Errors

Optional (StringArray)

Payment gateway processing errors.

Items

Array of objects

Details below.

ProductDetails

Object

Name

Optional (string)

Product name.

ExtraInfo

Optional (string)

The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.

RenewalStatus

Optional (boolean)

true for orders renewing subscriptions.
false for all other orders: new purchases, upgrades.

Subscriptions

Object

SubscriptionReference

Optional (string)

Unique, system-generated subscription identifier.

PurchaseDate

Optional (string)

The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the Avangate system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

e.g. 2015-08-11 15:18:52

SubscriptionStartDate

Optional (string)

Example: 2015-09-29 17:57:59

ExpirationDate

Optional (string)

The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.

Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

e.g. 2015-09-11 15:18:52

Lifetime

Optional (boolean)

true – For non-recurring, evergreen subscriptions.
false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.

Trial

Optional (boolean)

true – For trial subscriptions.
false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.

Enabled

Optional (boolean)

true – For active and past due subscriptions.
false – For expired and cancelled subscriptions.

RecurringEnabled

Optional (boolean)

true – For subscriptions with active recurring options
false – For subscriptions without recurring options.

Tangible

Optional (boolean)

true – For products with physical delivery.
false – For products that don't require physical delivery.

IsDynamic

Optional (boolean)

true – For products created with dynamic information.
false – For catalog products.

ShortDescription

Optional (string)

Short product description

DeliveryInformation

Optional (object)

Details below.

Delivery

Optional (string)

Delivery information.

DownloadFile

Optional (object)

Information related to the download file.

DeliveryDescription

Optional (string)

Delivery description.

CodesDescription

Optional (string)

Description of the codes delivered.

Codes

Optional (array)

Array with the codes delivered.

PriceOptions

Optional (array of objects)

Array of price option groups.

Code

Optional (string)

Pricing option code.

Name

Optional (string)

Pricing option name.

Required

Optional (boolean)

Possible values:

true, if the pricing option is mandatory
false, if the pricing option is optional

Options

Optional (array of objects)

Array of pricing options.

Name

Optional (string)

Pricing option name.

Value

Optional (string)

Pricing option code.

Surcharge

Optional (double)

Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order.

Price

Object

This object returns the price per unit at order line level.

In the case of trials, the object returns the costs for the trial to full subscription conversion.

UnitNetPrice

Optional (double)

The value per product unit, excluding sales tax/VAT expressed in the payment currency.

UnitGrossPrice

Optional (double)

Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

UnitVAT

Optional (double)

Sales tax/VAT per product unit expressed in the payment currency.

UnitDiscount

Optional (double)

Value of the discount per product unit expressed in the payment currency.

UnitNetDiscountedPrice

Optional (double)

The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which Avangate deducts the unit discount.

UnitGrossDiscountedPrice

Optional (double)

Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.

UnitAffiliateCommission

Optional (double)

Value of the affiliate commission per product unit calculated expressed in the payment currency.

Avangate deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

Avangate does not take into account shipping costs when calculating affiliate commissions.

NULL when Avangate does not apply an affiliate commission.

Currency

Optional (string)

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

NetPrice

Optional (double)

The value per order line, excluding sales tax/VAT expressed in the payment currency.

GrossPrice

Optional (double)

Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

NetDiscountedPrice

Optional (double)

The NetPrice value per order line (in the payment currency), excluding sales tax/VAT, from which Avangate deducts discounts.

GrossDiscountedPrice

Optional (double)

Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.

Example:

UnitNetPrice: 99
UnitGrossPrice: 120.39
UnitVAT: 21.39
UnitDiscount: 9.9
UnitNetDiscountedPrice: 89.1
UnitGrossDiscountedPrice: 110.49
UnitAffiliateCommission: 22.28
Currency: "usd"
NetPrice: 198
GrossPrice: 240.77
NetDiscountedPrice: 178.2
GrossDiscountedPrice: 220.97
Discount: 19.8
VAT: 42.77
AffiliateCommission: 44.56

Discount

Optional (double)

Value of the discounts per order line expressed in the payment currency.

VAT

Optional (double)

Value of sales tax/VAT per order line expressed in the payment currency.

AffiliateCommission

Optional (double)

Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions.

Quantity

Optional (integer)

Number of units

SKU

Optional (string)

SKU identifier.

PurchaseType

Optional (string)

Purchase type for orders placed with dynamic information. Possible values:

PRODUCT
TAX
COUPON
SHIPPING

ExternalReference

Optional (string)

External order reference.

SubscriptionStartDate

Optional (string)

Set subscription starting date.

CrossSell

Optional (Object)

Details below.

ParentCode

Optional (string)

The product code of the master product you set to trigger the campaign.

CampaignCode

Optional (string)

Unique, system-generated identifier for cross-sell campaigns.

Trial

Optional (Object)

Details below.

Period

Optional (integer)

The length of the trial subscription lifetime in days.

GrossPrice

Optional (double)

Total trial price in the payment currency before Avangate deducts any taxes, discounts, etc.

VAT

Optional (double)

The total value of taxes for the trial in the payment currency, before Avangate deducts any discounts.

NetPrice

Optional (double)

Total trial price in the payment currency, not including taxes, before Avangate deducts any discounts.

AdditionalFields

Optional (array of objects)

Details below.

Code

Optional (string)

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

Text

Optional (string)

Field text visible to shoppers in the cart.

Value

Optional (string)

Selected field value.

Promotion

Optional (object)

Details below.

Name

Optional (string)

Promotion name.

Description

Optional (string)

Promotion description.

StartDate

Optional (string)

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

EndDate

Optional (string)

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

MaximumOrdersNumber

Optional (integer)

Avangate only applies the promotion to a maximum number of orders you define.

Can be NULL if you want the promotion to apply to an unlimited number of orders.

MaximumQuantity

Optional (integer)

Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

InstantDiscount

Optional (boolean)

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

Coupon

Optional (string)

Promotion coupon/voucher.

DiscountLabel

Optional (string)

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

Enabled

Optional (string)

true or false, depending on whether a promotion is active or disabled.

Type

Optional (string)

REGULAR – product/cart line level discounts.
ORDER – quantity discounts.
GLOBAL – order-level discounts.
AFFILIATE – for discounts created by affiliates.

Promotions

Optional (Array of objects)

Details below.

Name

Optional (string)

Promotion name.

Description

Optional (string)

Promotion description.

StartDate

Optional (string)

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

EndDate

Optional (string)

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

MaximumOrdersNumber

Optional (integer)

Avangate only applies the promotion to a maximum number of orders you define.

Can be NULL if you want the promotion to apply to an unlimited number of orders.

MaximumQuantity

Optional (integer)

Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

InstantDiscount

Optional (boolean)

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

Coupon

Optional (string)

Promotion coupon/voucher.

DiscountLabel

Optional (string)

Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.

Enabled

Optional (string)

true or false, depending on whether a promotion is active or disabled.

Type

Optional (string)

REGULAR – product/cart line level discounts.
ORDER – quantity discounts.
GLOBAL – order-level discounts.
AFFILIATE – for discounts created by affiliates.

AdditionalFields

Optional (array of objects)

Details below.

Code

Optional (string)

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

Text

Optional (string)

Field text visible to shoppers in the cart.

Value

Optional (string)

Selected field value.

Currency

Optional (string)

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

NetPrice

Optional (double)

Order value excluding sales tax/VAT expressed in the payment currency.

GrossPrice

Optional (double)

Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.

NetDiscountedPrice

Optional (double)

The NetPrice order value excluding sales tax/VAT, from which Avangate deducts discounts. NetDiscountedPrice is expressed in the payment currency.

GrossDiscountedPrice

Optional (double)

Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.

For example:

Currency: "usd"
NetPrice: 396
GrossPrice: 486.29
NetDiscountedPrice: 376.2
GrossDiscountedPrice: 466.49
Discount: 19.8
VAT: 90.29
AffiliateCommission: 94.05

Discount

Optional (double)

Value of the discounts for an order expressed in the payment currency.

VAT

Optional (double)

Value of sales tax/VAT expressed in the payment currency.

AffiliateCommission

Optional (double)

Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions.

MerchantCode

Optional (string)

Merchant account code. Can be found in Control Panel, System Settings.

Place orders with dynamic product information

Overview

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

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

Supported payment methods

Credit/Debit cards: Visa, Visaelectron, MasterCard, Maestro, Amex, Discover, Dankort, Cartebleue, JCB. Avangate supports local Brazilian cards.
PayPal
Free orders (no payment information required).
2Pay.js

How to test?

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

Requirements

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

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.

Attributes

Parameters								Type/Description
Currency								Optional (string)
								The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country								Optional (string)
								Shopper country. ISO 3166 two-letter code. Example: “us.”
Language								Optional (string)
								ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference								Optional (string)
								Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.
Source								Optional (string)
								The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters.
CustomerReference								Optional (Int)
								System-generated Avangate customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The Avangate 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.
			Code					Optional (string)
								Should be send as NULL. Any other value will be ignored.
			Quantity					Required (integer)
								Number of units
			isDynamic					Required (bool)
								Send true for creating orders with dynamic order information.
			Tangible					Required (bool)
								Send false for product delivered electronically.
			PurchaseType					Required (string)
								Purchase types available are: PRODUCT, TAX, SHIPPING and COUPON.
			PriceOptions					Optional (array of objects)
								Array of price option groups.
				Name				Optional (string)
								Name of the pricing option group. Mandatory for dynamic products.
				Options				Optional (array of objects)
								Array of pricing options.
					Name			Optional (string)
								Pricing option name. Mandatory for dynamic products.
					Value			Optional (string)
								Pricing option code. Mandatory for catalog products.
					Surcharge			Optional (double)
								Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order. Mandatory for dynamic products.
			RecurringOptions					Optional (Object)
								Contains recurring options.
					CycleLength			Optional (int)
								The length of the recurring billing cycle.
					CycleUnit			Optional (string)
								Unit of measuring billing cycles (years, months).
					CycleAmount			Optional (int)
								The amount to be billed on each renewal.
					ContractLength			Optional (int)
								The contact length for which the recurring option will apply.
					ContractUnit			Optional
								Unit of measuring contact length (years, months).
			Price					Required (Object)
								Details below.
					Amount			Required (Int)
								Amount of the product.
					Type			Optional (string)
								Send "CUSTOM" for dynamic pricing.
			Trial					Optional (Object) – Can be NULL
								Details below.
					Period			Optional (integer)
								The length of the trial subscription lifetime in days.
					Price			Optional (double)
								Total trial price in the payment currency before Avangate deducts any taxes, discounts, etc.
			AdditionalFields					Optional (array of objects) – Can be NULL
					AdditionalFieldSet			Optional (Object) – Can be NULL
								Details below
							Code	Optional (string)
								Identifier code for the additional field.
							Text	Optional (string)
								Text displayed in the additional field.
							Value	Optional (string)
								Additional field value.
			SubscriptionStartDate					Optional (string)
								Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST. Send empty or NULL to activate subscriptions on the same date when customers purchase them. You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, Avangate uses 00:00:01. Default time zone GMT+02:00.
BillingDetails								Required (Object)
								Details below.
	Person							Object
								Details below.
		FirstName						Required (string)
								Shopper name.
		LastName						Required (string)
								Shopper surname.
		CountryCode						Optional (string)
								Shopper country. ISO 3166 two-letter code.
		State						String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
								The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
		City						Optional (string)
								Shopper city.
		Address1						Optional (string)
								Shopper address.
		Address2						Optional (string)
								Shopper address.
		Zip						Optional (string)
								ZIP/ Postal code.
		Email						Optional (string)
								Shopper email address.
		Phone						Optional (string)
								Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company						Optional (string)
								Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
		TaxExemptionId						Optional (string)
								Tax Exempt Certification id used to deduct taxes for US orders Example: `1b80eecc349v`
	FiscalCode							Optional (string) – Required for Brazil
								• For companies, it needs to be the VAT ID. Avangate will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name. • Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ). • Mandatory when you set India as the Billing Country, and purchase is made by a Company. • Can be NULL for end users.
DeliveryDetails								Required (Object)
								Details below.
	Person							Object
								Details below.
		FirstName						Required (string)
								Shopper name from the delivery details.
		LastName						Required (string)
								Shopper surname from the delivery details.
		CountryCode						Optional (string)
								Shopper country. ISO 3166 two-letter code from the delivery details.
		State						String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
								The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India 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. EES_TOKEN_PAYMENT (2Pay.js)
	Currency							Required (string)
								The currency ISO code for the payment - ISO 4217. Example: “usd.”
	RecurringEnabled							Optional (boolean)
								true – shopper checks the auto renewal checkbox and Avangate charges subscription renewals using a recurring billing process. false – shopper doesn’t check the auto renewal checkbox.
	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.
				CardPayment				Optional (object)
								Details below.
						CardNumber		Required (string)
								The credit/debit card number.
						CardType		Required (string)
								visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
						ExpirationYear		Required (string)
								The year in which the card expires.
						ExpirationMonth		Required (string)
								The month in which the card expires.
						HolderName		Required (string)
								Card holder name.
						Vendor3DSReturnURL		Required (string)
								URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
						Vendor3DSCancelURL		Required (string)
								URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
						CCID		Optional (string)
								Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
						HolderNameTime		Optional (float)
								The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
						CardNumberTime		Optional (float)
								The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
						InstallmentsNumber		Optional (Int)
								Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments.
				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 yourbuyer'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 Avangate 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 Avangate returns an error). Please contact Avangate. When AutoApprove is TRUE, Avangate no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. Avangate 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. Avangate 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 Avangate and that you need to approve. Avangate 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							Optional (string)
								Shopper IP.
Promotions								Optional (Array of strings)
								Array of promotion codes.
LocalTime								Optional (string)
								Local shopper time in the following format: Y-m-d H:i:s. This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.

Extract invoices

Overview

Use the getInvoices method to extract shopper invoices from the 2Checkout system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).

getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.

In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.

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.
RefNo	Required (string)
	Unique, system generated reference for orders.

Response

InvoicesData		Array of objects
		Details below.
	Sale	String
		Base64 encoded PDF file containing an invoice for a Complete order.
	Cancellation	String
		Base64 encoded PDF file containing a cancellation invoice.
	Refunds	Array of string
		Base64 encoded PDF files containing invoices for Refunds.

Request


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

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

Add comments to an order

Overview

Use this method to attach a comment when placing a partner order.

Requirements

Parameters

Parameter	Type/Description
sessionID	Required (String)
	Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
comment	Required (String)
	A comment visible to both you and the partner.

Response

Parameter	Type/Description
Response	Boolean
	True or false

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner
require('PATH_TO_addProduct'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/08Place_an_order/00Add_product_to_cart

$comment = 'YOUR_COMMENT';

try {
    $CommentSet= $client->setComment ($sessionID, $comment);
} catch (SoapFault $e) {
    echo " Comment: " . $e->getMessage();
    exit;
}
var_dump ("Comment", $CommentSet);

Errors

Error	Description
INVALID_COMMENT	The provided comment is empty.

Remove product from cart

Overview

Use this method to remove a product that was added to the shopping cart, during the current session.

Requirements

Parameters

Parameter	Type/Description
sessionID	Required (String)
	Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
productId	Required (Integer)
	Unique product identifier from the Avangate system.
priceOptions	Optional (StringArray)
	Array of price options codes. These identifiers mark the individual options inside pricing options configuration groups. This parameter must match exactly the pricing option combination of the product added to the cart in order for the product to be removed. Partner orders can involve the same product, bot ordered in multiple instances, each with different pricing options. Can be NULL.
quantity	Optional (Integer)
	Defines the number of product units added to cart that should be removed. If no quantity info is provided, the product is completely removed from cart. Can be NULL.

Response

Parameters	Type/Description
Result	Boolean
	True or false

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner
require('PATH_TO_addProduct'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/08Place_an_order/00Add_product_to_cart

$productId = 'YOUR_PRODUCT_ID';
$priceOptions = array(
'Pricing_options_group_code1',
'Pricing_options_group_code2'
);
$quantity = YOUR_QUANTITY;

try {
$RemoveProduct= $client->deleteProduct ($sessionID, $productId, $priceOptions, $quantity);
} catch (SoapFault $e) {
echo "ProductDeleted: " . $e->getMessage();
exit;
}
var_dump ("ProductDeleted ", $RemoveProduct);

Errors

Error	Description
EMPTY_CART	The shopping cart is empty.
PRODUCT_ERROR	There is no product with the specified settings in cart.

Overview

Parameters

Overview

Requirements

Parameters

Response

Request

Errors

Overview

Parameters

Response

Request

Overview

How to test?

Requirements

Limitations

Parameters

Overview

Unique customer IDs

Create external customer ID

Edit external customer ID

Import customer IDs

Importing a new subscription

Edit customer IDs

Customer IDs in LCNs and IPNs

Buy-link Customer ID Parameter

External customer ID in buy-links

Attribute a subscription to an existing customer

Place orders using the Avangate Customer Reference (ID) AV_CUSTOMERID

Network Cross-selling

Overview

Attributes

Overview

Supported payment methods

How to test?

Requirements

Limitations

Attributes

Overview

Parameters

Response

Request

Overview

Requirements

Parameters

Response

Request

Errors

Overview

Requirements

Parameters

Response

Request

Errors

Need help?

Not yet a Verifone customer?