For the complete documentation index, see llms.txt. This page is also available as Markdown.
Beta

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. They hold the credentials and configuration required to process payments through the Checkout.com payment gateway.

Credentials

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

Attribute
Description
Required

secret_key

Checkout.com secret API key for server-side requests.

public_key

Checkout.com public key — used to initialize the SDK client and typically shared with your client-side integration for tokenization.

entity_id

Checkout.com entity ID — needed only if your API key isn't restricted to a single entity. When set, the automatically provisioned webhook is scoped to it.

processing_channel_id

Checkout.com processing channel ID — needed only if your API key isn't restricted to a single processing channel. When set, it's sent on every payment session, payment, and payment link request.

webhook_endpoint_id

ID of the automatically created Checkout.com Workflow that delivers webhook events.

webhook_endpoint_secret

HMAC secret used to verify incoming Checkout.com webhook events — generated automatically.

Capabilities

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

Feature
Supported

Payment sessions

Payment wallets

Payment links

3DS / SCA

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.

When client_data has no payment_method, Commerce Layer creates a hosted Checkout.com 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.

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).

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).

If payment_method starts with pay_ (an Apple Pay / Google Pay Payment Request Button token, or the payment ID of a completed Flow payment), 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.

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.

You can find more information about how this compares to the other payment providers here.

Vaulting during a payment

When a payment session with vaulting enabled goes through the Flow integration, Commerce Layer asks Checkout.com to store the card as part of the Flow payment session, under the Checkout.com customer already stored on the customer's wallets for the same payment setting, or under a new one created from the customer's email. Once the Flow payment ID is submitted as payment_method in the session's client_data and the authorization succeeds, Commerce Layer creates the wallet from the stored card, already succeeded and linked to the session.

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.

Once a wallet is cancelled, the same card can be stored again, in a new wallet.

A Checkout.com payment link requires a payment session to already be associated with it at creation time — like Adyen, and unlike Stripe.

Webhook management

When a Checkout.com payment setting is created, Commerce Layer registers a Workflow 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. If the request fails — e.g. because the secret key lacks the necessary permissions — the payment setting is still created, but stays in the pending status until the webhook is provisioned (more details here). 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:

Event
Action

payment_approved

Creates or updates a payment authorization — succeeded.

payment_declined

Creates or updates a payment authorization — failed.

card_verified

Same as payment_approved above — sent instead for a zero-amount card-verification request rather than an actual charge.

card_verification_declined

Same as payment_declined above — sent instead for a zero-amount card-verification request rather than an actual charge.

payment_captured

Creates or updates a payment capture — succeeded.

payment_capture_declined

Creates or updates a payment capture — failed.

payment_voided

Creates or updates a payment void — succeeded.

payment_void_declined

Creates or updates a payment void — failed.

payment_refunded

Creates or updates a payment refund — succeeded.

payment_refund_declined

Creates or updates a payment refund — failed.

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.

Last updated