> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_checkout_coms.md).

# Payment setting checkout coms

The payment setting checkout com object and the allowed CRUD operations on the related resource endpoint

Checkout.com payment settings are the Checkout.com-specific subtype of [payment settings](/core-api-reference/2026-05/payment_settings.md). They hold the credentials and configuration required to process payments through the [Checkout.com](https://www.checkout.com) payment gateway.

## Credentials

Setting up a Checkout.com payment setting requires the following credential attributes:

<table><thead><tr><th width="260">Attribute</th><th>Description</th><th width="100" data-type="checkbox">Required</th></tr></thead><tbody><tr><td><strong><code>secret_key</code></strong></td><td>Checkout.com secret API key for server-side requests.</td><td>true</td></tr><tr><td><strong><code>public_key</code></strong></td><td>Checkout.com public key, used to initialize the SDK client and typically shared with your client-side integration for tokenization.</td><td>true</td></tr><tr><td><strong><code>webhook_endpoint_id</code></strong></td><td>ID of the automatically created Checkout.com Workflow that delivers webhook events.</td><td>false</td></tr><tr><td><strong><code>webhook_endpoint_secret</code></strong></td><td>HMAC secret used to verify incoming Checkout.com webhook events, generated automatically.</td><td>false</td></tr></tbody></table>

## Capabilities

Checkout.com payment settings support the following Commerce Layer features:

<table><thead><tr><th>Feature</th><th width="100" data-type="checkbox">Supported</th></tr></thead><tbody><tr><td>Payment sessions</td><td>true</td></tr><tr><td>Payment wallets</td><td>true</td></tr><tr><td>Payment links</td><td>true</td></tr><tr><td>3DS / SCA</td><td>true</td></tr></tbody></table>

## Session creation

Checkout.com supports two integration flows, selected automatically depending on whether a `payment_method` token is present in the payment session's `client_data`:

* **Flow** — hosted by Checkout.com, webhook-only.
* **Advanced** — client-submitted token only.

{% tabs %}
{% tab title="Flow" %}
When `client_data` has no `payment_method`, Commerce Layer creates a hosted Checkout.com [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/get-started-with-flow) payment session. The raw response — including the data needed to initialize Checkout.com's Flow component client-side — is available in the `response_data` attribute of the payment session.

{% hint style="info" %}
There's no synchronous authorization step with this flow: the outcome (approved or declined) is only known once the corresponding webhook event arrives (more details [below](#webhook-events)).
{% endhint %}
{% endtab %}

{% tab title="Advanced" %}
When `client_data.payment_method` is present — a token produced client-side via Checkout.com's Frames.js, mobile SDKs, or a Payment Request Button — Commerce Layer authorizes the payment synchronously, with 3DS enabled by default. If a challenge is required, the authorization transitions to `requires_action` with a `redirect` `next_action_type` (more details [here](/core-api-reference/2026-05/payment_authorizations.md#handling-3ds-and-customer-action)).

{% hint style="info" %}
If `payment_method` starts with `pay_` (an Apple Pay / Google Pay Payment Request Button token), the payment has already been processed by Checkout.com client-side — Commerce Layer just fetches and records its outcome instead of submitting a new payment request.
{% endhint %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Regardless of the flow used, capture, void, and refund requests never resolve synchronously for Checkout.com. Even though the initiating API call succeeds, the transaction stays `processing` until the matching Workflow webhook event arrives.
{% endhint %}

## Wallet vaulting

When a payment wallet is created against a Checkout.com payment setting without a `customer_token` supplied, Commerce Layer creates a customer profile on Checkout.com — using the customer's email — and stores its ID as the wallet's customer token. The submitted card token is then vaulted as a Checkout.com instrument associated with that customer, as part of the same request. Vaulting completes synchronously: the wallet transitions directly to `succeeded`, with no `requires_action` step.

{% hint style="info" %}
You can find more information about how this compares to the other payment providers [here](/core-api-reference/2026-05/payment_wallets.md#token-references).
{% endhint %}

### Duplicate wallets

Checkout.com keeps one instrument per card and customer, and returns the same one when that card is stored again — even after it was removed. Commerce Layer reuses the Checkout.com customer already stored on the customer's wallets, or the one registered with the customer's email, so every card of a customer is stored under the same Checkout.com customer. When a payment session with vaulting enabled stores a card the customer already holds in an active wallet, the session is linked to that wallet instead of creating a new one.

{% hint style="warning" %}
Creating a wallet directly for a card that's already stored in one of the customer's active wallets is rejected, with a `422 Unprocessable Entity` error pointing to the existing wallet.
{% endhint %}

{% hint style="info" %}
Once a wallet is [cancelled](/core-api-reference/2026-05/payment_wallets.md#cancelling-a-wallet), the same card can be stored again, in a new wallet.
{% endhint %}

## Payment links

A Checkout.com [payment link](/core-api-reference/2026-05/payment_links.md) requires a payment session to already be associated with it at creation time — like [Adyen](/core-api-reference/2026-05/payment_setting_adyens.md), and unlike [Stripe](/core-api-reference/2026-05/payment_setting_stripes.md).

{% hint style="success" %}
When the link is associated with an order, the generated link also includes a `products` breakdown built from the order's SKU and bundle line items, shown to the customer on Checkout.com's hosted payment page.
{% endhint %}

## Webhook management

When a Checkout.com payment setting is created, Commerce Layer registers a [Workflow](https://www.checkout.com/docs/workflows) with Checkout.com — rather than a plain webhook endpoint — configured to deliver the events below to `webhook_endpoint_url`, signed with the generated `webhook_endpoint_secret`. The workflow is removed from Checkout.com when the payment setting is deleted.

## Webhook events

Commerce Layer listens to the following Checkout.com Workflow events:

<table><thead><tr><th width="330">Event</th><th>Action</th></tr></thead><tbody><tr><td><strong><code>payment_approved</code></strong></td><td>Creates or updates a payment authorization — <code>succeeded</code>.</td></tr><tr><td><strong><code>payment_declined</code></strong></td><td>Creates or updates a payment authorization — <code>failed</code>.</td></tr><tr><td><strong><code>card_verified</code></strong></td><td>Same as <code>payment_approved</code> above — sent instead for a zero-amount card-verification request rather than an actual charge.</td></tr><tr><td><strong><code>card_verification_declined</code></strong></td><td>Same as <code>payment_declined</code> above — sent instead for a zero-amount card-verification request rather than an actual charge.</td></tr><tr><td><strong><code>payment_captured</code></strong></td><td>Creates or updates a payment capture — <code>succeeded</code>.</td></tr><tr><td><strong><code>payment_capture_declined</code></strong></td><td>Creates or updates a payment capture — <code>failed</code>.</td></tr><tr><td><strong><code>payment_voided</code></strong></td><td>Creates or updates a payment void — <code>succeeded</code>.</td></tr><tr><td><strong><code>payment_void_declined</code></strong></td><td>Creates or updates a payment void — <code>failed</code>.</td></tr><tr><td><strong><code>payment_refunded</code></strong></td><td>Creates or updates a payment refund — <code>succeeded</code>.</td></tr><tr><td><strong><code>payment_refund_declined</code></strong></td><td>Creates or updates a payment refund — <code>failed</code>.</td></tr></tbody></table>

Events are matched to a payment session using the `reference` field, which Commerce Layer sets to the session token on every outbound request. For capture, void, and refund events, Commerce Layer first looks for an existing transaction on that session matching the event's `action_id`. If none is found — for example, the action was issued from the Checkout.com Hub rather than through Commerce Layer's API — it's created from the event data alone, provided the session can still be resolved from the reference.

{% hint style="warning" %}
If the session can't be resolved either, the event is silently dropped.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_checkout_coms.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.