> 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](/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](/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](/core-api-reference/2026-05/payment_authorizations.md#handling-3ds-and-customer-action)).

{% hint style="info" %}
A session that renews an [order subscription](/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](/core-api-reference/2026-05/payment_wallets.md#token-references).
{% 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](/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`. 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 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_setting_stripes.md?ask=<question>&goal=<endgoal>
```

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