> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# API Setup Intents

> Un Setup Intent enregistre le moyen de paiement d'un acheteur pour une utilisation ultérieure, sans prélever d'argent immédiatement.

Créez-en un à partir d'un jeton de confirmation collecté par les éléments de paiement en mode configuration, ou à partir d'un moyen de paiement déjà enregistré pour le vérifier à nouveau. Il suit le même processus de collecte qu'un paiement, de sorte que l'acheteur peut encore avoir une étape à accomplir : 3D Secure sur une carte, une inscription hébergée ou l'association d'un compte bancaire.

La réponse de création correspond au setup intent tel que créé, et non à son résultat. Transmettez son `client_secret` à `handleNextAction` des éléments, ou interrogez [Récupérer le statut](https://docs.whop.com/fr/api-reference/setup-intents/retrieve-setup-status.md) pour savoir où en est la configuration et ce qui reste à faire. Une fois le statut `succeeded` atteint, `payment_method_id` désigne le moyen enregistré, et Create Payment permet de le débiter.

## Endpoints

| Endpoint | Requête |
| - | - |
| [Lister les setup intents](https://docs.whop.com/fr/api-reference/setup-intents/list-setup-intents.md) | GET `/setup_intents` |
| [Récupérer un setup intent](https://docs.whop.com/fr/api-reference/setup-intents/retrieve-setup-intent.md) | GET `/setup_intents/{id}` |
| [Récupérer le statut de configuration](https://docs.whop.com/fr/api-reference/setup-intents/retrieve-setup-status.md) | GET `/setup_intents/{setup_intent_id}/status` |
| [Créer un setup intent](https://docs.whop.com/fr/api-reference/setup-intents/create-setup-intent.md) | POST `/setup_intents` |
| [Mettre à jour l'URL de retour de configuration](https://docs.whop.com/fr/api-reference/setup-intents/update-setup-return-url.md) | PATCH `/setup_intents/{setup_intent_id}/return_url` |

## Attributs

**id** `string` *required*

ID du setup intent, préfixé par `sint_`.

**account\_id** `string | null` *required*

Le compte pour lequel le moyen de paiement est enregistré, préfixé par `biz_`.

**checkout\_configuration\_id** `string | null` *required*

La configuration de paiement via laquelle cette configuration a été créée, préfixée par `ch_`. Null pour une configuration créée via cette API plutôt que via un checkout hébergé.

**client\_secret** `string | null` *required*

L'identifiant que l'interface de l'acheteur présente pour interroger cette configuration et définir son URL de retour — transmettez-le à `handleNextAction` des éléments. Présent uniquement sur les configurations créées via cette API, et toujours null dans les réponses de liste — récupérez le setup intent pour l'obtenir.

**created\_at** `string` *required*

Date de création du setup intent, sous forme d'horodatage ISO 8601.

**last\_setup\_error** `object | null` *required*

Pourquoi la configuration s'est arrêtée là où elle s'est arrêtée, ou `null` si rien n'a échoué. Présent avec `canceled` — un abandon par l'acheteur ne comporte aucun code, un refus du prestataire en comporte un. Supprimé une fois la configuration réussie.

> [accordion] Propriétés
>
> **code** `string | null` *required*
>
> Une classification de l'échec lisible par machine, par ex. `enrollment_declined`. Absent lorsque l'acheteur a simplement abandonné la configuration.
>
> **message** `string | null` *required*
>
> Une explication lisible de l'échec.

**member\_id** `string | null` *required*

L'enregistrement de membre de l'acheteur sur le compte, préfixé par `mber_`. Null sans l'autorisation member:basic:read, sauf si l'appelant est l'acheteur.

**metadata** `object | null` *required*

Vos propres données clé-valeur associées lors de la création du setup intent.

**payment\_instrument** `object | null` *required*

Le moyen associé à cette configuration, mis en forme pour l'affichage : un nom destiné à l'acheteur, le jeu d'icônes standard, ainsi que la marque de la carte, ses quatre derniers chiffres, son numéro d'identification de l'émetteur, sa date d'expiration et l'id de transaction réseau lorsqu'il s'agit d'une carte. Null tant qu'aucun moyen n'a été collecté.

> [accordion] Propriétés
>
> **card** `object | null` *required*
>
> Paiements par carte, Apple Pay et Google Pay uniquement : le réseau de la carte, ses quatre derniers chiffres, son numéro d'identification de l'émetteur, sa date d'expiration et l'id de transaction réseau.
>
> > [accordion] Propriétés
> >
> > **brand** `string | null` *required*
> >
> > L'identifiant du réseau (`visa`, `amex`, …), correspondant aux entrées de `card.networks` et aux moyens de paiement par carte enregistrés. Null lorsque le coffre-fort n'a pas enregistré le réseau.
> >
> > **exp\_month** `number | null` *required*
> >
> > Le mois d'expiration de la carte, de 1 à 12. Null lorsque le coffre-fort ne l'a pas enregistré.
> >
> > **exp\_year** `number | null` *required*
> >
> > L'année d'expiration de la carte, sur quatre chiffres. Null lorsque le coffre-fort ne l'a pas enregistrée.
> >
> > **issuer\_identification\_number** `string | null` *required*
> >
> > Le numéro d'identification de l'émetteur, également appelé BIN : les six ou huit premiers chiffres de la carte, qui identifient la banque émettrice. Null lorsque le processeur ne l'a pas communiqué.
> >
> > **last4** `string | null` *required*
> >
> > Les quatre derniers chiffres de la carte, lorsqu'ils ont été saisis.
> >
> > **network\_transaction\_id** `string | null` *required*
> >
> > L'id de transaction réseau que ce compte utilise pour la carte. Il s'agit de l'id propre à ce compte, issu de son premier prélèvement ou de sa première vérification avec le client présent sur cette carte, lorsque Whop en dispose. Sinon, il s'agit d'un id de transaction réseau antérieur pour cette carte, qui peut provenir de la transaction d'un autre compte ou avoir été fourni avec la carte. Citez-le comme transaction antérieure lors d'un prélèvement ultérieur de cette carte initié par le marchand sur ce compte. Null tant qu'il n'en existe pas. Un webhook envoyé au moment où un paiement est enregistré pour la première fois peut contenir `null` ; récupérez donc le paiement pour le lire.
>
> **display\_name** `string` *required*
>
> Nom du moyen de paiement destiné à l'acheteur — "Visa •••• 4242" lorsque la carte est connue, sinon le nom propre du moyen ("Klarna").
>
> **icons** `object` *required*
>
> Le jeu d'icônes standard : formats carré et carte, chacun en variantes claire et sombre.
>
> > [accordion] Propriétés
> >
> > **card** `object` *required*
> >
> > La vignette aux proportions d'une carte bancaire (48x30).
> >
> > > [accordion] Propriétés
> > >
> > > **dark** `object` *required*
> > >
> > > La variante de couleurs pour les surfaces sombres.
> > >
> > > > [accordion] Propriétés
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Image matricielle de secours à la taille native du format.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Image matricielle de secours en double densité.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Image matricielle de secours en quadruple densité.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > Le fichier vectoriel. À privilégier partout où le SVG s'affiche.
> > >
> > > **light** `object` *required*
> > >
> > > La variante de couleurs pour les surfaces claires.
> > >
> > > > [accordion] Propriétés
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Image matricielle de secours à la taille native du format.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Image matricielle de secours en double densité.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Image matricielle de secours en quadruple densité.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > Le fichier vectoriel. À privilégier partout où le SVG s'affiche.
> >
> > **square** `object` *required*
> >
> > La vignette carrée (32x32).
> >
> > > [accordion] Propriétés
> > >
> > > **dark** `object` *required*
> > >
> > > La variante de couleurs pour les surfaces sombres.
> > >
> > > > [accordion] Propriétés
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Image matricielle de secours à la taille native du format.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Image matricielle de secours en double densité.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Image matricielle de secours en quadruple densité.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > Le fichier vectoriel. À privilégier partout où le SVG s'affiche.
> > >
> > > **light** `object` *required*
> > >
> > > La variante de couleurs pour les surfaces claires.
> > >
> > > > [accordion] Propriétés
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Image matricielle de secours à la taille native du format.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Image matricielle de secours en double densité.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Image matricielle de secours en quadruple densité.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > Le fichier vectoriel. À privilégier partout où le SVG s'affiche.
>
> **installment\_count** `number | null` *required*
>
> Moyens de paiement échelonné uniquement : nombre de paiements en lesquels le prélèvement est divisé. Il s'agit d'une donnée, pas d'un texte — composez et traduisez le libellé côté client.
>
> **payment\_method\_type** `string` *required*
>
> L'identifiant du type de moyen de paiement, par ex. `card`, `klarna`, `apple_pay`.

**payment\_method\_id** `string | null` *required*

Le moyen de paiement enregistré, préfixé par `payt_`, prêt à être débité avec Create Payment. Null tant que la configuration n'a pas le statut `succeeded`.

**payment\_method\_type** `string | null` *required*

Le type de moyen de paiement en cours d'enregistrement, par exemple `card` ou `us_bank_account`.

**return\_url** `string | null` *required*

La page sur laquelle l'acheteur arrive après avoir terminé une étape hors site, ou `null` pour le laisser là où il se trouve.

**status** `string` *required*

Où en est la configuration. **Un 201 ou un 200 signifie que nous avons répondu, et non que le moyen a été enregistré — basez toujours votre logique sur ce champ.** `requires_action` — l'acheteur a une étape en attente ; transmettez `client_secret` aux éléments ou interrogez Retrieve setup status. `processing` — le processeur est en train de statuer. `succeeded` — le moyen est enregistré, et seul ce statut signifie qu'il l'est. `canceled` — abandonné ou refusé ; consultez `last_setup_error`.

Options disponibles : `processing`, `succeeded`, `canceled`, `requires_action`

**three\_ds\_level** `string | null` *required*

Comportement 3D Secure pour les paiements par carte en session pris en charge. `mandate_challenge` exige une vérification 3DS avant le traitement du paiement ; `mandate_if_required` impose une vérification uniquement lorsque le processeur de paiement l'exige ; `frictionless_if_required` utilise le flux 3DS sans friction habituel. Les paiements de 1 000 \$ ou plus utilisent `mandate_if_required`, sauf si `mandate_challenge` est sélectionné. Les exigences en matière de risque et de récupération d'authentification peuvent prévaloir sur cette préférence. Le paramètre demandé pour cette configuration, ou `null` s'il n'est pas défini.

Options disponibles : `mandate_challenge`, `mandate_if_required`, `frictionless_if_required`

**three\_ds\_verified** `boolean` *required*

Vrai lorsque l'acheteur a effectué la vérification 3D Secure lors de l'enregistrement de ce moyen de paiement.

**updated\_at** `string` *required*

Date de la dernière mise à jour du setup intent, sous forme d'horodatage ISO 8601.

**user** `object | null` *required*

L'utilisateur qui enregistre le moyen de paiement. Null lorsque l'acheteur est un compte plutôt qu'un utilisateur.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> ID utilisateur, préfixé par `user_`.
>
> **name** `string | null` *required*
>
> Nom d'affichage.
>
> **profile\_picture** `object` *required*
>
> Conteneur de l'avatar. Son `url` est toujours présent et correspond à un espace réservé généré lorsque l'utilisateur n'a défini aucune photo.
>
> > [accordion] Propriétés
> >
> > **url** `string` *required*
> >
> > URL de l'image de l'avatar. Toujours présente. Il s'agit d'un espace réservé généré lorsque l'utilisateur n'a défini aucune photo.
>
> **username** `string` *required*
>
> Nom d'utilisateur public.

```json SetupIntent theme={null}
{
	"id": "sint_xxxxxxxxxxxxxx",
	"account_id": "biz_xxxxxxxxxxxxxx",
	"checkout_configuration_id": null,
	"client_secret": null,
	"created_at": "2026-09-22T12:00:00.000Z",
	"last_setup_error": null,
	"member_id": "mber_xxxxxxxxxxxxxx",
	"metadata": {
		"customer_id": "cus_4417"
	},
	"payment_method_id": "payt_xxxxxxxxxxxxxx",
	"payment_method_type": "card",
	"return_url": "https://shinetime.example/billing/saved",
	"status": "succeeded",
	"three_ds_verified": false,
	"three_ds_level": "mandate_challenge",
	"updated_at": "2026-09-22T12:00:00.000Z",
	"user": {
		"id": "user_xxxxxxxxxxxxxx",
		"name": "Dana Whitfield",
		"profile_picture": {
			"url": "https://ui-avatars.com/api/"
		},
		"username": "danawhitfield"
	},
	"payment_instrument": {
		"card": {
			"brand": "visa",
			"issuer_identification_number": "41111111",
			"last4": "4242",
			"exp_month": 11,
			"exp_year": 2030,
			"network_transaction_id": "016153570198200"
		},
		"display_name": "Visa •••• 4242",
		"icons": {
			"card": {
				"dark": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				},
				"light": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				}
			},
			"square": {
				"dark": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				},
				"light": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				}
			}
		},
		"installment_count": null,
		"payment_method_type": "card"
	}
}
```
