Integrate Checkout

Prerequisites

Following are the prerequisites to integrate Checkout using the Checkout Browser SDK:

• 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 payment Connector and one Application configured

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.

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.

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.

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

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

{
  "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.

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.