# Set up Checkout

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:

1. **Grant permissions**: allow Checkout to create an API Client and subscribe to Cart/Order events.
2. **Create API credentials**: generate an API Client for your application code and Connectors to authenticate with Checkout.
3. **Install Payment Connectors**: add integrations with Payment Service Providers (PSPs) from the Connect Marketplace.
4. **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

1. In the Merchant Center, go to **Checkout > Overview**.
2. Click **Get started**.
   ![Merchant Center Checkout overview page displaying the Get started button to initiate first-time Checkout configuration.](https://docs.commercetools.com/learning-implement-checkout/images/checkout-get-started-button.png)
3. Click **Let's proceed to handle the required confirmation**.
4. Review the required scopes and Subscription settings.
5. 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

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

Checkout's internal API Client appears in **Settings > Developer Settings > API Clients** as `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](/checkout/scopes.md).

### Create the client

1. Go to **Settings > Developer settings > API clients**.
2. Click **Create API client**.
3. Enter a name, such as "Checkout Integration Client".
4. Select the required scopes mentioned earlier.
5. Click **Create API client**.
6. **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

1. Go to **My Profile > Organizations & teams**.
2. Select your Organization.
3. Select the **Connect** tab.
4. Search for `Sample payment connector for checkout`.
5. 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](/checkout/connectors-and-applications.md).

#### 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](/checkout/connectors-and-applications.md). For predicate syntax and examples, see [Payment Integration predicates](/checkout/payment-integration-predicates.md).

#### Payment method ordering

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

1. Click **Manage order of payment integrations (frontend)**.
2. Drag integrations into the required order.
3. 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](/checkout/transactions-api.md).

## 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 commercetools 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](/checkout/transactions-api.md) for captures, cancellations, and refunds.

## Related pages

- [Area overview page with navigation](/learning-implement-checkout.md)
- [Previous page: Introduction to Checkout](/learning-implement-checkout/implement-commercetools-checkout/intro-to-commercetools-checkout.md)
- [Next page: Build with the Checkout SDK](/learning-implement-checkout/implement-commercetools-checkout/build-with-the-checkout-sdk.md)
- [Search documentation and API specs](/search.md)