Place orders with dynamic product information

Last updated: 30-Dec-2019

Rate this article:

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.

For more details about how to be PCI compliant before accepting CC payments, see this page.

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

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.

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

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.
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.
	Person							Object
								Details below.
		FirstName						Required (string)
								Shopper name.
		LastName						Required (string)
								Shopper surname.
		CountryCode						Optional (string)
								Shopper country. ISO 3166 two-letter code.
		State						Optional (string) – Required for US, Brazil, India and Romania
								The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
		City						Optional (string)
								Shopper city.
		Address1						Optional (string)
								Shopper address.
		Address2						Optional (string)
								Shopper address.
		Zip						Optional (string)
								ZIP/ Postal code.
		Email						Optional (string)
								Shopper email address.
		Phone						Optional (string)
								Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company						Optional (string)
								Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
	FiscalCode							Optional (string) – Required for Brazil
								• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name. • Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ). • Mandatory when you set India as 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						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.
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.
	Currency							Optional (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)
								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.
	CustomerIP							Required (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.

Rate this article:

Global eCommerce

In-Person Payments

Business Tools

Petroleum & Convenience

APIs

Place orders with dynamic product information