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

# Checkout

> Pilote un checkout hébergé complet pour un ou plusieurs plans — récapitulatif de prix détaillé, codes promo, devise dans laquelle l'acheteur paie, et toute l'interface de collecte du paiement (les éléments de paiement, composés à l'intérieur) — via l'API des sessions de checkout Whop. Montez-le avec `items`, un seul `plan` ou une `checkoutConfiguration` que vous avez créée, et l'élément ouvre lui-même la session de checkout ; l'identifiant de session ne quitte jamais l'élément. Une configuration de checkout en mode setup monte le même élément pour enregistrer un moyen de paiement : rien n'est débité, le moyen de l'acheteur est conservé pour que vous puissiez le débiter plus tard, et le checkout terminé redirige avec `setup_intent_id`. L'acheteur paie à l'intérieur de l'élément, et un checkout terminé redirige l'onglet courant vers `returnUrl`, y compris la page qui contient l'élément. Exécutez les commandes à partir des webhooks plutôt que d'un callback navigateur. Sans `returnUrl`, l'acheteur reste sur la vue de succès propre à l'élément. L'élément pilote automatiquement une étape de paiement externe, comme 3DS ou une page bancaire. Sur whop.com, il ramène l'acheteur dans le checkout restauré ; dans une intégration, l'acheteur revient sur la même `returnUrl` quel que soit le résultat, avec les paramètres de requête `payment` et `status` (`succeeded`, `failed` ou `canceled`), donc la page de `returnUrl` doit lire `status` avant de considérer la visite comme une vente. Un paiement qui échoue à l'intérieur de l'élément rouvre le même checkout en affichant la raison, pour que l'acheteur puisse payer à nouveau. Chaque option est définie à la création : l'élément génère une session de checkout à partir de ces valeurs lors du montage. En modifier une plus tard avec `update()` ou de nouvelles props React échoue au lieu de modifier la commande existante. Montez un nouveau checkout pour changer ce qui est acheté.

> [!NOTE]
>
> Cette page documente `@whop/elements@1.10.0` et `@whop/elements-react@1.10.0`.

*Depuis `v1.0.0`.*

## Playground

Assemblez les éléments avec des données d'exemple. Manipulez les contrôles, ajoutez et organisez des éléments, et observez les événements se déclencher en direct :

```tsx React theme={null}
import { WhopElements, Checkout } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Checkout /* options */>
        {/* mount elements here */}
      </Checkout>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const checkout = window.WhopElements().checkout.create({ /* options */ });
</script>
```

## Options

Transmettez-les à `whop.checkout.create({ … })`, ou comme props sur `<Checkout>` avec React.

**plan** `string`

ID d'un plan existant, préfixé par `plan_`. Raccourci pour un tableau `items` contenant ce plan et `quantity`. Le plan définit le prix ; aucun montant ne peut être imposé côté client. Transmettez soit `plan`, soit `items`, soit une `checkoutConfiguration`. Défini uniquement à la création : la session est générée à partir de cette valeur, et toute modification ultérieure est refusée.

**quantity** `number`

Le nombre d'unités à acheter. Les plans qui n'autorisent pas les multiples refusent les valeurs supérieures à 1. Défini uniquement à la création : la session est générée avec cette valeur, et toute modification ultérieure est refusée. @default 1

**items** `CheckoutItemInput[]`

Les plans de ce checkout et le nombre d'unités à acheter pour chacun. Chaque article doit appartenir au même vendeur et utiliser des conditions de facturation compatibles ; l'API valide le panier complet et le facture en un seul débit. Transmettez cette option à la place de `plan`, `quantity` ou `checkoutConfiguration`. Défini uniquement à la création : la session est générée à partir de ce panier exact, et toute modification ultérieure est refusée.

**propriétés**

**plan** `string` *required*

ID d'un plan existant, préfixé par `plan_`.

**quantity** `number`

Nombre d'unités à acheter. 1 par défaut ; les plans peuvent interdire les quantités supérieures à 1.

**checkoutConfiguration** `string`

ID d'une configuration de checkout existante, préfixé par `ch_`. L'élément crée la session de checkout à partir de celle-ci : la configuration désigne le plan vendu (ou, en mode `setup`, aucun plan — le checkout enregistre un moyen de paiement et ne débite rien) et initialise ses propres code d'affiliation, métadonnées, redirection et préréglages de moyens de paiement — une option transmise ici à côté prévaut sur la valeur de la configuration, champ par champ. Transmettez `plan` en parallèle uniquement pour définir `quantity` ; il doit s'agir du plan propre à la configuration, qui ne peut jamais être remplacé à l'insu de ses préréglages. Défini uniquement à la création.

**promoCode** `string`

Un code promo à appliquer avant même que l'acheteur ne voie le prix — la réduction figure dans le premier devis, et l'acheteur peut encore la modifier ou la retirer. Transmettez le code porté par un lien marketing : un code expiré ou qui n'a jamais été valide ouvre le checkout au prix plein avec la raison sur la ligne promo, jamais un checkout qui refuse de s'ouvrir. Défini uniquement à la création.

**affiliateCode** `string`

L'affilié auquel ce checkout est attribué. Défini uniquement à la création.

**attribution** `CheckoutAttributionInput`

La provenance de cette vente, pour les rapports du compte : les paramètres de campagne du lien par lequel l'acheteur est arrivé (`utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`, tout autre paramètre `utm_*` sous `utm`, un `trackingLinkId` Whop, un `funnelId` et votre propre `source`). Tout ce qui figure ici est enregistré sur la commande et n'est jamais montré à l'acheteur. Défini uniquement à la création.

**propriétés**

**utmSource** `string`

**utmMedium** `string`

**utmCampaign** `string`

**utmTerm** `string`

**utmContent** `string`

**trackingLinkId** `string`

**funnelId** `string`

**source** `string`

**utm** `Record\<string, string\>`

Tout autre paramètre `utm_*` porté par le lien, indexé par son nom complet (`{ utm_funnel: 'spring' }`). Les clés qui ne commencent pas par `utm_` sont ignorées, et les champs nommés ci-dessus prévalent sur la même clé ici.

**metadata** `Record\<string, string\>`

Vos propres paires clé/valeur à enregistrer sur la commande et à relire sur le paiement — ID de commande, ID de panier, ou tout ce que vous rapprochez. Jusqu'à 40 paires de chaînes. Défini uniquement à la création.

**returnUrl** `string`

L'endroit où l'acheteur arrive après une étape de paiement externe, quel qu'en soit le résultat. L'onglet arrive avec `payment` (l'ID `pay_` ; `setup` avec l'ID `sint_` pour un checkout en mode setup) et `status` (`succeeded`, `failed` ou `canceled`) ajoutés, et vos autres paramètres de requête intacts. Branchez votre logique sur `status` avant d'afficher une page de succès : une étape externe refusée ou abandonnée arrive aussi ici. Exécutez les commandes à partir des webhooks, pas à partir de cette visite. HTTPS uniquement (http pour localhost). Défini uniquement à la création.

**appearance** `Appearance`

Personnalisation visuelle des éléments de ce groupe. Remplace le `WhopElements({ appearance })` global. Modifiez-la en direct avec `update({ appearance })`.

**locale** `WhopElementsLocale`

Langue du texte de l'interface des éléments de ce groupe. Définissez-la sur l'une des langues intégrées à l'application pour remplacer la configuration globale. Toute autre valeur revient à la langue par défaut.

## Événements

Transmettez les callbacks dans les options de création ou dans les props React.

### `onComplete`

Se déclenche une fois par montage lorsque le checkout se termine et que son résultat est confirmé. `result` indique ce qui est confirmé : `payment` (l'acheteur a payé — `paymentId`), `waitlist_entry` (l'acheteur a rejoint une liste d'attente — `entryId`) ou `setup` (un checkout en mode setup a enregistré le moyen de paiement — `setupIntentId`) ; `sessionId` est la session de checkout dans tous les cas. Se déclenche avant toute navigation vers `returnUrl` : c'est donc là que vos propres outils d'analyse ou pixels publicitaires enregistrent l'achat. Exécutez les commandes à partir des webhooks, pas de ce callback : un checkout restauré lors d'un chargement de page ultérieur le déclenche à nouveau pour le même résultat.

**payload** `CheckoutPaymentCompletion | CheckoutWaitlistCompletion | CheckoutSetupCompletion`

**CheckoutPaymentCompletion**

**sessionId** `string` *required*

La session de checkout, préfixée par `chs_`.

**result** `"payment"` *required*

**paymentId** `string` *required*

Le paiement, préfixé par `pay_` — l'ID sous lequel enregistrer l'achat.

**CheckoutWaitlistCompletion**

**sessionId** `string` *required*

La session de checkout, préfixée par `chs_`.

**result** `"waitlist_entry"` *required*

**entryId** `string` *required*

L'entrée de liste d'attente, préfixée par `ent_`.

**CheckoutSetupCompletion**

**sessionId** `string` *required*

La session de checkout, préfixée par `chs_`.

**result** `"setup"` *required*

**setupIntentId** `string` *required*

Le setup enregistré, préfixé par `sint_`.

### `onLoadingChange`

S'exécute lorsque l'état de chargement groupé change. La valeur est `true` tant qu'un élément monté est encore en cours de chargement.

**loading** `boolean`

## Méthodes

Appelez-les sur le handle Checkout obtenu via `whop.checkout.create({ … })` ou `useCheckout()`.

### `update`

Fusionne de nouvelles options de handle dans chaque élément monté. Avec React, modifiez plutôt les props du namespace.

**Paramètres**

**options** `Partial\<CheckoutOptions\>` *required*

### `destroy`

Détruit chaque élément et sous-contrôleur créé par ce handle, supprime le frame du contrôleur et libère ses abonnements. Vous pouvez l'appeler plusieurs fois, mais un handle détruit refuse tout autre appel — créez un nouveau handle pour recommencer. React supprime le groupe automatiquement lorsque le provider est démonté.

## Ressources

Créez ces objets SDK sans monter d'élément. Chacun a sa propre page :

> [card] [CheckoutSession](https://docs.whop.com/fr/elements/latest/checkout/checkoutSession.md)
>
> Session de checkout headless de bas niveau pour une page qui affiche son propre bouton PayPal. `load()` crée la session de checkout à partir de `lineItems` ; `show("paypal", { termsAccepted: true })` envoie l'acheteur vers PayPal — une fenêtre pop-up sur ordinateur, l'onglet entier sur téléphone — et se résout avec le paiement une fois que l'acheteur a approuvé. Avec `paymentMethodOptions.paypal.requestShipping`, PayPal demande une adresse de livraison à l'acheteur et le webhook du compte abonné à `shipping_address.changed` calcule le prix de chacune sur votre serveur pendant que l'acheteur est sur PayPal ; le paiement n'est créé qu'après l'approbation de l'acheteur, à ce prix. Après une redirection pleine page, la promesse ne se résout jamais ; lisez plutôt le résultat dans les paramètres de requête `payment` et `status` de `redirectUrl`.

## Éléments

Les éléments montés par ce groupe. Chacun a sa propre page :

**Alternatives.** Montez-en un seul à la fois. Détruisez-le avant d'en monter un autre :

> [card] [CheckoutElement](https://docs.whop.com/fr/elements/latest/checkout/checkout.md)
>
> L'interface de paiement complète — récapitulatif de commande avec le devis en temps réel, saisie du code promo, devise dans laquelle l'acheteur paie, tout ce que ce checkout doit collecter auprès de l'acheteur, l'interface composée des moyens de paiement et le flux de paiement. Ce qu'il collecte correspond à ce que le vendeur a configuré (e-mail, ses propres questions, un numéro de téléphone, une adresse de livraison pour les biens physiques, une acceptation explicite de ses conditions), affiché ensemble sur un seul écran dans l'ordre choisi — ainsi, un vendeur qui commence à demander quelque chose de nouveau n'a rien à modifier ici. Affiche l'intégralité de l'achat ; le contrôleur de checkout gère la session et l'identifiant. Après un paiement nécessitant une étape externe, cette même interface affiche le résultat signalé par le serveur lorsque l'acheteur revient.

> [card] [ExpressCheckoutElement](https://docs.whop.com/fr/elements/latest/checkout/expressCheckout.md)
>
> Des boutons Apple Pay, Google Pay et PayPal en un clic pour un checkout — le wallet collecte tout ce dont la session a encore besoin (l'e-mail de l'acheteur, une adresse de livraison pour les biens physiques, un numéro de téléphone lorsque le vendeur en collecte un dans Apple Pay et Google Pay, et dans Apple Pay un code promo lorsque le vendeur propose sa saisie) et un seul clic finalise l'achat. Il partage l'emplacement d'entrée du checkout avec l'élément de checkout complet, de sorte qu'un handle monte exactement l'un des deux : ce bouton seul lorsque l'achat est assez simple pour qu'une feuille de paiement le finalise, ou l'interface de checkout complète pour tout le reste. N'affiche que les wallets avec lesquels l'appareil de l'acheteur peut réellement payer — et que la configuration des moyens de paiement du checkout autorise — en utilisant les visuels de boutons fournis, et n'affiche rien lorsqu'aucun wallet n'est disponible. PayPal apparaît lorsque le vendeur l'accepte, s'ouvre dans sa propre fenêtre et enregistre le compte PayPal de l'acheteur avec l'achat, de sorte qu'un renouvellement, un essai gratuit et les débits ultérieurs du vendeur fonctionnent comme avec une carte enregistrée. Les trois wallets nécessitent Apple Pay sur le domaine de la page : les pages first-party whop.com sont pré-approuvées, et tout autre site doit ajouter Apple Pay à son domaine via l'[API Domains](https://docs.whop.com/fr/api-reference/beta/domains/domain) avant que l'un de ces boutons puisse s'y afficher. Proposer Google Pay sur votre propre site est soumis aux conditions d'utilisation de l'API Google Pay. Un checkout que la feuille de paiement ne peut pas honnêtement finaliser — une inscription à une liste d'attente, un transfert, une question de formulaire que seule une page peut poser — est refusé de manière explicite au lieu d'afficher un bouton voué à l'échec.


## Related topics

- [CheckoutSession](https://docs.whop.com/fr/elements/latest/checkout/checkoutSession.md)
- [CheckoutElement](https://docs.whop.com/fr/elements/latest/checkout/checkout.md)
- [API Checkout Configurations](https://docs.whop.com/fr/api-reference/checkout-configurations/checkout-configuration.md)
