# Checkout integration

**Route shoppers from the Commerce Integration Layer to a commercetools Checkout Application in either Checkout mode.**

## Checkout integration workflow

The Commerce Integration Layer acts as the backend-for-frontend (BFF) for [Checkout](/checkout/overview.md). Your storefront starts the checkout flow through the Experience API, which creates a Checkout Session for your Project. Your storefront passes that Checkout Session to the [Checkout Browser SDK](/checkout/browser-sdk.md), which renders the Checkout UI and creates the Order. Checkout creates the Order and processes the payment, not the Commerce Integration Layer.

The integration uses the same Checkout SDK contract as any other Checkout integration, so Connectors, Payment Integrations, and customization behave as described in the [Checkout documentation](/checkout/overview.md). The Commerce Integration Layer only adds routing: for each shopper, it decides which Checkout Application and mode to use.

Both Checkout modes are supported:

- [Complete Checkout mode](/checkout/overview.md#complete-checkout-mode): Checkout renders addresses, shipping method, payment, and order confirmation.
- [Payment Only mode](/checkout/overview.md#payment-only-mode): Checkout renders the payment step only. You keep your own flow for the rest.

### B2B Orders

For B2B checkout, place the Order with the [`placeOrder`](/commerce-integration-layer/experience/order.md#place-order) mutation instead of starting a Checkout flow. `placeOrder` places the Order as the Associate in the selected Business Unit, so the permissions of the Associate and the Approval Rules of the Business Unit apply to the Order. It doesn't collect a payment. To collect one, use an [extension](/commerce-integration-layer/overview.md#extensions).

## Provision Checkout

Provision Checkout as you would for any other integration: install at least one Connector, then create a Checkout Application for each checkout experience. See the [Getting started workflow](/checkout/overview.md#getting-started-workflow) in the Checkout documentation.

## Configure Checkout routing

Configure Checkout routing in the Commerce Integration Layer application in the Merchant Center. Routing is an ordered list of rules. Each rule matches a Store, a country, or both, and names the Checkout Application to use. An empty cell matches any value. The Commerce Integration Layer evaluates the rules in order and selects the first matching rule.

| Store | Country | Checkout Application |
| --- | --- | --- |
| `retail-de` |  | `checkout-de` |
|  | `US` | `checkout-us` |
|  |  | `checkout-default` |

With these rules, shoppers in the `retail-de` Store go to `checkout-de` regardless of country. Shoppers outside the `retail-de` Store who browse from the US go to `checkout-us`. All other shoppers go to `checkout-default`.

Rules match against the country and Store on the shopper's [session](/commerce-integration-layer/hosts-and-authorization.md#session-tokens).

> If no rule matches, starting a Checkout flow fails. Add a catch-all rule so every shopper can reach Checkout.

## Start a Checkout flow

Call the `beginPayment` mutation to start a flow for the shopper's active Cart. It resolves the [Checkout routing](/commerce-integration-layer/development/checkout-integration.md#configure-checkout-routing) for the current session and creates a Checkout Session.

These diagrams show where `beginPayment` fits into the [Checkout integration flows](/checkout/overview.md#integration-flows), with the Commerce Integration Layer as the BFF.

**Complete Checkout flow:**

```mermaid title="Complete Checkout flow"
sequenceDiagram
  participant Browser
  participant Commerce Integration Layer
  participant Session API
  participant Checkout API

  Browser->>Commerce Integration Layer: beginPayment mutation
  Commerce Integration Layer->>Session API: Create Checkout Session
  Session API-->>Commerce Integration Layer: Return [sessionId]
  Commerce Integration Layer-->>Browser: Return [paymentTicket]
  Browser->>Checkout API: Initialize checkoutFlow using Checkout Browser SDK with [paymentTicket]
  Checkout API-->>Browser: Return Checkout configuration and Cart
  Browser->>Browser: Checkout

```

**Payment Only flow:**

```mermaid
sequenceDiagram
  participant Browser
  participant Commerce Integration Layer
  participant Session API
  participant Checkout API

  Browser->>Browser: Customer advances to payment details
  Browser->>Commerce Integration Layer: beginPayment mutation
  Commerce Integration Layer->>Session API: Create Checkout Session
  Session API-->>Commerce Integration Layer: Return [sessionId]
  Commerce Integration Layer-->>Browser: Return [paymentTicket]
  Browser->>Checkout API: Initialize paymentFlow using Checkout Browser SDK with [paymentTicket]
  Checkout API-->>Browser: Payment configuration returned
  Browser->>Browser: SDK displays payment options UI

```

`beginPayment` returns the following fields:

| Field | Description |
| --- | --- |
| `paymentTicket` | The Checkout Session ID. Pass it as the `sessionId` argument to [`checkoutFlow`](/checkout/browser-sdk.md#checkoutflow-method) or [`paymentFlow`](/checkout/browser-sdk.md#paymentflow-method) in the Checkout Browser SDK. |
| `projectKey` | Your Project key. Pass it to the Browser SDK. |
| `region` | The Region in which the Checkout Application is hosted. Pass it to the Browser SDK. |
| `mode` | `COMPLETE` or `PAYMENT_ONLY`. Determines whether to call `checkoutFlow` or `paymentFlow`. |

To know which method to prepare for before starting the flow, query `{ viewer { checkoutMode } }`.

> The Checkout Session isn't the shopper session that authorizes requests to the Commerce Integration Layer. Keep the [session token](/commerce-integration-layer/hosts-and-authorization.md#session-tokens) and the `paymentTicket` separate: the session token authorizes the Commerce Integration Layer, and the `paymentTicket` authorizes Checkout.

## Payment actions after checkout

`beginPayment` starts a checkout or payment flow. Later actions on an authorized Payment, such as a refund, capture, cancellation, or reversal, aren't modeled in the Commerce Integration Layer schema. Use the Checkout [Payment Intents API](/checkout/payment-intents-api.md) from a [schema extension](/commerce-integration-layer/development/writing-schema-extensions.md).

## Further reading

- [Checkout overview](/checkout/overview.md): Learn about Checkout, Connectors, and Applications.
- [Checkout Browser SDK](/checkout/browser-sdk.md): Embed the Checkout UI in your storefront.

## Related pages

- [Area overview page with navigation](/commerce-integration-layer.md)
- [Next page: Identity providers](/commerce-integration-layer/development/identity-providers.md)
- [Search documentation and API specs](/search.md)