Skip to main content

Order object

Last updated: 14-Dec-2023
Rate this article:

Overview

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

Supported payment methods

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

Object parameters

 

Parameters   Type/Description

RefNo

 

Optional (string)

 

 

Unique, system-generated, order reference number.

 

Do not include it when placing new orders or send it as NULL.

Currency

 

Optional (string)

 

 

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

Country

 

Optional (string)

 

 

Shopper country. ISO 3166 two-letter code. Example: “us.”

Language

 

Optional (string)

 

 

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

ExternalReference

 

Optional (string)

 

 

Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.

Source

 

Optional (string)

 

 

The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.

 

Maximum length 255 characters.

Affiliate

 

Object/Optional

 

AffiliateCode

String/Required

 

 

The affiliate unique code (as returned by the affiliates API methods).

 

AffiliateSource

String/Optional

 

 

The affiliate source.

CustomerReference

 

Optional (Int)

 

 

System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.

MachineId

 

Optional (string)

 

 

Unique, system generated code for each unique customer, identifying returning customers.

Items

 

Required (array of objects)

 

 

Details below. 

 

OrderItem

 

Object

 

 

 

 

Details below. 

 

 

Code

 

Required (string)

 

 

 

 

Unique product identifier your control. Max length 256 characters.

 

 

Quantity

 

Required (integer)

 

 

 

 

Number of units

 

 

PriceOptions

 

Optional (array of strings)

 

 

 

 

Array of price option codes.

 

 

SKU

 

Optional (string)

 

 

 

 

SKU identifier.

 

 

Price

 

Object - Can be NULL

 

 

 

 

OrderPrice

Object - Can be NULL

 

 

 

 

Currency

Optional (string)

 

 

 

 

 

 

 

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

 

 

 

 

NetPrice

Optional (double)

 

 

 

 

 

 

 

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

 

 

 

 

GrossPrice

Optional (double)

 

 

 

 

 

 

 

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

 

 

 

 

NetDiscountedPrice

Optional (double)

 

 

 

 

 

 

 

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

 

 

 

 

 

GrossDiscountedPrice

Optional (double)

 

 

 

 

 

 

 

Total costs shoppers incurexpressed in the payment currencyThis value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

For example:

 

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

AffiliateCommission: 94.05

 

 

 

 

 

Discount

Optional (double)

 

 

 

 

 

 

 

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

 

 

 

 

 

VAT

 

Optional (double)

 

 

 

 

 

 

 

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

 

 

 

 

 

AffiliateCommission

Optional (double)

 

 

 

 

 

 

 

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

 

 

 

 

UnitNetPrice

Optional (double)

 

 

 

 

 

 

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

 

 

 

 

UnitGrossPrice

Optional (double)

 

 

 

 

 

 

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

 

 

 

 

UnitVAT

 

Optional (double)

 

 

 

 

 

 

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

 

 

 

 

UnitDiscount

Optional (double)

 

 

 

 

 

 

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

 

 

 

 

UnitNetDiscountedPrice

Optional (double)

 

 

 

 

 

 

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

 

 

 

 

UnitGrossDiscountedPrice

Optional (double)

 

 

 

 

 

 

Total costs shoppers incur per product unitexpressed in the payment currencyThis value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

 

 

 

UnitAffiliateCommission

Optional (double)

 

 

 

 

 

 

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

 

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

 

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

 

NULL when 2Checkout does not apply an affiliate commission.

 

 

CrossSell

 

Object – Can be NULL

 

 

 

 

 

Details below. 

 

 

 

ParentCode

 

Optional (string)

 

 

 

 

 

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

 

 

 

CampaignCode

 

Optional (string)

 

 

 

 

 

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

 

 

Trial

 

Optional (Object) – Can be NULL

 

 

 

 

 

Details below. 

 

 

 

Period

 

Optional (integer)

 

 

 

 

 

The length of the trial subscription lifetime in days.

 

 

 

Price

 

Optional (double)

 

 

 

 

 

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

 

 

AdditionalFields

 

Optional (array of objects) – Can be NULL

 

 

 

AdditionalFieldSet

 

Optional (Object) – Can be NULL

 

 

 

 

Code

 

Optional (string)

 

 

 

 

 

 

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

 

 

 

 

Value

 

Optional (string)

 

 

 

 

 

 

Selected field value.

    SubscriptionStartDate   Optional (string)
       

Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.

Send empty or NULL to activate subscriptions on the same date when customers purchase them.

You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.

 

 

Promotion

 

Optional (Object)

 

 

 

 

 

Details below. 

 

 

 

Name

 

Optional (string)

 

 

 

 

 

Promotion name.

 

 

 

Description

 

Optional (string)

 

 

 

 

 

Promotion description.

 

 

 

StartDate

 

Optional (string)

 

 

 

 

 

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

 

 

 

EndDate

 

Optional (string)

 

 

 

 

 

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

 

 

 

MaximumOrdersNumber

Optional (integer)

 

 

 

 

 

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

 

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

 

 

 

MaximumQuantity

 

Optional (integer)

 

 

 

 

 

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

 

 

 

InstantDiscount

 

Optional (boolean)

 

 

 

 

 

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

 

 

 

Coupon

 

Optional (string)

 

 

 

 

 

Promotion coupon/voucher.

 

 

 

DiscountLabel

 

Optional (string)

 

 

 

 

 

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

 

 

 

Enabled

 

Optional (string)

 

 

 

 

 

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

 

 

 

Type

 

Optional (string)

 

 

 

 

 
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.

BillingDetails

 

Required (Object)

 

 

 

Details below. 

 

Person

 

Object

 

 

 

Details below. 

 

 

FirstName

Required (string)

 

 

 

Shopper name.

 

 

LastName

Required (string)

 

 

 

Shopper surname.

 

 

CountryCode

Optional (string)

 

 

 

Shopper country. ISO 3166 two-letter code.

 

 

State

Optional (string) – Required for US, Brazil, India and Romania

The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

 

 

 

 

 

City

Optional (string)

 

 

 

Shopper city.

 

 

Address1

Optional (string)

 

 

 

Shopper address.

 

 

Address2

Optional (string)

 

 

 

Shopper address.

 

 

Zip

Optional (string)

 

 

 

ZIP/ Postal code.

 

 

Email

Optional (string)

 

 

 

Shopper email address.

 

 

Phone

Optional (string)

 

 

 

Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.

 

 

Company

Optional (string)

 

 

 

Company name. Can be null for end users. When present, you also need to provide the FiscalCode.

    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. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when you set India as Billing Country, and purchase is made by a Company.

• Can be NULL for end users.

DeliveryDetails

Required (Object)

 

 

Details below. 

 

Person

Object

 

 

 

Details below. 

 

 

FirstName

Required (string)

 

 

 

Shopper name from the delivery details.

 

 

LastName

Required (string)

 

 

 

Shopper surname from the delivery details.

 

 

CountryCode

Optional (string)

 

 

 

Shopper country. ISO 3166 two-letter code from the delivery details.

 

 

State

Optional (string) – Required for US, Brazil and Romania

 

 

 

The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

 

 

City

Optional (string)

 

 

 

Shopper city from the delivery details.

 

 

Address1

Optional (string)

 

 

 

Shopper address from the delivery details.

 

 

Address2

Optional (string)

 

 

 

Shopper address from the delivery details.

 

 

Zip

Optional (string)

 

 

 

ZIP/ Postal code from the delivery details.

 

 

Email

Optional (string)

 

 

 

Shopper email address from the delivery details.

 

 

Phone

Optional (string)

 

 

 

Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.

 

 

Company

Optional (string)

 

 

 

Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.

PaymentDetails

 

Required (Object)

 

 

Adapt this object to the desired payment method.

 

Type

 

Required (string)

 

 

 

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • ENCRYPTED_PAYMENT_DATA (client-side encryption)
  • PAYPAL
  • PAYPAL_EXPRESS
  • CCNOPCI(credit/debit card for non-PCI certified merchants).
  • TEST (for test orders).
  • PREVIOUS_ORDER(place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.

 

 

Currency

 

Optional (string)

 

 

 

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

 

PaymentMethod

 

Optional (object)

 

 

 

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)).

 

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

                                                         RecurringEnabled   Optional (boolean)
     

true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.

false – shopper doesn’t check the auto-renewal checkbox.

 

 

 

CardPayment

 

Optional (object)

 

 

 

 

 

 

Details below. 

 

 

 

 

CardNumber

 

Optional (string)

 

 

 

 

 

 

The credit/debit card number.

 

 

 

 

CardType

 

Optional (string)

 

 

 

 

 

 

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

 

 

 

 

ExpirationYear

 

Optional (string)

 

 

 

 

 

 

The year in which the card expires.

 

 

 

 

ExpirationMonth

 

Optional (string)

 

 

 

 

 

 

The month in which the card expires.

 

 

 

 

HolderName

 

Optional (string)

 

 

 

 

 

 

Card holder name.

 

 

 

 

CCID

 

Optional (string)

 

 

 

 

 

 

Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.

        HolderNameTime Optional (float)
           

The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.

        CardNumberTime Optional (float)
           

The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.

 

 

 

 

InstallmentsNumber 

Optional (Int)

 

 

 

 

 

 

Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments. 

 

 

 

PayPalExpress

 

Optional (object)

 

 

 

 

 

 

Details below. 

 

 

 

 

Email

 

Optional (string)

 

 

 

 

 

 

Email address customers use for their PayPal account.

 

 

 

 

ReturnURL

 

Optional (string)

 

 

 

 

 

 

The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.

 

 

 

 

CancelURL

 

Optional (string)

 

 

 

 

 

 

The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.

 

 

 

PreviousOrder

 

Optional (Object)

 

 

 

 

 

 

Details below. 

 

 

 

 

RefNo

 

Optional (string)

 

 

 

 

 

 

Order reference a previous purchase which reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of order should be AUTHRECEIVED or COMPLETE.

 

Check the validity of references with the isValidOrderReference method.

 

The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.

 

 

 

PurchaseOrderPaymentDetails

 

Optional (Object)

 

 

 

 

 

 

Details below. 

 

 

 

 

InternalPONumber

Optional (string)

 

 

 

 

 

 

Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.

 

 

 

 

AutoApprove

 

Optional (boolean)

 

 

 

 

 

 

TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders.

FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders.

 

Can be NULL.

      WE_CHAT_PAY   Optional (string)
          Details below
        ReturnURL   Optional (string)
            The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL   Optional (string)
            The cancel URL is the page to which your customers are redirected after their failed payment attempt.
      IDEAL   Optional (string)
          Details below
        ReturnURL   Optional (string)
            The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL   Optional (string)
            The cancel URL is the page to which your customers are redirected after their failed payment attempt.
        BankCode   Required (string)
            String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".

 

 

 

EXISTING_PAYMENT_DATA

 

Optional (Object)

 

 

 

 

 

By using EXISTING_PAYMENT_DATA you no longer require shoppers to enter any payment details.

 

 

 

 

TransientToken

 

Optional (string)

 

 

 

 

 

 

Returned as a part of the process of retrieving customer information by SSOToken.

 

CustomerIP

 

Required (string)

 

 

 

Shopper IP.

Promotions

 

Optional (Array of strings)

 

 

Array of promotion codes.

AdditionalFields

 

 

 

 

 

Details below. 

 

Code

 

Optional (string)

 

 

 

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

 

Text

 

Optional (string)

 

 

 

Field text visible to shoppers in the cart.

 

Value

 

Optional (string)

 

 

 

Selected field value.

LocalTime

 

Optional (string)

 

 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.

GiftDetails

 

Optional (object)

 

 

Contains contact details for the recipient of a gift purchase.

 

FirstName

 

Optional (string)

 

 

 

First name of gift recipient.

 

LastName

 

Optional (string)

 

 

 

Last name of gift recipient.

 

Email

 

Optional (string)

 

 

 

Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.

 

GiftNote

 

Optional (string)

 

 

 

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

Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo