Integrate Checkout

Use the Checkout Browser SDK to integrate Checkout with web applications.

Copy for LLM

View as Markdown

Prerequisites

The prerequisites to integrate Checkout by using the Checkout Browser SDK are as follows:

A Composable Commerce Project
An API Client with at least the manage_orders:{projectKey} or manage_orders:{projectKey}:{storeKey} scope
An API Client with at least the manage_sessions scope
At least one Connector and one Application configured

To create the API Clients, you can use the Admin client template in the Merchant Center.

You can create a single API Client with all the required scopes. However, we recommend creating two for security reasons.

Create Carts

Checkout can only be initialized for Carts created with the Carts API. You must provide the id of the Cart in the request to create a Checkout Session, which is required to initialize Checkout.

Multiple Shipping Methods BETA

Checkout's Payment Only mode supports multiple Shipping Methods. For example, you can leverage multiple Shipping Methods to offer your customers the possibility to collect some items in person and have the rest sent by express delivery.

To provide multiple Shipping Methods, you must set shippingMode to Multiple in the CartDraft. For further information, see Multiple Shipping Methods.

Create Checkout Sessions

Checkout Sessions hold the permissions and information to initialize Checkout. To create a Checkout Session, you must include the corresponding code in your backend as follows to send a request to the Sessions API.

Checkout Sessions are specific to Checkout. They are different from payment sessions created with payment service providers (PSPs) to process payments.

To send requests to the Session API, you must use an access token with at least the manage_sessions scope. In the request, you must provide the identifier of the Cart and of the Application.

The id returned in the response must be used as the value of the sessionId property in the checkoutFlow and paymentFlow methods.

Request to the Session API to create a Checkout SessionHTTP

POST https://session.{region}.commercetools.com/{projectKey}/sessions
Authorization: Bearer <Token manage_sessions:{projectKey}>

{
    "cart": {
        "cartRef": {
            "id": "{cartId}"
        }
    },
    "metadata": {
        "applicationKey": "{applicationKey}"
    }
}

Example response from the Session APIjson

{
  "id": "537ec3b7-01f5-47b6-8a5c-3974a8bc4812",
  "expiryAt": "2024-03-13T10:20:45.661Z",
  "lastModifiedAt": "2024-03-13T09:20:45.661Z",
  "createdAt": "2024-03-13T09:20:45.661Z",
  "metadata": {
    "applicationKey": "{applicationKey}"
  },
  "activeCart": {
    "cartRef": {
      "id": "{cartId}"
    }
  },
  "state": "ACTIVE"
}

Set a custom Order number BETA

You can set a custom Order number in your Checkout Session to let you track and manage your Orders across all your platforms, payment service providers, and customer communications.

To set an Order number, send a unique number in the optional futureOrderNumber field. This number is then stored as the orderNumber in the Composable Commerce Order entity.

Order numbers must be unique. If you send a duplicate Order number, an error occurs and the Order is not created.

Request to set the futureOrderNumber when creating a Checkout SessionHTTP

POST https://session.{region}.commercetools.com/{projectKey}/sessions
Authorization: Bearer <Token manage_sessions:{projectKey}>

{
  "cart": {
    "cartRef": {
      "id": "{cartId}"
    }
  },
  "metadata": {
    "applicationKey": "{applicationKey}",
    "futureOrderNumber": "{yourUniqueOrderNumber}"
  }
}

Locales

When initializing Checkout with the checkoutFlow and paymentFlow methods, setting the locale translates the checkout process into the preferred language and updates the decimal separator for prices.

Checkout supports locale formats such as xx, xx-xx, or xx-XX. If the payment service provider requires a specific locale format, initialize Checkout with that format to ensure proper price formatting and translations.

If an unsupported locale is set, the checkout process automatically reverts to the default locale of en.

Locale code	Language	Price formatting
`en` (fallback locale)	English	€10,000.00
`bg-BG`	Bulgarian - Bulgaria	10 000,00 лв
`cs-CZ`	Czech - Czechia	10 000,00 Kč
`da-DK`	Danish - Denmark	10.000,00 kr
`de`	German	10.000,00 €
`el-GR`	Greek - Greece	10.000,00 €
`en-US`	English - United States	$10,000.00
`es`	Spanish	10.000,00 €
`et-EE`	Estonian - Estonia	10 000,00 €
`fi-FI`	Finnish - Finland	10 000,00 €
`fr`	French	10.000,00 €
`hr-HR`	Croatian - Croatia	10.000,00 €
`hu`	Hungarian	10 000,00 Ft
`it`	Italian	10.000,00 €
`lt-LT`	Lithuanian - Lithuania	10 000,00 €
`lv-LV`	Latvian - Latvia	10 000,00 €
`nb-NO`	Norwegian - Norway	10.000,00 kr
`nl-NL`	Dutch - Netherlands	10.000,00 €
`pl-PL`	Polish - Poland	10 000,00 zł
`pt-PT`	Portuguese - Portugal	10 000,00 €
`ro-RO`	Romanian - Romania	10.000,00 lei
`sk-SK`	Slovak - Slovakia	10.000,00 €
`sl-SI`	Slovenian - Slovenia	10.000,00 €
`sr-RS`	Serbian - Serbia	10.000 RSD
`sv-SE`	Swedish - Sweden	10.000,00 kr

Integrate Checkout

Prerequisites.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create Carts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Multiple Shipping Methods BETA.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create Checkout Sessions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set a custom Order number BETA.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}