> 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](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_adyens.md), [Braintree](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_braintrees.md), [Checkout.com](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_checkout_coms.md), [PayPal](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_paypals.md), [Stripe](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_stripes.md), [gift card](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_gift_cards.md), [manual](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_manuals.md), or [external](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_externals.md) — and controls how [payment sessions](https://docs.commercelayer.io/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:

<table><thead><tr><th width="260">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>payment_setting_adyens</code></strong></td><td>Adyen gateway configuration.</td></tr><tr><td><strong><code>payment_setting_braintrees</code></strong></td><td>Braintree gateway configuration.</td></tr><tr><td><strong><code>payment_setting_checkout_coms</code></strong></td><td>Checkout.com gateway configuration.</td></tr><tr><td><strong><code>payment_setting_paypals</code></strong></td><td>PayPal gateway configuration.</td></tr><tr><td><strong><code>payment_setting_stripes</code></strong></td><td>Stripe gateway configuration.</td></tr><tr><td><strong><code>payment_setting_gift_cards</code></strong></td><td>Commerce Layer gift card payments.</td></tr><tr><td><strong><code>payment_setting_manuals</code></strong></td><td>Manual payment processing.</td></tr><tr><td><strong><code>payment_setting_externals</code></strong></td><td>Custom external gateway configuration.</td></tr></tbody></table>

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

<table><thead><tr><th width="260">Type</th><th>Accepted values</th><th width="200">Default (when omitted)</th></tr></thead><tbody><tr><td><strong><code>payment_setting_adyens</code></strong></td><td><code>70</code>, <code>71</code>, <code>72</code></td><td><strong><code>72</code></strong></td></tr><tr><td><strong><code>payment_setting_braintrees</code></strong></td><td><code>2019-01-01</code></td><td><strong><code>2019-01-01</code></strong></td></tr><tr><td><strong><code>payment_setting_stripes</code></strong></td><td><code>2019-05-16</code>, <code>2025-11-17.clover</code></td><td><strong><code>2025-11-17.clover</code></strong></td></tr></tbody></table>

{% 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](https://docs.commercelayer.io/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](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#requesting-a-specific-internal-version), [payment wallets](https://docs.commercelayer.io/core-api-reference/2026-05/payment_wallets.md#triggers), [payment links](https://docs.commercelayer.io/core-api-reference/2026-05/payment_links.md#triggers), and [payment transactions](https://docs.commercelayer.io/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:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "type": "payment_authorizations",
    "attributes": {
<strong>      "_internal_version": "LineItemSku"
</strong>    },
    "relationships": {
      "payment_session": { "data": { "type": "payment_sessions", "id": "..." } }
    }
  }
}
</code></pre>

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](https://docs.commercelayer.io/core/api-credentials.md#sales-channel) API credentials, not just [integration](https://docs.commercelayer.io/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](https://docs.commercelayer.io/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](https://docs.commercelayer.io/core-api-reference/2026-05/payment_rules.md) are market-level rules that affect payment settings in two ways: some rules make specific settings available for a given order only when their conditions are met, while others can block placement if the payment coverage doesn't meet a configured threshold.

## Status

Every payment setting has a read-only `status` attribute that tells whether Commerce Layer can receive the gateway's [webhook events](#webhook-provisioning) for it:

<table><thead><tr><th width="130">Status</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>pending</code></strong></td><td>The gateway webhook isn't configured yet. The setting can't be used for payments.</td></tr><tr><td><strong><code>active</code></strong></td><td>The gateway webhook is configured. The setting can be used for payments.</td></tr></tbody></table>

Braintree, gift card, manual, and external payment settings don't rely on a webhook provisioned by Commerce Layer, so they're active as soon as they're created. Adyen, Checkout.com, PayPal, and Stripe payment settings become active once their webhook is configured. Once active, a payment setting never goes back to the `pending` status.

A pending payment setting is excluded from the `available_payment_settings` relationship on orders, and creating a payment link or a payment wallet against it is rejected with a `422 Unprocessable Entity` error.

{% hint style="info" %}
When a payment setting becomes active, Commerce Layer triggers the `payment_settings.activate` [webhook](https://docs.commercelayer.io/core-api-reference/2026-05/webhooks.md) topic, along with the subtype-specific one (e.g. `payment_setting_stripes.activate`).
{% endhint %}

### Webhook provisioning

When an Adyen, Checkout.com, PayPal, or Stripe payment setting is created, Commerce Layer tries to configure the gateway webhook automatically, using the credentials you provided. If the gateway rejects the request — e.g. because the API credentials lack the necessary permissions — the payment setting is still created, but stays in the `pending` status.

To bring a pending payment setting to the `active` status, you can:

* Fix the credentials — updating them on a pending payment setting automatically triggers a new provisioning attempt.
* Retry without changing anything, by sending a `PATCH` request with the `_provision_webhook` trigger attribute set to `true`. If the gateway rejects the request again, the error is returned with a `422 Unprocessable Entity` status code.
* Configure the webhook manually on the gateway side and set the related credential attribute — only supported by [Adyen](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_adyens.md#webhook-management).

{% hint style="warning" %}
Removing the webhook credentials from an active payment setting is rejected with a `422 Unprocessable Entity` error.
{% endhint %}

## 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
