Learning PathModule

Set up Checkout

Learn how to configure commercetools Checkout in the Merchant Center before integrating the SDK.

Ask about this Page

Copy for LLM

View as Markdown

After completing this page, you should be able to:

Configure Checkout permissions and subscriptions to enable API access.
Create API Clients with the required scopes for Checkout integration.
Install and configure Payment Connectors from the Connect Marketplace.
Create and configure Checkout Applications for various business use cases.
Understand Payment Integration Types and configure Payment methods.

Before integrating the Checkout SDK, you must complete a one-time configuration in the Merchant Center. This setup establishes the infrastructure Checkout needs to process Payments and create Orders: permissions to access your Project data, API credentials for your application, Payment provider connections, and Checkout Application instances.

Setup overview

The setup process consists of the following four phases:

Grant permissions: allow Checkout to create an API Client and subscribe to Cart/Order events.
Create API credentials: generate an API Client for your application code and Connectors to authenticate with Checkout.
Install Payment Connectors: add integrations with Payment Service Providers (PSPs) from the Connect Marketplace.
Create Checkout Applications: configure one or more applications that define checkout behavior, Payment methods, and localization.

You can complete phases 1 to 3 once per Project. Phase 4 can be repeated to create multiple applications for different business contexts like separating applications according to a specific brand, country, or sales Channel.

Grant permissions and subscriptions

Checkout requires the following two authorizations to function:

API Client permissions: Checkout creates an internal API Client with specific scopes (such as manage_payments, manage_orders, and view_sessions) to read and update Cart, Order, and Payment resources in your Project.
Subscription: Checkout subscribes to Cart and Order messages to track Payment State changes and synchronize data with your PSP.

The API Client permissions and Subscription are pre-defined by commercetools. You only need to confirm their creation once per Project.

First-time setup

For the first time you configure Checkout, or if the permissions and/or the Subscription created in the past has been deleted, you must confirm the creation of permissions and a Subscription for Checkout:

Set up for first time

In the Merchant Center, go to Checkout > Overview.
Click Get started.
Click Let's proceed to handle the required confirmation.
Review the required scopes and Subscription settings.
Click Confirm creation.

Checkout creates two demo applications by default: Checkout DE and Checkout EN. These are Complete Checkout Applications that you can use for testing.

If permissions or subscription were previously deleted

In the Merchant Center, go to Checkout > Overview.
Select the Permissions and subscription tab.
Click Recreate permission or Apply subscription changes as needed.

Checkout's internal API Client appears in Settings > Developer Settings > API Clients as commercetools Checkout - API client (autogenerated). This API Client is managed by Checkout; do not modify or delete the API Client.

Create an API Client for your Connectors

Your payment and gift card Connectors need an API Client to authenticate with Checkout and Composable Commerce APIs. This client requires specific scopes to create sessions, manage payments, and process orders.

Required scopes

Your API Client needs specific Checkout scopes, including manage_payments, view_sessions, manage_orders, and manage_checkout_payment_intents.

For the complete list of required and optional scopes, see Scopes.

Create the client

Go to Settings > Developer settings > API clients.
Click Create API client.
Enter a name, such as "Checkout Integration Client".
Select the required scopes mentioned earlier.
Click Create API client.
Copy and securely store the client_id, client_secret, and project_key; these credentials are shown only once.

You need to use these credentials to configure Payment Connectors in the next step.

Install Payment Connectors

Payment Connectors integrate Checkout with payment service providers (PSPs). Connectors manage the communication between Checkout and PSPs like Adyen, Stripe, and PayPal, eliminating the need to write custom integration code.

For testing, install the Sample Payment Connector, a sandbox PSP that processes test payments without requiring a real PSP account. For production, install Connectors for your actual Payment providers.

Installation steps

Go to My Profile > Organizations & teams.
Select your Organization.
Select the Connect tab.
Search for Sample payment connector for checkout.
Click Install, and then complete the steps in the installation wizard.

Configure the Connector

During installation, configure the Connector with your Project details and the API Client credentials that you created earlier:

Field	Description	Example value
`CTP_API_URL`	Composable Commerce API endpoint for your region.	`https://api.europe-west1.gcp.commercetools.com`
`CTP_AUTH_URL`	OAuth 2.0 authentication endpoint.	`https://auth.europe-west1.gcp.commercetools.com`
`CTP_CLIENT_ID`	Client ID from your API Client.	`xvHDj6aZ...`
`CTP_CLIENT_SECRET`	Client secret from your API Client.	`ya_bWf_example-Secret...`
`CTP_PROJECT_KEY`	Your Project key.	`my-project-key`
`CTP_SESSION_URL`	Session API endpoint.	`https://session.europe-west1.gcp.commercetools.com`
`CTP_JWKS_URL`	JWKS endpoint for JWT validation.	`https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json`
`CTP_JWT_ISSUER`	JWT issuer URL.	`https://mc-api.europe-west1.gcp.commercetools.com`

Replace europe-west1.gcp with your specific region, such as us-central1.gcp, us-east-2.aws, eu-central-1.aws, or australia-southeast1.gcp.

After completing the configuration process, finish the installation. The Connector becomes available for use in Checkout Applications.

Create Checkout Applications

With Connectors installed, you can create Checkout Applications. Each application represents a distinct checkout configuration—you might create separate applications for different brands, countries, or business units, each with its own payment methods, localization, and settings.

You can create two application types:

Complete Checkout: manages the entire checkout flow including address collection, Shipping Method selection, and Payment processing.
Payment Only: manages only Payment processing—use this when you manage the checkout UI yourself.

When creating an application, you can configure the following items:

General settings (name, key, countries, URLs, logo)
User agreements (terms and conditions, privacy policy)
Payment Integrations (Payment methods and providers)

General settings

Field	Description
Application name	Display name for the application in the Merchant Center.
Application key	Unique identifier (2-256 alphanumeric characters, `_`, `-`) used when creating sessions.
Application description	Optional description for internal documentation.
Logo URL	URL of the logo displayed on the checkout page.
Select countries	Countries where this application is available.
Origin URLs	Allowed origins that can initialize this application, such as `https://www.yourstore.com`. For testing, enable the Allow all origins setting, but restrict it in production.
Payment return URL	URL of the web page to which Customers are redirected after Payment completion.
Discount Code function	Toggle to show or hide the Discount Code input field on the checkout page.

User agreements

User agreements display legal terms (privacy policy, terms of service) during checkout. Customers must accept these agreements to complete their purchase.

Field	Description
User agreement name	Internal name for the agreement.
User agreement text	Agreement text shown to Customers (supports links).
User agreement method	Indicates hether acceptance requires a mandatory checkbox.

You can add multiple user agreements to a single application.

Payment Integrations

Payment Integrations connect your application to payment methods provided by installed connectors. Each integration defines which Payment method appears in checkout and under what conditions.

Payment Integration types

Checkout supports two integration types: web components and drop-in. Web components give you full control over layout, labels, icons, and conditional display logic for each Payment method. Drop-in renders all Payment methods in a single pre-built container controlled by the Connector and PSP.

For a detailed comparison of these integration types, including Connector availability and configuration options, see Connectors and Applications.

Configuration fields

When adding a Payment Integration, you select a Connector and integration type, then configure fields like Payment method, display name, integration key, and optional predicate conditions.

For the complete list of configuration fields for both web components and drop-in integrations, see Connectors and Applications. For predicate syntax and examples, see Payment Integration predicates.

Payment method ordering

The first Payment Integration in the list becomes the default on the checkout page. To reorder, follow these steps:

Click Manage order of payment integrations (frontend).
Drag integrations into the required order.
Click Save.

Activation

Payment Integrations are deactivated by default after creation. Toggle the Status switch to activate each integration before use.

Checkout generates a unique Payment Integration ID when you save the configuration. This ID is required when using the Checkout Transactions API.

Key takeaways

The setup for Checkout consists of four phases: permissions, API Client creation, Connector installation, and application configuration.
Permissions and subscriptions are confirmed once per project, allowing Checkout to access your Composable Commerce data.
Create a dedicated API Client with specific scopes like manage_payments, view_sessions, and manage_orders for your Payment and gift card Connectors.
Payment Connectors integrate Checkout with PSPs—install from the Connect Marketplace and configure with your Project credentials.
Checkout Applications define checkout behavior—create multiple applications for different brands, countries, or business requirements.
Web components provide granular control and conditional logic; the drop-in configuration offers faster setup with less customization.
Payment Integrations are deactivated by default—make sure to toggle the Status switch after configuration.
Payment Integration keys are required when using the Checkout Transactions API for captures, cancellations, and refunds.

Set up Checkout

Learn how to configure commercetools Checkout in the Merchant Center before integrating the SDK.

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

Grant permissions and subscriptions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

Set up for first time.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

If permissions or subscription were previously deleted.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create an API Client for your Connectors.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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