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

# Payments

> Encaissez un paiement à partir d'un ID `plan_` ou d'une devise et d'un montant inline, ou enregistrez un moyen de paiement sans débit avec `mode: "setup"`. Montez PaymentElement, CardElement ou CardFields, puis appelez `payments.createConfirmationToken` avec les informations de facturation. Les sélections de wallet ouvrent automatiquement leur feuille de paiement. Lorsque le compte propose la liaison bancaire dans la page (`bank_debit.bank_connection` sur son type de moyen de paiement par compte bancaire), la sélection d'un compte bancaire ouvre aussi Plaid Link sur la page. Si l'acheteur ferme l'un ou l'autre, l'appel est rejeté avec `payment_request_cancelled`, que votre handler de paiement doit traiter comme une annulation. Confirmez le jeton côté serveur, puis transmettez le `client_secret` du paiement ou du setup intent à `handleNextAction` pour toute étape en attente.

> [!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, Payments } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

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

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

## Options

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

> [!NOTE]
>
> Transmettez exactement l'une de ces combinaisons :
>
> * `accountId` et `plan`
> * `accountId`, `currency` et `amount`
> * `accountId`, `mode: "setup"` et `currency`
> * aucun de `plan`, `currency`, `amount` ou `mode`

**accountId** `string`

ID du compte, préfixé par `biz_`. Ne l'omettez que pour appeler des méthodes statiques sans surface de compte.

**mode** `"payment" | "setup"`

Mode de montage, `payment` par défaut. `setup` enregistre un moyen de paiement sans rien débiter, ni maintenant ni plus tard : seuls les moyens pouvant être enregistrés sont proposés et les limites de montant ne s'appliquent pas. Confirmez avec `createConfirmationToken()`, puis créez le setup intent côté serveur.

**plan** `string`

ID du plan, préfixé par `plan_`. Il est résolu côté client en devise, montant et configuration des moyens de paiement. Transmettez un plan ou une devise et un montant inline, jamais les deux.

**offerAmounts** `object`

Totaux `feeInclusive` et `feeFree` en unités mineures, utilisés pour filtrer les moyens de paiement lorsque le checkout recalcule `amount` pour un moyen sans frais comme le BNPL. Chaque moyen est comparé à son total correspondant, ce qui évite que le moyen sans frais sélectionné disparaisse. S'ils sont omis, `amount` filtre tous les moyens.

**propriétés**

**feeInclusive** `number` *required*

**feeFree** `number` *required*

**returnUrl** `string`

URL de retour pour les étapes bancaires ou 3DS hors site. Par défaut, la page de montage. L'acheteur y arrive quel que soit le résultat, avec `payment` (ou `setup`), `status` (`succeeded`, `failed`, `canceled` ou un statut encore en attente comme `processing`) et `client_secret` ajoutés : vérifiez donc `status` avant d'afficher une page de succès.

**setupFutureUsage** `"off_session" | "on_session"`

Un setup enregistre le moyen de paiement pour un usage `off_session`, le seul usage qu'un setup accepte.

**previewWalletAvailability** `WalletAvailability`

Remplacement de la disponibilité des wallets pour des aperçus déterministes. Les checkouts réels interrogent l'hôte.

**propriétés**

**applePay** `boolean` *required*

**googlePay** `boolean` *required*

**payPal** `boolean`

**order** `("apple_pay" | "google_pay" | "paypal_express")[]`

Les wallets classés selon la feuille de paiement native de ce navigateur — Apple Pay en premier sur WebKit, Google Pay en premier partout ailleurs, PayPal en dernier — pour que les boutons express puissent s'empiler du meilleur au moins bon. Absent lorsque la disponibilité est déclarée par l'intégrateur (aperçus) et sur les échanges antérieurs à ce champ. Une union inline, et non le WalletSheetType de payment-request : ce module importe déjà celui-ci.

**wallets** `object`

Les détails de chaque wallet disponible, indexés par type de wallet. Absent lorsque la disponibilité est déclarée par l'intégrateur (aperçus).

**propriétés**

**apple\_pay** `WalletDetails`

**propriétés**

**button** `WalletButtonArt`

Le visuel de bouton officiel du wallet. Absent lorsqu'aucun n'est publié.

**propriétés**

**light** `object` *required*

Pour les pages claires.

**propriétés**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

Pour les pages sombres.

**propriétés**

**color** `string` *required*

**image** `string` *required*

**google\_pay** `WalletDetails`

**propriétés**

**button** `WalletButtonArt`

Le visuel de bouton officiel du wallet. Absent lorsqu'aucun n'est publié.

**propriétés**

**light** `object` *required*

Pour les pages claires.

**propriétés**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

Pour les pages sombres.

**propriétés**

**color** `string` *required*

**image** `string` *required*

**paypal\_express** `WalletDetails`

**propriétés**

**button** `WalletButtonArt`

Le visuel de bouton officiel du wallet. Absent lorsqu'aucun n'est publié.

**propriétés**

**light** `object` *required*

Pour les pages claires.

**propriétés**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

Pour les pages sombres.

**propriétés**

**color** `string` *required*

**image** `string` *required*

**currency** `string`

Code de devise ISO 4217 à trois lettres en minuscules. Il filtre la matrice des moyens de paiement.

**amount** `number`

Montant du paiement en unités mineures. Les moyens dont les limites l'excluent ne sont pas proposés.

**paymentMethodConfiguration** `object`

Filtres des moyens de paiement du compte au format `enabled`, `disabled` et `include_platform_defaults` de l'API. `disabled` retire des types, `enabled` rétablit des types proposés, et `include_platform_defaults: false` ne conserve que les types activés. Les plans fournissent leur propre configuration.

**propriétés**

**enabled** `string[]`

**disabled** `string[]`

**include\_platform\_defaults** `boolean`

**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 des textes d'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 se rabat sur la langue par défaut.

## Événements

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

### `onLoadingChange`

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

**loading** `boolean`

## Méthodes

Appelez-les sur le handle Payments obtenu avec `whop.payments.create({ … })` ou `usePayments()`.

### `createConfirmationToken`

Crée un jeton de confirmation pour le moyen sélectionné depuis votre bouton de paiement. Transmettez les informations de facturation du checkout. Elles doivent inclure `email`. Fournissez `phone` pour les moyens qui l'exigent lorsque la collecte des informations de facturation est désactivée. Les cartes nécessitent aussi `name` et une adresse contenant `line1` et `country`. Les sélections de wallet ouvrent leur feuille de paiement pendant l'interaction avec le bouton de paiement. Lorsque le compte propose la liaison bancaire dans la page (`bank_debit.bank_connection` sur son type de moyen de paiement par compte bancaire), la sélection d'un compte bancaire ouvre aussi Plaid Link à ce moment-là, et l'appel se résout une fois que l'acheteur a lié un compte. Cela nécessite une page whop.com ou un domaine prêt pour Apple Pay via l'[API Domains](https://docs.whop.com/fr/api-reference/beta/domains/domain), ainsi qu'une Content Security Policy qui autorise les hôtes Plaid renvoyés par `contentSecurityPolicy()`. Sinon, l'acheteur lie le compte après l'envoi. Si l'acheteur ferme la feuille ou Link, l'appel est rejeté avec `payment_request_cancelled` : traitez-le comme une annulation, et non comme une erreur de paiement, et laissez l'acheteur payer à nouveau. Confirmez le `confirmationToken` renvoyé côté serveur, puis appelez `WhopElements.payments.handleNextAction(…)`. S'exécute sur votre page (côté hôte), et non dans l'iframe du contrôleur.

**Paramètres**

**input** `object` *required*

**propriétés**

**billingDetails** `object`

**propriétés**

**email** `string`

**name** `string`

**phone** `string`

**address** `object`

**propriétés**

**country** `string`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**Renvoie** `Promise<object>`

**confirmationToken** `string` *required*

**type** `string` *required*

### `update`

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

**Paramètres**

**options** `Partial\<PaymentsOptions\>` *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é.

## Méthodes statiques

Appelez-les sans montage : `whop.payments.<method>(…)` en JavaScript vanilla ou `useWhop().payments.<method>(…)` avec React.

### `handleNextAction`

Termine l'étape en attente d'un paiement confirmé sans monter d'élément. `clientSecret` identifie le paiement. Vous n'avez pas besoin d'ID de paiement. Les étapes inline s'ouvrent dans une boîte de dialogue et se résolvent avec `redirected: false`. Fermer la boîte de dialogue renvoie le statut actuel du paiement, qui peut rester en attente. Les étapes pleine page redirigent avec `redirected: true` vers `return_url`, ou vers un reçu hébergé lorsque le paiement n'a pas d'URL de retour. Dans une iframe, elles naviguent dans l'onglet de premier niveau. Si la page d'intégration refuse cette navigation, elles sont rejetées avec le code `TAB_NAVIGATION_BLOCKED`, et le paiement reste en attente. Définissez `returnUrl` pour mettre à jour la destination avant l'affichage. Un échec de mise à jour entraîne un rejet avant l'exécution de toute étape. Les étapes inline ne naviguent jamais vers cette URL. Un paiement dont le débit est encore en cours de décision est interrogé jusqu'à ce qu'une étape apparaisse ou qu'il soit réglé ; un paiement décidé sans étape se résout immédiatement.

**Paramètres**

**input** `object` *required*

**propriétés**

**clientSecret** `string` *required*

**returnUrl** `string`

**pollIntervalMs** `number`

**Renvoie** `Promise<object>`

**status** `string` *required*

**redirected** `boolean` *required*

**lastPaymentError** `object | null` *required*

**propriétés**

**code** `string | null`

**decline\_code** `string | null`

**message** `string | null`

## Ressources

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

> [card] [PaymentRequest](https://docs.whop.com/fr/elements/latest/payments/paymentRequest.md)
>
> Feuille de paiement Apple Pay, Google Pay ou PayPal de bas niveau pour les boutons personnalisés, le checkout express et les callbacks de livraison. Les tuiles de wallet automatisent ce flux via `payments.createConfirmationToken`. Attendez `canMakePayment()` pour vérifier la disponibilité et préparer le wallet, puis appelez `show(type)` de manière synchrone dans le handler d'interaction utilisateur. Le `ctok` résolu est un jeton de confirmation préfixé par `ctok_`. Confirmez-le côté serveur comme un jeton généré par un élément. Un jeton PayPal débite au maximum le total que PayPal a affiché à l'acheteur.

## Content Security Policy

Une partie du travail de ce groupe s'exécute sur votre page, pas dans un frame. Une page dotée d'une Content Security Policy a besoin de ces sources. `contentSecurityPolicy()` de `@whop/elements` renvoie toutes les sources de ce tableau. La source sandbox s'applique avec `environment: "sandbox"`.

| Besoin | Directive | Source en production | Source en sandbox |
| - | - | - | - |
| Script de Plaid Link | `script-src` | `https://cdn.plaid.com` | Identique |
| ↳ Frame de Plaid Link, ouvert par le script de Plaid | `frame-src` | `https://cdn.plaid.com` | Identique |
| ↳ API de Plaid, appelée par le script de Plaid | `connect-src` | `https://production.plaid.com` | `https://sandbox.plaid.com` |

## Éléments

Les éléments que monte ce groupe. Chacun a sa propre page :

> [card] [AddressElement](https://docs.whop.com/fr/elements/latest/payments/address.md)
>
> Collecte une adresse de facturation ou de livraison. Les champs, leur ordre et leur validation suivent le pays sélectionné. Inclut l'autocomplétion de la rue (en plein écran sur téléphone) et des méthodes pour lire ou valider l'adresse.

> [card] [EmailElement](https://docs.whop.com/fr/elements/latest/payments/email.md)
>
> Collecte l'e-mail de l'acheteur et le transmet à `payments.createConfirmationToken()` tant qu'il est monté. Un `billingDetails.email` explicite est prioritaire. Un compte Whop correspondant affiche une connexion facultative avec vérification par code, ou avec la passkey du compte lorsqu'il en possède une. Une connexion réussie débloque les moyens de paiement enregistrés dans l'élément de paiement. Les acheteurs peuvent continuer en tant qu'invités.

> [card] [TaxIdElement](https://docs.whop.com/fr/elements/latest/payments/taxId.md)
>
> Collecte un numéro d'identification fiscale d'entreprise accepté par l'API. Les libellés utilisent les noms présentés à l'acheteur. Le placeholder correspond au format sélectionné. `country` présélectionne un type. `onChange` émet les paires validées. L'hôte fournit les erreurs de validation de l'API.

> [card] [BrandingElement](https://docs.whop.com/fr/elements/latest/payments/branding.md)
>
> **Obligatoire — les autres éléments, sauf `AddressElement`, `EmailElement` et `TaxIdElement`, l'attendent.** La mention de marchand officiel (merchant of record) de Whop : l'acceptation par l'acheteur des conditions d'utilisation acheteur et de la politique de confidentialité de Whop, avec le logotype Whop. Obligatoire — les éléments de paiement, de carte et de champs de carte restent dans leur état de chargement tant qu'il n'est pas monté, et les paiements ne peuvent pas être confirmés sans lui.

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

> [card] [PaymentElement](https://docs.whop.com/fr/elements/latest/payments/payment.md)
>
> Affiche les moyens de paiement disponibles et collecte les champs requis et les mentions du moyen sélectionné. Utilisez `change` pour activer votre bouton de paiement. Dans son handler d'activation, appelez `payments.createConfirmationToken()`. Confirmez le jeton côté serveur, puis transmettez toute étape en attente à `payments.handleNextAction(…)`. Utilisez `addressChange` pour les mises à jour dépendant de l'adresse.

> [card] [CardElement](https://docs.whop.com/fr/elements/latest/payments/card.md)
>
> Champs préagencés pour le numéro de carte, la date d'expiration et le code de sécurité. Créez-le avec `payments.create("card")`, activez votre bouton de paiement depuis `onChange` et confirmez avec `payments.createConfirmationToken()`. Les numéros de carte restent dans des champs hébergés isolés PCI. `layout` prend en charge `stacked` (par défaut) et `compact`.

> [card] [CardFields](https://docs.whop.com/fr/elements/latest/payments/cardFields)
>
> Trois champs de carte isolés PCI, montables séparément, pour des mises en page personnalisées : numéro, date d'expiration et code de sécurité. Créez-le avec `payments.create("cardFields")`, placez chaque champ, activez votre bouton de paiement depuis `onChange` et confirmez avec `payments.createConfirmationToken()`. Les numéros de carte restent dans des champs hébergés. *(sous-contrôleur, 3 éléments)*


## Related topics

- [API Payments](https://docs.whop.com/fr/api-reference/payments/payment.md)
- [Retrieve Payment](https://docs.whop.com/fr/api-reference/payments/retrieve-payment.md)
- [Retry Payment](https://docs.whop.com/fr/api-reference/payments/retry-payment.md)
