Introduction to commercetools Checkout

Checkout features

Checkout simplifies the complexity of payment integration and implementation of the checkout flow:

• PSP integration through Connect: use prebuilt Connectors for Stripe, Adyen, PayPal, and other payment providers without writing integration code.
• Hosted UI: render checkout forms in your application by using the Browser SDK, with full customization of styles and labels.
• Cart and Order management: Checkout reads Cart data from Composable Commerce and creates Orders upon successful payment.
• PCI DSS compliance: Checkout and PSPs manage sensitive payment data in a secure manner, reducing your compliance scope.
• Multi-region support: Checkout Applications are hosted in the same region as your commercetools project (Europe, America, Australia).
• Localization: built-in support for multiple currencies and languages.
• Event messaging: subscribe to Checkout events for tracking and analytics.

Checkout reduces the time that's required to implement payment processing by providing the infrastructure, PSP integrations, and UI components needed for a complete checkout flow.

Checkout modes: Complete Checkout and Payment Only

commercetools Checkout operates in two modes: Complete Checkout and Payment Only. The mode you choose determines which parts of the checkout flow Checkout manages.

Complete Checkout mode

• Shipping and billing address forms
• Selection of the shipping method
• Selection of the payment method and entry of payment data
• Acceptance of terms and conditions
• Order summary
• Checkout success and failure pages

Payment Only mode

Your application manages address collection, shipping method selection, and Cart updates. Checkout renders only the payment method selector and captures payment data through PSP-provided secure forms. The Cart must have shipping and billing information before initializing the payment flow.

Checkout architecture

Checkout contains several components that work together to process payments and manage the checkout flow.

Checkout Application (Backend Service)

This is the commercetools-hosted service that runs the checkout logic. The Checkout Application orchestrates everything during a customer's checkout; it reads or updates Cart and Order data in Composable Commerce, communicates with payment providers, and enforces the configurations you set.

• Complete Checkout: corresponds to the complete checkout mode. In addition to the general settings, you can activate the discount code functionality on your checkout, add user agreements, and add Payment Integrations.
• Payment Only: corresponds to the payment-only mode. You can configure only the general settings and add Payment Integrations.

You can create and configure Checkout Applications through the Merchant Center, and then integrate with them by using the Checkout APIs/SDK from your code.

Connectors

commercetools provides a marketplace of Public Connectors, such as Adyen, PayPal, Stripe, that you can install and use. You can also use custom (Organization) Connectors if you need your own integration; for example, to a PSP that isn't provided.

Merchant Center Configuration

In the Merchant Center, you can manage Checkout settings, such as connecting payment providers (through Connectors) and creating Applications. An Application in this context represents a specific checkout configuration; think of it as an instance of Checkout configured for a certain context or purpose; for example, an Application for a specific brand or country.

You can create multiple Applications under one project, even combining full checkout and payment-only Applications as needed.

Browser SDK (frontend integration)

Depending on the SDK method you call, you can launch the UI and flow for either the Complete Checkout or Payment Only mode.

Component relationships

The following diagram shows how Checkout components interact with each other and with your Application:

Checkout Sessions

Checkout Sessions authorize and configure individual checkout instances. You can create Sessions from your Backend for Frontend (BFF) by calling the Composable Commerce Sessions API.

A Session request requires the following:

• An API Client access token with the manage_sessions scope
• The Cart id or key
• The Checkout Application id or key

import fetch from "node-fetch";

async function createCheckoutSession(
  region: string,
  projectKey: string,
  token: string,
  cartId: string,
  applicationKey: string
) {
  const url = `https://session.${region}.commercetools.com/${projectKey}/sessions`;

  const body = {
    cart: {
      cartRef: {
        id: cartId,
      },
    },
    metadata: {
      applicationKey: applicationKey,
    },
  };

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`Session creation failed: ${response.status}`);
  }

  const data = await response.json();
  return data.id; // This is the sessionId
}

Checkout workflows

The following sections describe the typical integration flows for Complete Checkout and Payment Only modes.

Complete Checkout workflow

The following diagram shows the Complete Checkout initialization flow:

This sequence performs the following actions:

1. Initializes the Checkout Session
2. Associates a Customer Cart to it
3. Specifies which Application to use for the checkout. This step, in turn, specifies the customization and localization settings that are to be used during checkout.
4. Renders the Checkout UI directly in the browser. By default, the Checkout UI is rendered in full screen in an absolute positioned <div> element or inline to a specified <div> or <span> element.

The Checkout UI guides the Customer to provide their shipping and billing addresses, apply discount codes, select the delivery method, and provide their payment information.

Payment Only workflow

Before initializing the Payment Only mode, make sure that the following conditions are met for the Cart:

• It exists in Composable Commerce and is ready for checkout
• It contains specific shipping information
• It contains specific billing information

Payment Only mode provides control over when and where the payment UI renders. Your application manages all checkout steps, except for payment capture.

The following diagram shows the Payment Only initialization flow:

This sequence performs the following actions:

1. Initializes the Checkout Session
2. Associates the Customer Cart to it
3. Specifies which Application to use for the checkout, it must be of type Payment Only
4. Renders the hosted payment UI directly in the browser (under a <div> or <span> element of your choice)

Key takeaways

• commercetools Checkout is a service that manages payment processing and checkout flows for Composable Commerce applications.
• Checkout operates in two modes: Complete Checkout (full checkout UI and flow) and Payment Only (payment processing only).
• Checkout Applications are configured in the Merchant Center and define the checkout behavior, localization, and payment methods.
• Connectors integrate Checkout with Payment Service Providers like Stripe, Adyen, and PayPal without requiring custom integration code.
• Checkout Sessions authorize individual checkout instances and are created from your BFF by using the Sessions API.
• The Browser SDK embeds the Checkout UI in your application and handles communication with the Checkout service.
• Complete Checkout mode requires only a Cart to exist before initialization, while Payment Only mode requires the Cart to have shipping and billing information.
• Checkout manages PCI DSS compliance for payment data, reducing your security and compliance responsibilities.

Test your knowledge