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:
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:
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.
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).
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.
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.
Payment links
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:
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