Overview

The checkout process begins with an order, which manages all aspects of the transaction. This includes cart items, discounts, delivery options, payment methods, and customer details. It also handles callbacks for validations, hooks, and notifications, while tracking the order's status. Every order initially starts in the checkout state.

Order Context

The order contains key context information that cannot be modified during checkout. This data is crucial for most adapters and their integrations and remains static throughout the flow.

• Culture : Defines the locale and language for the checkout.
• Currency : Specifies the currency used for the transaction.
• Country : Indicates the country associated with the order.

Cart

The cart keeps track of items and discounts.

Read more about carts here.

Customer details

The customer model includes two addresses: billing and shipping. We're considering adding orderer as a third. Each address has a different owner. The billing address is primarily for the payment provider and is often provided by them. The shipping address is used by the delivery provider and may come from the checkout, payment provider, or the shipping provider. Currently, platform adapters assume that the billing address also represents the individual making the order.

Order States

A new order starts in the Checkout state, where it is editable. When a payment is initiated, the order transitions to Processing. If the payment is accepted, the order advances to the Accepted state; if it is declined, the order returns to Checkout. After all conditions are met, the order finally reaches the Completed state. However, if there's a failure after acceptance, it will transition to Declined.

Read more about order states here.

Shippings

Keeps track of delivery details and the cost of shipping. It has an adapterId that tells us which adapter has created and manages this shipping.

Order total

The order always calculates the sum of the cart total and all active shipping costs. We cannot transition the order to the processing state unless the total of all active payments matches this overall total.

Payments

Payments on the order contain an optional adapterId to inform us if this payment was created and is being managed by an adapter, very useful for cases where we have multiple payment adapters creating payments on the order. amount informs us how much of the order this payment is covering.

Example order with payments

In this simplified order, the cart total is 200 and the shipping total is 100, resulting in an order total of 300. A voucher with an upperLimitAmount of 100 is applied, covering that amount. The remaining 200 is covered by a regular payment.

{
  "cart": {
    "total": {
      "includingVat": 200,
      "excludingVat": 160
    }
  },
  "shippings": [
    {
      "total": {
        "includingVat": 100,
        "excludingVat": 80
      }
    }
  ],
  "payments": [
    {
      "name": "Regular Payment",
      "type": "default",
      "merchant": "norce",
      "amount": 200
    },
    {
      "name": "Voucher",
      "type": "voucher",
      "amount": 100,
      "upperLimitAmount": 100
    }
  ],
  "total": {
    "includingVat": 300,
    "excludingVat": 240
  }
}

Callbacks

Callbacks are used to interact with adapters without tightly coupling them. There are three different types of callbacks registered on the order:

• Validations
• Hooks
• Notifications

Read more about validations, hooks and notifications here.