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.

These authorizations 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 client is managed by Checkout; you must not modify or delete it.

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

Create an API Client with the following scopes:

manage_payments: create and update Payment resources
view_sessions: create Checkout sessions
view_api_clients: validate API Client credentials
manage_orders: create and update Orders
introspect_oauth_tokens: verify OAuth tokens
manage_checkout_payment_intents: trigger payment captures, cancellations, and refunds

If you install the Sample Payment Connector, we recommend that you also add the manage_types scope.

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 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 that determine how Payment methods render.

Feature	Web components	Drop-in
Rendering	Each Payment method has its own component.	All Payment methods in one pre-built UI container.
Customizability	Configure labels, icons, and conditional display logic.	Appearance controlled by Connector and PSP.
Predicates	Define conditions for when Payment methods appear.	No conditional logic—PSP controls availability.
UI control	Full control over layout and presentation.	Connector defines layout.
Best for	Advanced customization and business logic.	Quick setup with minimal configuration.

Connector availability varies: Adyen supports both types, whereas PayPal supports only web components. You can choose the Payment method based on your customization needs and development timeline.

Configuration fields

When adding a Payment Integration, configure the following:

Connector selection

Choose an installed Payment or gift card Connector.
The Connector must be installed in your Organization before it appears in the list.

Integration type

Select Web components or Drop-in.
If the Connector supports only one type, then it's preselected.

Web components configuration

Field	Description
Payment method	Specific payment method to activate, such as credit card, Klarna, PayPal, and more.
Payment Integration name	Display name in the Merchant Center (not shown to Customers).
Payment Integration key	Optional unique identifier (2-256 characters) that's required for the Checkout Transactions API
Payment Integration conditions	Optional predicate expression that defines when this method is available. For example, `cart.totalPrice.currencyCode = "EUR"`. Leave it blank to always show. For more information, see Payment Integration predicates.
Automated reversal	Enable to automatically refund failed Orders. You can define conditions by using predicates. For more information, see Payment Integration predicates.

Drop-in configuration:

Field	Description
Drop-in integration name	Display name in the Merchant Center (not shown to Customers).
Payment Integration key	Optional unique identifier (2-256 characters) that's required for the Checkout Transactions API.
Automated reversal	Enable to automatically refund failed Orders. You can define conditions by using 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;}