> 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_settings.md). # Payment settings The payment setting object and the allowed CRUD operations on the related resource endpoint Payment settings are the gateway configuration objects in Commerce Layer's Payments API. Each payment setting represents a specific payment provider configuration — [Adyen](/core-api-reference/2026-05/payment_setting_adyens.md), [Braintree](/core-api-reference/2026-05/payment_setting_braintrees.md), [Checkout.com](/core-api-reference/2026-05/payment_setting_checkout_coms.md), [PayPal](/core-api-reference/2026-05/payment_setting_paypals.md), [Stripe](/core-api-reference/2026-05/payment_setting_stripes.md), [gift card](/core-api-reference/2026-05/payment_setting_gift_cards.md), [manual](/core-api-reference/2026-05/payment_setting_manuals.md), or [external](/core-api-reference/2026-05/payment_setting_externals.md) — and controls how [payment sessions](/core-api-reference/2026-05/payment_sessions.md) are created and processed. {% hint style="info" %} This is an **immutable API**, meaning that create, update, and delete operations are not allowed on this endpoint. You can only fetch a list of payment settings or a single payment setting object. For the full set of available CRUD actions, refer to the specific payment setting type endpoints. {% endhint %} Payment settings are polymorphic. The concrete type can be one of the following subtypes:
TypeDescription
payment_setting_adyensAdyen gateway configuration.
payment_setting_braintreesBraintree gateway configuration.
payment_setting_checkout_comsCheckout.com gateway configuration.
payment_setting_paypalsPayPal gateway configuration.
payment_setting_stripesStripe gateway configuration.
payment_setting_gift_cardsCommerce Layer gift card payments.
payment_setting_manualsManual payment processing.
payment_setting_externalsCustom external gateway configuration.
## Versioning Payment settings carry two independent versioning concepts: the [gateway version](#gateway-version), which controls the external API version used to talk to the payment provider, and the [internal versions](#internal-versions), a read-only field that tracks Commerce Layer's own internal payload-building logic. ### Gateway version The `gateway_version` attribute controls which version of the external payment provider's API Commerce Layer uses when processing transactions for that setting. It's only meaningful — and only settable — for the payment types listed below. It's always `null` for every other type. That's because Checkout.com and PayPal's SDK clients pin no API version of their own, and manual, gift card, and external payment settings never talk to a versioned external API at all.
TypeAccepted valuesDefault (when omitted)
payment_setting_adyens70, 71, 7272
payment_setting_braintrees2019-01-012019-01-01
payment_setting_stripes2019-05-16, 2025-11-17.clover2025-11-17.clover
{% hint style="warning" %} This gateway version information is unrelated to the legacy `adyen_gateways.api_version` field used by the older `2017-08` [Adyen integration](/core-api-reference/adyen_gateways.md) — the two live on different resources, accept different value ranges (`api_version` supports `66`–`71`), and are not interchangeable. {% endhint %} ### Internal versions The `internal_versions` attribute is a **read-only**, Commerce-Layer-internal field — it is not the same thing as `gateway_version` and isn't something you configure. It records which internal payload-building logic is pinned for each action on that specific payment setting, for example: ```json { "payment_intent": "V1", "setup_intent": "V3" } ``` Each key is the name of a specific payload/action (e.g. `payment_intent`, `setup_intent`, `session`, `capture`), scoped to how that one action is built — not a single version for the whole gateway. This lets Commerce Layer evolve how a request is built for new settings without changing behavior for existing ones, and lets a version pinned for one action (e.g. `capture`) differ from the version used for another (e.g. `refund`) on that same setting. {% hint style="info" %} This has no effect on which external API version is used to talk to the gateway — that's controlled entirely by the [gateway version](#gateway-version). {% endhint %} Whether a payment setting supports internal versioning at all is exposed via the read-only `internal_versionable` boolean: * `false` for Checkout.com, gift card, and manual payment settings. * `true` for Adyen, Braintree, PayPal, Stripe, and external payment settings. {% hint style="warning" %} Sending `_internal_version` on a resource whose payment setting is not internal-versionable is rejected with a `422 Unprocessable Entity` error — it is not silently ignored. {% endhint %} #### Per-request overrides Using internal versions lets you pin a default for the setting as a whole, but individual payment resources — [payment sessions](/core-api-reference/2026-05/payment_sessions.md#requesting-a-specific-internal-version), [payment wallets](/core-api-reference/2026-05/payment_wallets.md#triggers), [payment links](/core-api-reference/2026-05/payment_links.md#triggers), and [payment transactions](/core-api-reference/2026-05/payment_transactions.md#internal-version) — can override it for a single request via that resource's own `_internal_version` trigger attribute, without changing the setting's default for every other request. For example, to pin the `LineItemSku` payload variant for an Adyen payment authorization, send: 
{
  "data": {
    "type": "payment_authorizations",
    "attributes": {
      "_internal_version": "LineItemSku"
    },
    "relationships": {
      "payment_session": { "data": { "type": "payment_sessions", "id": "..." } }
    }
  }
}
The value must always be one of the versions already available for that specific resource's own action — Commerce Layer validates it against the same set of built-in payload variants exposed via `internal_versions`, scoped to the resource's own family (e.g. a payment session can only request session-family versions, not one meant for a payment wallet). An unsupported value is rejected with a `422 Unprocessable Entity` error. {% hint style="info" %} Unlike `options`, `_internal_version` never exposes raw gateway parameters — it only lets the caller pick among payload variants Commerce Layer has already built. That makes it safe to use with [sales channel](/core/api-credentials.md#sales-channel) API credentials, not just [integration](/core/api-credentials.md#integration) ones. {% endhint %} ## Automation flags All payment settings expose the following top-level boolean attributes: * `auto_capture` — when `true`, a capture is created automatically as soon as the authorization succeeds, without requiring a separate API call. * `auto_place` — when `true`, the associated order is placed automatically when the payment session transitions to `authorized`, without requiring a separate `_place` call. ## Idempotency window The `idempotency_window_mins` attribute controls how long an open [payment transaction](/core-api-reference/2026-05/payment_transactions.md#idempotency) keeps absorbing identical repeats. A transaction created within that many minutes of a matching open one inherits its idempotency key, so the gateway deduplicates the two. Past the window, a repeat gets a fresh key and reaches the provider as its own operation. {% hint style="info" %} The default idempotency window is **1 hour** (60 minutes) and applies to every payment setting subtype. Widen it when the gateway is slow to confirm and you want a longer guard against duplicate submissions. Narrow it when an operation left hanging in `processing` — because a gateway event never arrived — should stop blocking retries sooner. Braintree, gift card, and manual settings never send the key to a provider, so the window has no practical effect on them. {% endhint %} {% hint style="warning" %} The window bounds open transactions only. A repeat of an operation that has already reached a final status — whether it succeeded or not — is never deduplicated, whatever the window is set to. {% endhint %} ## Payment rules [Payment rules](/core-api-reference/2026-05/payment_rules.md) are market-level rules that affect payment settings in two ways: some rules control which settings are available for a given order, while others can block placement if the payment coverage doesn't meet a configured threshold. ## Enabling and disabling Payment settings can be enabled or disabled. Disabled settings are excluded from the `available_payment_settings` relationship on orders and cannot be used for new sessions or wallets. Use the `_disable` and `_enable` trigger attributes to toggle the state. ## Connectivity check Payment settings expose a `_check_client` trigger attribute that tests the connection to the underlying payment provider using the stored credentials. On success, the setting's configuration is verified without creating any real transactions. --- # 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_settings.md?ask=&goal= ``` `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.