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

# Payment setting stripes

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

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

## Credentials

Setting up a Stripe 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>api_key</code></strong></td><td>Stripe secret API key for server-side requests.</td><td>true</td></tr><tr><td><strong><code>public_key</code></strong></td><td>Stripe publishable key for client-side SDK usage.</td><td>false</td></tr><tr><td><strong><code>connected_account</code></strong></td><td>Stripe Connect account ID for marketplace scenarios.</td><td>false</td></tr><tr><td><strong><code>webhook_endpoint_id</code></strong></td><td>ID of the automatically created Stripe webhook endpoint.</td><td>false</td></tr><tr><td><strong><code>webhook_endpoint_secret</code></strong></td><td>Signing secret used to verify incoming Stripe webhook events.</td><td>false</td></tr></tbody></table>

## Gateway versions

Stripe payment settings support the following gateway versions, corresponding to Stripe's API version:

* `2019-05-16`
* `2025-11-17.clover` (default)

## Capabilities

Stripe 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>

## Client-side integration

Stripe requires payment details to be collected and the payment intent confirmed client-side using Stripe.js and [Elements](https://docs.stripe.com/payments/elements) (or the mobile SDKs). Commerce Layer creates the payment intent server-side when a [payment session](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md) is created with a Stripe payment setting. The `client_secret` needed to initialize Elements and confirm the payment intent is available in the `response_data` attribute of the payment session. Once the customer completes the form, including any 3DS/SCA challenge, payment details must be submitted back (more details [here](https://docs.commercelayer.io/core-api-reference/2026-05/payment_authorizations.md#handling-3ds-and-customer-action)).

{% hint style="info" %}
A session that renews an [order subscription](https://docs.commercelayer.io/core-api-reference/2026-05/order_subscriptions.md#unattended-renewals) is the exception: there is no client to confirm it, so Commerce Layer confirms the payment intent server-side, off session, against the stored instrument.
{% endhint %}

## Wallet vaulting

When a payment wallet is created against a Stripe payment setting without a `customer_token` supplied, Commerce Layer creates a customer profile on Stripe and stores its ID as the wallet's customer token. Either way — auto-created or supplied by you — Commerce Layer attaches the payment method to that customer as part of the same vaulting request. It only fails if the payment method is already attached to a different Stripe customer.

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

### Vaulting during a payment

When a payment session has [vaulting enabled](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#vaulting-during-a-charge), Commerce Layer asks Stripe to store the payment method with the payment intent, and creates the wallet from it once the payment succeeds. The `setup_future_usage` value sent to Stripe depends on whether the order has [line items with a frequency](https://docs.commercelayer.io/core-api-reference/2026-05/line_items.md#choosing-line-items-that-generate-subscriptions):

<table><thead><tr><th width="300">Scenario</th><th>Sent to Stripe</th></tr></thead><tbody><tr><td>Storing a new card — no line item with a frequency.</td><td><code>on_session</code> — the card is reused on later orders, with the shopper present.</td></tr><tr><td>Storing a new card — at least one line item with a frequency.</td><td><code>off_session</code> — the card is set up for the renewals charged without the shopper.</td></tr><tr><td>Paying with a wallet — at least one line item with a frequency.</td><td><code>off_session</code> — the saved card is set up for the renewals that follow.</td></tr><tr><td>Paying with a wallet — no line item with a frequency.</td><td>Not sent.</td></tr><tr><td>Renewing an order subscription.</td><td>Not sent — the payment intent is confirmed off session.</td></tr></tbody></table>

{% hint style="info" %}
A `setup_future_usage` value passed in the session's [gateway options](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#gateway-options) always takes precedence over the derived one.
{% endhint %}

{% hint style="warning" %}
If you charge cards stored on orders without a frequency off session outside Commerce Layer, set `setup_future_usage` to `off_session` in the session's `options`: cards set up for on-session use are more likely to be declined when charged without the shopper.
{% endhint %}

### Duplicate wallets

Stripe issues a new payment method every time a card is collected, even when it's the same card of the same customer. Commerce Layer deduplicates wallets by payment method only, so every payment session with vaulting enabled — and every wallet created directly with a newly collected payment method — produces a new wallet for that card.

{% hint style="warning" %}
Only submitting a payment method 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. Beyond that, duplicates must be managed on your side: every Stripe wallet exposes the fingerprint at `payment_data.card.fingerprint`, which is the same for every payment method created from the same card. Before enabling vaulting on a session, check the customer's `succeeded` wallets and offer the one already holding that card instead. To clean up a duplicate, [cancel](https://docs.commercelayer.io/core-api-reference/2026-05/payment_wallets.md#cancelling-a-wallet) the extra wallet.
{% endhint %}

## Webhook management

When a Stripe payment setting is created, Commerce Layer automatically registers a webhook endpoint with Stripe and stores the resulting `webhook_endpoint_id` and `webhook_endpoint_secret`. If the request fails — e.g. because the API 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](https://docs.commercelayer.io/core-api-reference/2026-05/payment_settings.md#webhook-provisioning)). The webhook endpoint is removed from Stripe when the payment setting is deleted.

## Webhook events

Commerce Layer listens to the following Stripe webhook notification events:

<table><thead><tr><th width="480">Event</th><th>Action</th></tr></thead><tbody><tr><td><strong><code>payment_intent.amount_capturable_updated</code></strong></td><td>Creates or updates a payment authorization — <code>succeeded</code>.</td></tr><tr><td><strong><code>payment_intent.payment_failed</code></strong></td><td>Creates or updates a payment authorization — <code>failed</code>.</td></tr><tr><td><strong><code>payment_intent.canceled</code></strong></td><td>Creates or updates a payment void — <code>succeeded</code>.</td></tr><tr><td><strong><code>payment_intent.succeeded</code></strong></td><td>Creates or updates a payment capture — <code>succeeded</code>.</td></tr><tr><td><strong><code>charge.expired</code></strong></td><td>Transitions the payment authorization to <code>expired</code>.</td></tr><tr><td><strong><code>charge.refunded</code></strong></td><td>Creates or updates a payment refund — <code>succeeded</code>.</td></tr><tr><td><strong><code>setup_intent.requires_action</code></strong></td><td>Transitions a payment wallet to <code>requires_action</code>.</td></tr><tr><td><strong><code>setup_intent.canceled</code></strong></td><td>Transitions a payment wallet to <code>canceled</code>.</td></tr><tr><td><strong><code>setup_intent.succeeded</code></strong> / <strong><code>payment_method.updated</code></strong></td><td>Transitions a payment wallet to <code>succeeded</code>.</td></tr><tr><td><strong><code>checkout.session.expired</code></strong></td><td>Transitions a payment link to <code>expired</code>.</td></tr><tr><td><strong><code>checkout.session.completed</code></strong></td><td>Transitions a payment link to <code>completed</code> and creates the associated payment session.</td></tr></tbody></table>

Session events are matched using the `payment_intent` ID, and link events using the checkout session ID. Wallet events are matched using the setup intent ID, except `payment_method.updated`, which is matched using the Stripe payment method ID instead. Missing transactions are created automatically when an event arrives.


---

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