Skip to main content

Build the order object to place orders

Build the order object to place orders

Last updated: 06-Oct-2020
Rate this article:

Overview

An order is the most common way to collect payment from your shoppers and is at the heart of the 2Checkout platform.

The Order Object

While the full order object can be very extensive (the full object structure can be found here), the minimum information needed for placing an order are the billing details, the payment details, and the order items.

The Billing Details

The billing details are mandatory information when placing an order, and they are used in the processing of an order, as they appear on the invoice of the order. 

Field name Type Required/Optional Description

FirstName

String

Mandatory

Shopper' name or their first name

LastName

String

Mandatory

Shopper' surname or their last name

CountryCode

String

Mandatory

Shopper's country, ISO 3166 two-letter code formatted.

State

String

Mandatory

The state in the shopper's country. Mandatory when the billing country is the USA, Turkey, India, or Romania. Use case insensitive UTF8 strings for the full name, or just the two-letter code.

City

String

Mandatory

Shopper's city.

Address1

String

Mandatory

Shopper's address.

Address2

String

Optional

Shopper's address, when additional information is needed.

Zip

String

Mandatory

Shopper's address zip/postal code.

Email

String

Mandatory

Shopper's email address.

Phone

String

Optional

Shopper's phone number.

Company

String

Optional

Company name, can be null for end users. When provided, FiscalCode needs to be also present.

Fiscal Code

String

Optional

Can be NULL for end-users; 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.

Exceptions:

  • 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 the purchase is made by a company.

The payment details

The payment details are used in processing the order and contain information specific for the payment method used. For example, for a Credit Card payment, this is where you would be sending the Card Holder Name, Card Number, Card Type, Expiration Date, and CVV.

Due to the wide range of payment methods supported in the 2Checkout API, the payment details object can differ extensively between payment methods. 

The various payment details objects will be explained and detailed in the Payments flow article. 

The items  

The items object required when placing an order is an array of item objects. The items are the products that the shopper is buying when placing the order. 

The 2Checkout API supports either catalog or dynamic products. Mixed orders, with both catalog and dynamic products is not supported.

For each product in the item list, the quantity is optional and can be left out. In this case, the quantity will be set to 1 by default.  

Catalog products

Catalog products are products that you have defined in your product catalog, either via your Merchant Control Panel or via API. 

The minimum information needed in order to place an order with catalog products, via API, is the alphanumeric product code (not to be confused with the product id). 

The JSON for this would look like:

"Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ]

The full list of fields available for catalog products can be found here.

The full JSON for an order with catalog products would look like:

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"TEST",
      "Currency":"USD",
      "PaymentMethod":{
         "CardNumber":"4111111111111111",
         "CardType":"VISA",
         "ExpirationYear":"2023",
         "ExpirationMonth":"12",
         "HolderName":"Red Doe",
         "CCID":"123",
         "Vendor3DSReturnURL":"http:\/\/yoursuccessurl.com",
         "Vendor3DSCancelURL":"http:\/\/yourcancelurl.com"
      },
      "CustomerIP":"10.10.10.10"
   }
}

Dynamic products

Dynamic products are products generated on the fly when placing orders.

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. 

The minimum information needed in order to place an order with dynamic products, via API is:

Field name Type Required/Optional Description

Code

String

Mandatory

Always NULL for dynamic products.

IsDynamic

Boolean

Mandatory

Boolean flag that signals a dynamic product.

PurchaseType

String

Mandatory

The type of product that is being used, possible values:

  • PRODUCT

  • SHIPPING

  • TAX

  • COUPON

Tangible

Boolean

Mandatory

Defines the product delivery type - either a digital product (tangible is false) or a physical product (tangible is true).

Name

String

Mandatory

The name of the product will be used in the 2Checkout systems (order reports, invoices if generated).

Price Amount

Float

Mandatory

The price of the product. The price amount and type must be grouped under a price object.

Price Type

String

Mandatory

Must be set to “CUSTOM”; Price amount and type must be grouped under a price object.

The items in the JSON body of the request would look like:

 "Items":[
      {
         "Code":null,
         "IsDynamic":true,
         "PurchaseType":"PRODUCT",
         "Tangible":false,
         "Name":"My Dynamic Product",
         "Quantity":1,
         "Price":{
            "Amount":1,
            "Type":"CUSTOM"
         }
      }
   ]

The full list of fields available for dynamic products can be found here.

The full JSON for an order with catalog products would look like:

{
   "Items":[
      {
         "Code":null,
         "IsDynamic":true,
         "PurchaseType":"PRODUCT",
         "Tangible":false,
         "Name":"My Dynamic Product",
         "Quantity":1,
         "Price":{
            "Amount":1,
            "Type":"CUSTOM"
         }
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"TEST",
      "Currency":"USD",
      "CustomerIP":"10.10.10.10",
      "PaymentMethod":{
         "CardNumber":"4111111111111111",
         "CardType":"VISA",
         "ExpirationYear":"2020",
         "ExpirationMonth":"12",
         "CCID":"123",
         "HolderName":"John Doe",
         "Vendor3DSReturnURL":"https:\/\/example.com",
         "Vendor3DSCancelURL":"https:\/\/example.com"
      }
   }
}

Extending the order object

There's a wide range of use cases that can be supported by the order object, such as, but not limited to, adding customer information on an order, affiliate information, promotions, or additional fields.

In order to add this information, a new object with the corresponding name must be added at the root level of the order object, with the appropriate structure. 

For example, in order to add delivery details that were collected from the shopper, a new object named “DeliveryDetails” needs to be added in the order object (on the same level as the "Billing Details"). 

The Delivery Details object has the same structure as the Billing Details object. 

Let’s assume we also want to add some additional information to the order. This could be done by adding a new Additional Fields array of Additional Field objects. 

The additional field object contains three fields:

  • a code (the internal code in the merchant's systems)
  • a text (that could be displayed to the shoppers)
  • a value (the actual value of the additional field for that order)

Adding delivery details and additional fields to an order would look like this:

 "DeliveryDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "Address1":"Example Street 42",
      "Address2":"2nd line of the address",
      "City":"San Francisco",
      "State":"California",
      "CountryCode":"US",
      "Phone":"555-5555",
      "Email":"example@email.com",
      "Zip":"90210"
   },
   "AdditionalFields":[
      {
         "Code":"ABC1234",
         "Text":"Additional field text",
         "Value":"Additional field value"
      }
   ]

Integration use cases

There are several test credit cards (available here) that can be used to test your integration as described in these steps:

  1. Create a test product in the Merchant Control Panel.
  2. Using the product code of the newly created product, place an order based on the request example above, and check that an order is placed.
  3. Starting from the minimum requirements for a catalog product order, extend the information you send to 2Checkout and check on every new parameter that the order is placed successfully.
  4. If you need to create products on the fly via dynamic products, first of all, make sure your account supports dynamic products (available only for 2Sell and 2Subscribe accounts, if you handle your own tax and invoice management.).
  5. Starting from the minimum requirements for a dynamic product order, start adding all the information you need to send to 2Checkout while checking that the order is successfully placed.
  6. Check that making a placeOrder API call returns an order object.
  7. Once an order object is obtained via API, check the order in the Merchant Control Panel. Under Orders & customers → Order search, you can filter by the order reference of the newly created order (the RefNo property).

 

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