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

# Premiers pas avec Elements

> Installez Whop Elements et montez votre premier élément en React, JavaScript, Swift ou React Native.

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

Whop Elements sont des composants d'interface hébergés et personnalisables que vous intégrez à votre propre site. Chaque élément s'affiche dans un frame isolé servi depuis le CDN de Whop. Vous installez un package léger et entièrement typé, et le code des éléments se met à jour de lui-même.

Whop Elements sont des composants d'interface personnalisables que vous pouvez importer dans votre application iOS. Ils sont distribués sous la forme d'un unique package Swift SPM. Chacun est une simple vue SwiftUI qui récupère ses propres données et gère son propre état : un écran de solde se résume donc à quelques vues dans un `VStack` au lieu d'une couche réseau et d'un view model. Ajoutez le package, indiquez au SDK comment récupérer un jeton d'accès, et placez les éléments dans votre hiérarchie de vues.

Whop Elements sont des composants d'interface personnalisables que vous pouvez intégrer à une application React Native. Ce sont de vrais composants React Native, pas des web views : les tuiles de moyens de paiement, le formulaire d'adresse et les champs de carte sont tous des saisies natives, et Apple Pay et Google Pay ouvrent la feuille de paiement propre à la plateforme. Installez le package, indiquez au SDK comment récupérer un jeton d'accès, et montez les éléments.

## Installation

Ajoutez le package à votre `Package.swift` (ou **File → Add Package Dependencies** dans Xcode) :

Installez le SDK :

```bash React theme={null}
npm install @whop/elements-react @whop/elements
```

```bash React Native theme={null}
npm install @whop/elements-react-native
```

```bash JavaScript theme={null}
npm install @whop/elements
```

```swift Swift theme={null}
dependencies: [
    .package(url: "https://github.com/whopio/whopsdk-elements-swift.git", from: "0.1.12")
]
```

## Prérequis

| | |
| - | - |
| React | `^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0`, pour `@whop/elements-react`. |
| Content Security Policy | Votre politique doit inclure toutes les sources du [tableau Content Security Policy](#content-security-policy) ci-dessous. |

### Content Security Policy

| Besoin | Directive | Source en production | Source en sandbox |
| - | - | - | - |
| Frames des éléments | `frame-src` | `https://cdn.whop.com` | Identique |
| La balise script, si vous la chargez | `script-src` | `https://cdn.whop.com` | Identique |
| L'API Whop | `connect-src` | `https://api.whop.com` | `https://sandbox-api.whop.com` |
| Le pixel Whop | `script-src` | `https://t.whop.tw` | Aucune |
| Le pixel Whop | `connect-src` | `https://t.whop.tw` | Aucune |
| Apple Pay, Google Pay et PayPal | `frame-src` | `https://checkout.paypal.com` `https://assets.braintreegateway.com` `https://www.paypal.com` | `https://checkout.paypal.com` `https://assets.braintreegateway.com` `https://www.sandbox.paypal.com` |
| Apple Pay, Google Pay et PayPal | `script-src` | `https://pay.google.com` `https://applepay.cdn-apple.com` `https://js.braintreegateway.com` `https://assets.braintreegateway.com` `https://www.paypal.com` `https://c.paypal.com` | `https://pay.google.com` `https://applepay.cdn-apple.com` `https://js.braintreegateway.com` `https://assets.braintreegateway.com` `https://www.sandbox.paypal.com` `https://c.paypal.com` |
| Apple Pay, Google Pay et PayPal | `connect-src` | `https://pay.google.com` `https://google.com` `https://account.google.com` `https://www.google.com` `https://api.basistheory.com` `https://payments.braintree-api.com` `https://api.braintreegateway.com` `https://api-m.paypal.com` `https://www.paypal.com` | `https://pay.google.com` `https://google.com` `https://account.google.com` `https://www.google.com` `https://api.basistheory.com` `https://payments.sandbox.braintree-api.com` `https://api.sandbox.braintreegateway.com` `https://api-m.sandbox.paypal.com` `https://www.sandbox.paypal.com` |
| Apple Pay, Google Pay et PayPal | `img-src` | `https://www.paypalobjects.com` | Identique |
| Liaison de compte bancaire Plaid | `frame-src` | `https://cdn.plaid.com` | Identique |
| Liaison de compte bancaire Plaid | `script-src` | `https://cdn.plaid.com` | Identique |
| Liaison de compte bancaire Plaid | `connect-src` | `https://production.plaid.com` | `https://sandbox.plaid.com` |

`contentSecurityPolicy()` de `@whop/elements` renvoie toutes les sources de ce tableau, pour l'environnement que vous transmettez. Les lignes concernant le travail côté page s'exécutent sur votre page, pas dans un frame. Les scripts que les éléments chargent pour Apple Pay, Google Pay et PayPal et pour la liaison de compte bancaire Plaid proviennent d'autres entreprises et peuvent charger des ressources au-delà de ces lignes. Consultez aussi les recommandations Content Security Policy de chaque fournisseur.

> [!WARNING]
>
> Les éléments s'affichent dans des frames servis depuis `cdn.whop.com`. Une partie de leur travail s'exécute sur votre page et appelle `api.whop.com` depuis celle-ci, comme Apple Pay, Google Pay et PayPal et la liaison de compte bancaire Plaid. Si votre CSP bloque l'une de ces origines, vous obtenez un espace vide à la place de l'élément ou une requête en échec, et l'erreur n'apparaît que dans la console du navigateur.

> [!NOTE]
>
> Un élément modal assombrit votre page en arrière-plan avec un style inline. Un `style-src` qui n'autorise pas les styles inline laisse la page non assombrie, mais la modale fonctionne toujours.

## Avant de commencer

Il vous faut deux choses :

1. **Un `accountId`.** Un ID de compte, préfixé par `biz_`, ou un ID d'utilisateur, préfixé par `user_`, pour les propres données de l'utilisateur. Les interfaces de paiement acceptent plutôt un plan ou un montant, et chaque page d'élément indique ce dont il a besoin.
2. **Un endpoint serveur qui crée un jeton d'accès**, limité aux éléments que vous montez.

> [!WARNING]
>
> Ne placez jamais une clé API Whop dans du code navigateur. Elle permet de créer des jetons, donc toute personne qui ouvre les outils de développement du navigateur peut lire le compte. Créez le jeton sur votre serveur et n'envoyez que le jeton.

Votre serveur appelle [Create Access Token](https://docs.whop.com/fr/api-reference/access-tokens/create-access-token.md) avec le compte et les scopes dont les éléments ont besoin :

```http theme={null}
POST https://api.whop.com/api/v1/access_tokens
Authorization: Bearer <api_key>
Content-Type: application/json

{ "company_id": "biz_xxxxxxxx", "scoped_actions": ["company:balance:read"] }
```

## Prérequis

| | |
| - | - |
| Plateforme | iOS 18.0+ |
| Chaîne d'outils | Swift 6.0 |
| Installation | Swift Package Manager |

## Avant de commencer

Il vous faut deux choses :

1. **Un `accountId`.** Un ID de compte, préfixé par `biz_`, ou un ID d'utilisateur, préfixé par `user_`, pour le propre solde de l'utilisateur.
2. **Un endpoint serveur qui crée un jeton d'accès** pour le compte. N'embarquez jamais une clé API Whop dans l'application. Elle permet de créer des jetons, donc toute personne qui l'extrait peut lire le compte. Créez le jeton sur votre serveur et ne renvoyez que celui-ci.

Un tag `user_…` lit les propres données de l'utilisateur, il utilise donc l'OAuth utilisateur (`WhopSDK.configureWithOAuth`) au lieu d'un jeton. Les vues de chat aussi.

Votre serveur appelle [Create Access Token](https://docs.whop.com/fr/api-reference/access-tokens/create-access-token.md) avec le compte et le scope dont les éléments ont besoin :

```http theme={null}
POST https://api.whop.com/api/v1/access_tokens
Authorization: Bearer <api_key>
Content-Type: application/json

{ "company_id": "biz_xxxxxxxx", "scoped_actions": ["company:balance:read"] }
```

## Prérequis

| | |
| - | - |
| React Native | `0.87+` avec Swift Package Manager, `0.86+` avec CocoaPods. New Architecture (Fabric) activée |
| React | `19.2.3+` |
| iOS | 15.1+ |
| Android | `minSdk 24`, `compileSdk 37` |

> [!NOTE]
>
> **Les deux gestionnaires de dépendances iOS fonctionnent.** Le package fournit à la fois un `ios/Package.swift` et un podspec, et la chaîne d'outils choisit l'un des deux. L'autolinker Swift Package Manager de React Native privilégie le `Package.swift`, donc une application déjà sur SPM n'est pas affectée par le podspec. Une application sur CocoaPods, ce qui inclut aujourd'hui toutes les applications Expo, se lie via le podspec et n'a besoin de rien d'autre. La version minimale de React Native est plus élevée avec SPM car `Package.swift` lie deux XCFrameworks header-only apparus pour la première fois dans la 0.87.

> [!NOTE]
>
> Le code natif est du Swift et du Kotlin générés via React Native Codegen : rien ici ne vous demande de modifier à la main de l'Objective-C ou du Java, et il n'y a aucune dépendance native peer à installer.

## Avant de commencer

Il vous faut deux choses :

1. **Un `accountId`.** Un ID d'entreprise, préfixé par `biz_`.
2. **Un endpoint serveur qui génère un jeton d'accès** pour ce compte. N'embarquez jamais une clé API Whop dans l'application : elle permet de créer des jetons, donc toute personne qui l'extrait peut agir en tant que compte. Générez le jeton sur votre serveur et ne renvoyez que celui-ci.

Votre serveur appelle [Create Access Token](https://docs.whop.com/fr/api-reference/access-tokens/create-access-token.md) et renvoie le résultat à `getToken`.

## Monter votre premier élément

Une application complète. `configure` s'exécute une fois au lancement, et les éléments affichent un indicateur de chargement jusqu'à ce qu'il aboutisse, donc rien n'entre en concurrence avec lui :

Un checkout complet. `<WhopElements>` contient le résolveur de jeton, `<Payments>` contient le débit, et les éléments entre les deux le collectent :

```tsx React theme={null}
import { WhopElements, Payments, PaymentElement, AddressElement, CardElement, EmailElement, TaxIdElement, BrandingElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <PaymentElement />
        <AddressElement />
        <CardElement />
        <EmailElement />
        <TaxIdElement />
        <BrandingElement />
      </Payments>
    </WhopElements>
  );
}
```

```tsx React Native theme={null}
import { useRef, useState } from 'react';
import { Button, ScrollView } from 'react-native';
import {
  AddressElement,
  BrandingElement,
  EmailElement,
  PaymentElement,
  Payments,
  WhopElements,
  type PaymentsHandle,
} from '@whop/elements-react-native';

export function Checkout() {
  const payments = useRef<PaymentsHandle | null>(null);
  const [ready, setReady] = useState(false);

  return (
    // Called again before every request, so fetch rather than cache.
    <WhopElements getToken={() => myBackend.whopAccessToken()}>
      <Payments ref={payments} accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
        <ScrollView>
          <EmailElement />
          <AddressElement />
          <PaymentElement onChange={(p) => setReady(p.complete)} />
          <BrandingElement />
        </ScrollView>
        <Button
          title="Pay"
          disabled={!ready}
          onPress={async () => {
            const token = await payments.current!.createConfirmationToken();
            // Confirm server-side, then hand the payment's client_secret back:
            // await payments.current!.handleNextAction({ clientSecret });
            console.log(token.confirmationToken);
          }}
        />
      </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 */ });
  payments.create('payment').mount('#payments-payment');
  payments.create('address').mount('#payments-address');
  payments.create('card').mount('#payments-card');
  payments.create('email').mount('#payments-email');
  payments.create('taxId').mount('#payments-taxId');
  payments.create('branding').mount('#payments-branding');
</script>
```

```swift Swift theme={null}
import SwiftUI
import WhopElements

/// The SDK calls this again before the token expires, so fetch rather than cache.
final class WalletTokenProvider: WhopTokenProvider {
    func getToken() async -> WhopTokenResponse {
        WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
    }
}

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            WalletScreen()
                .task { await WhopSDK.configure(tokenProvider: WalletTokenProvider()) }
        }
    }
}

struct WalletScreen: View {
    var body: some View {
        ScrollView {
            VStack(spacing: 24) {
                BalanceElement(accountId: "biz_xxxxxxxx")
                ListElement(accountId: "biz_xxxxxxxx")
            }
            .padding()
        }
    }
}
```

Vous préférez npm à la balise script ? `loadWhop()` injecte le même script hébergé et résout le constructeur global :

```ts theme={null}
import { loadWhop } from "@whop/elements";

const whop = (await loadWhop())({ locale: "en" });
const payments = whop.payments.create({ /* options */ });
```

## Authentification

Transmettez un `accessToken` lorsque vous créez le handle. **Utilisez un seul jeton pour tout le handle, pas un par élément.** Le handle envoie ce jeton à chaque élément qu'il contient, donc demandez tous les scopes dont vous avez besoin sur ce seul jeton. Chaque page d'élément liste les scopes qu'il lit.

```tsx React theme={null}
<Ads accountId="biz_xxxxxxxx" accessToken={token}>
  {/* elements */}
</Ads>
```

```ts JavaScript theme={null}
const ads = whop.ads.create({ accountId: "biz_xxxxxxxx", accessToken });
```

Le jeton est une valeur que vous définissez, pas un callback appelé par le SDK. Définissez-en un nouveau avant son expiration :

```ts theme={null}
ads.update({ accessToken: await createAccessToken() });
```

> [!NOTE]
>
> Si vous omettez `accessToken`, les requêtes utilisent à la place le cookie de session de l'utilisateur. Cela fonctionne **uniquement sur whop.com**. L'API n'envoie pas `Access-Control-Allow-Credentials` sur les requêtes preflight cross-origin, donc une page sur votre propre domaine n'a pas de session de repli et doit transmettre un jeton.

## Configuration globale

Tout ce que vous transmettez à la construction s'applique à chaque groupe d'éléments créé à partir de cette instance (les options propres à un handle peuvent prendre le dessus pour chaque groupe) :

**appearance** `Appearance`

Personnalisation visuelle de chaque élément — `theme` (clair/sombre + palettes), `variables` (propriétés CSS personnalisées) et `classes` (déclarations de style par partie). Le schéma de couleurs est appliqué avant le premier affichage d'un élément, donc les pages sombres ne clignotent jamais en clair. Consultez [Apparence](https://docs.whop.com/fr/elements/latest/appearance.md).

**locale** `string`

Langue du texte de l'interface des éléments — l'une des langues intégrées à l'application ; toute autre valeur revient à la langue par défaut. Par défaut : `"en"`.

L'une des valeurs `"en"`, `"es"`, `"zh"`, `"nl"`, `"pt"`, `"de"`, `"hu"`, `"it"`, `"fr"`, `"ja"`, `"pl"` ou `"tr"`.

**environment** `"production" | "sandbox"`

L'environnement de l'API Whop avec lequel communiquent les éléments — `"sandbox"` cible l'API sandbox (données de test ; aucun argent réel ne circule). Choisir un environnement est le seul moyen de changer l'endroit où les éléments envoient ce que saisit un acheteur, et les deux environnements appartiennent à Whop. L'environnement sandbox n'est pas encore disponible pour tous. Par défaut : `"production"`.

**toasts** `boolean`

Indique si les éléments peuvent afficher des notifications toast sur votre page — de brefs messages d'état (« Payment method added », « Payment failed ») affichés dans le coin inférieur droit. Définissez `false` pour les désactiver entièrement. Par défaut : `true`.

**skipPixel** `boolean`

Ignore le pixel Whop. Par défaut, les éléments chargent le pixel publicitaire Whop sur une page qui ne l'exécute pas déjà, limité au compte pour lequel ils travaillent (l'`accountId` d'un groupe d'éléments, ou le vendeur du plan d'un checkout), et associent les analytics des éléments à l'ID visiteur du pixel, un lien d'identité ponctuel qui permet de rapprocher l'activité des éléments de vos données d'attribution publicitaire dans le graphe d'identité de Whop. Définissez `true` pour ne faire ni l'un ni l'autre. Les analytics d'utilisation elles-mêmes ne sont pas affectées (désactivez-les par handle avec `analytics: false`). Par défaut : `false`.

```ts theme={null}
const whop = WhopElements({
  locale: 'es',
  appearance: { theme: { appearance: 'dark', accentColor: 'blue' } }
});
```

Avec React, le même objet passe par `<WhopElements appearance={…} locale={…}>`.

L'option globale `toasts` est active sur cette page — le bouton ci-dessous en envoie un via le même canal que celui utilisé par les éléments, avec le thème de l'`appearance` de cette page :

## Ce que gèrent les éléments, et ce qui vous revient

Chaque élément récupère ses propres données et affiche ses propres états de chargement, vide et d'erreur.

Vous gérez **la navigation et le stockage**. Les éléments signalent les sélections et les résultats sous forme d'événements, et n'écrivent jamais dans votre base de données.

L'exception est un flux qui quitte la page. Lorsqu'un élément accepte une `returnUrl`, il y redirige l'onglet, et l'acheteur peut donc se retrouver hors de votre page. L'acheteur y arrive après une étape externe échouée ou abandonnée aussi bien qu'après une étape réussie, avec `status` (`succeeded`, `failed` ou `canceled`) et l'ID de la tentative ajoutés à l'URL, donc la page de `returnUrl` doit lire `status` avant d'afficher un message de succès. Exécutez les commandes à partir des webhooks plutôt que d'un callback navigateur.

Les éléments s'exécutent dans des frames, donc seules les valeurs sérialisables franchissent la frontière. Il n'y a pas de DOM partagé, et l'identité des objets n'est pas préservée.

## Dépannage

| Ce que vous voyez | Pourquoi |
| - | - |
| Un espace vide à la place de l'élément | Votre CSP bloque `cdn.whop.com`. Ajoutez-le à `frame-src`, et à `script-src` si vous utilisez la balise script. |
| La console affiche une violation de Content Security Policy | Il manque une source à votre politique. Comparez-la avec le tableau des prérequis. `contentSecurityPolicy()` renvoie toutes les sources de ce tableau, et le script d'une autre entreprise peut en nécessiter d'autres. |
| `mount()` ne fait rien | Le sélecteur ne correspond à aucun nœud. La cible doit déjà être dans le DOM. |
| L'élément se charge mais reste vide | Il manque au jeton un scope que cet élément lit. Vérifiez les scopes listés sur la page de l'élément. |
| Les requêtes échouent sur votre propre domaine | Aucun jeton n'a été transmis. Le repli sur la session ne fonctionne que sur whop.com. |
| Cela fonctionnait, puis s'est arrêté | Le jeton a expiré. Créez-en un nouveau et transmettez-le avec `update({ accessToken })`. |

## Éléments disponibles

> [card] [Payments](https://docs.whop.com/fr/elements/latest/payments/overview)
>
> 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"`.

> [card] [Verifications](https://docs.whop.com/fr/elements/latest/verifications/overview)
>
> Collecte et vérifie les informations d'identité d'un compte.

> [card] [Checkout](https://docs.whop.com/fr/elements/latest/checkout/overview)
>
> 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.

> [card] [Ads](https://docs.whop.com/fr/elements/latest/ads/overview)
>
> Un compte publicitaire.

> [card] [Tracking](https://docs.whop.com/fr/elements/latest/tracking/overview)
>
> L'audience suivie d'un compte : toutes les personnes vues par son pixel, et tous les événements qu'elles ont effectués.

> [card] [Wallet](https://docs.whop.com/fr/elements/latest/wallet/overview)
>
> Pilote les interfaces financières d'un compte.

> [card] [Websites](https://docs.whop.com/fr/elements/latest/websites/overview)
>
> Les sites web d'un compte : chaque site créé sur whop.site ainsi que chaque domaine signalé par le Whop Pixel, avec le trafic et le revenu attribué par domaine.

> [card] [Dashboard](https://docs.whop.com/fr/elements/latest/dashboard/overview)
>
> Les interfaces du tableau de bord propres à un compte, intégrées à votre site.

> [card] [Delivery](https://docs.whop.com/fr/elements/latest/delivery/overview)
>
> Suivi des livraisons pour les clients d'une entreprise.

> [card] [Chat](https://docs.whop.com/fr/elements/latest/chat/overview)
>
> Chat en temps réel avec une liste de canaux et une recherche de messages.

## Étapes suivantes

* [Apparence](https://docs.whop.com/fr/elements/latest/appearance.md) : thèmes, variables CSS et restylage par partie
* [Create Access Token](https://docs.whop.com/fr/api-reference/access-tokens/create-access-token.md) : l'endpoint à partir duquel votre serveur génère les jetons

## Authentification

`getToken()` est votre unique point d'intégration, et le SDK l'appelle **à nouveau avant l'expiration du jeton** : renvoyez donc un nouveau jeton à chaque fois plutôt que d'en mettre un en cache :

```swift theme={null}
final class WalletTokenProvider: WhopTokenProvider {
    func getToken() async -> WhopTokenResponse {
        // your backend, not the Whop API directly
        WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
    }
}
```

Configurez une seule fois, n'importe où au-dessus des éléments. `WhopSDK` est global au processus, donc un second appel n'est nécessaire que lorsque le compte change :

```swift theme={null}
await WhopSDK.configure(tokenProvider: WalletTokenProvider())
```

Le chat et les DM authentifient l'**utilisateur** plutôt qu'un compte, via OAuth : `WhopSDK.configureWithOAuth(appId:)`.

## Thèmes

`.whopTheme(_:)` se propage dans l'environnement SwiftUI, donc un seul appel applique le thème à chaque élément situé en dessous. Six rôles, chacun étant un `WhopTint` :

```swift theme={null}
ListElement(accountId: "biz_xxxxxxxx")
    .whopTheme(WhopTheme(accent: .blue, danger: .red, success: .green))
```

Les valeurs par défaut sont `accent: .blue`, `neutral: .gray`, `danger: .red`, `info: .sky`, `success: .green`, `warning: .amber`. `WhopTheme.default` regroupe les six. Les vues suivent d'elles-mêmes l'apparence claire/sombre du système.

## Ce que gèrent les éléments, et ce qui vous revient

Chaque vue récupère ses propres données et affiche ses propres états de chargement, vide et d'erreur, y compris une nouvelle tentative. La **navigation** vous revient : les callbacks de sélection vous transmettent une valeur et n'affichent jamais d'écran.

```swift theme={null}
ListElement(accountId: account) { balance in
    path.append(Route.asset(balance.symbol))   // your router, your screen
}
```

## Dépannage

| Ce que vous voyez | Pourquoi |
| - | - |
| `Authentication failed` | Le jeton est manquant, expiré, ou il s'agit d'une **clé API** plutôt que d'un jeton d'accès. `getToken()` doit renvoyer un jeton généré par [Create Access Token](https://docs.whop.com/fr/api-reference/access-tokens/create-access-token.md). |
| Une vue reste vide | Le jeton est valide mais n'a pas le scope pour cette lecture. Les soldes nécessitent `company:balance:read`. |
| `Couldn't load this account` | L'`accountId` ne fait pas partie de ceux que ce jeton peut lire. |
| Un graphique sans courbe | L'historique du solde n'est disponible que pour les ID de compte préfixés par `biz_`, pas pour les comptes personnels préfixés par `user_`. |

## Disponible sur iOS

Les vues wallet, chacune avec un simulateur en direct sur sa page :

* [`BalanceElement`](https://docs.whop.com/fr/elements/latest/wallet/balances-balance#swift) : le solde total, sa tendance et le sélecteur de période
* [`ListElement`](https://docs.whop.com/fr/elements/latest/wallet/balances-list#swift) : la liste des avoirs
* [`ActivityElement`](https://docs.whop.com/fr/elements/latest/wallet/activity#swift) : le flux d'activité du grand livre

`WhopChatView` et `WhopDMsListView` sont fournis dans le même package pour le chat authentifié par l'utilisateur. Consultez le [README](https://github.com/whopio/whopsdk-elements-swift).

## Paiements sur iOS

Les éléments de paiement sont fournis dans leur propre package, [`whopio/elements-swift`](https://github.com/whopio/elements-swift), qui expose un module `Elements`. Le module du SDK wallet est `WhopElements`, donc les deux s'installent côte à côte :

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/whopio/elements-swift.git", from: "0.1.0")
]
```

Le module est `Elements`, et non `WhopElements`, donc `import Elements` est la seule ligne qui change. La configuration diffère aussi, et elle se répartit comme dans SwiftUI : la configuration est héritée de la racine de l'application, et un débit constitue un scope. Rien ne nécessite de jeton, car un jeton de confirmation est généré à partir de ce que l'acheteur a saisi, puis confirmé sur votre serveur :

```swift theme={null}
// once, at the app root
WindowGroup {
    CheckoutScreen()
        .whopElements(environment: .production)
}

// one charge, and the elements that collect for it
WhopPayments(accountID: "biz_xxxxxxxx", charge: .plan(id: "plan_xxxxxxxx")) { payments in
    WhopEmailElement()
    WhopPaymentElement()
    WhopBrandingElement()
    Button("Pay") { Task { try await payments.createConfirmationToken() } }
        .disabled(!payments.isComplete)
}
```

* [`WhopPaymentElement`](https://docs.whop.com/fr/elements/latest/payments/payment#swift) : les tuiles de moyens de paiement et tout ce que collecte le moyen sélectionné
* [`WhopCardElement`](https://docs.whop.com/fr/elements/latest/payments/card#swift) et [`WhopCardFields`](https://docs.whop.com/fr/elements/latest/payments/cardFields#swift) : les champs de carte hébergés, en un seul bloc ou placés un par un
* [`WhopAddressElement`](https://docs.whop.com/fr/elements/latest/payments/address#swift) : l'adresse de facturation, au format propre au pays
* [`WhopEmailElement`](https://docs.whop.com/fr/elements/latest/payments/email#swift) et [`WhopTaxIDElement`](https://docs.whop.com/fr/elements/latest/payments/taxId#swift)
* [`WhopBrandingElement`](https://docs.whop.com/fr/elements/latest/payments/branding#swift) : obligatoire à côté de toute interface de paiement
* [`WhopPaymentRequest`](https://docs.whop.com/fr/elements/latest/payments/paymentRequest#swift) : Apple Pay sans aucun élément monté

Les données de carte sont capturées par des champs hébergés isolés PCI et n'entrent jamais dans votre processus. Stylisez l'ensemble avec `.whopElementsAppearance(_:)` plutôt qu'avec `.whopTheme(_:)`.

## Authentification

`getToken` est votre unique point d'intégration, et le SDK l'appelle **avant chaque requête** : renvoyez donc un nouveau jeton plutôt que d'en mettre un en cache :

```tsx theme={null}
<WhopElements getToken={async () => (await fetch('/api/whop-token')).text()}>
  {/* your app */}
</WhopElements>
```

Un élément qui ne nécessite aucun identifiant fonctionne sans lui, vous pouvez donc afficher un formulaire de carte avant de connecter votre backend.

## Encaisser un paiement

La collecte et la confirmation sont séparées, et cette séparation est délibérée : l'application ne voit jamais de numéro de carte et votre serveur ne fait jamais confiance au client.

1. Les éléments collectent. Les numéros de carte passent directement des champs isolés PCI à un jeton, sans jamais transiter par votre code.
2. `createConfirmationToken()` renvoie un **jeton de confirmation**, que vous pouvez envoyer en toute sécurité à votre propre backend.
3. Votre backend confirme le paiement avec l'API Whop.
4. Si l'API répond que le paiement nécessite une action supplémentaire de l'acheteur, transmettez son `client_secret` à `handleNextAction()` et le SDK exécute l'étape 3D Secure ou de redirection.

```tsx theme={null}
const token = await payments.current!.createConfirmationToken();
const { status, clientSecret } = await myBackend.confirm(token.confirmationToken);
if (status === 'requires_action') await payments.current!.handleNextAction({ clientSecret });
```

## Redirections et 3D Secure

Les étapes hors application ouvrent le **navigateur système** (`ASWebAuthenticationSession` sur iOS, Custom Tabs sur Android), jamais une WebView, de sorte que la page de l'émetteur reste en dehors du périmètre de confiance de votre application et que ses cookies restent hors du stockage de votre application.

Définissez `returnUrl` sur `<Payments>` avec une URL **https** que vous hébergez. L'API refuse tout ce qui n'est pas https ou loopback (`PaymentsApi::ValidateReturnUrl`), donc un schéma d'application personnalisé ne fonctionnera pas ici — et vous n'en avez pas besoin : `handleNextAction` interroge le paiement jusqu'à son état final et ferme lui-même le navigateur, plutôt que d'attendre un deep link de retour vers votre application.

```tsx theme={null}
<Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx" returnUrl="https://example.com/checkout/return">
```

## Apple Pay et Google Pay

Les tuiles de wallet apparaissent dès que la plateforme peut présenter une feuille de paiement, et il n'y a rien à configurer pour l'un ou l'autre. Apple Pay utilise le marchand enregistré sur le compte Whop, donc votre application n'a besoin ni d'identifiant marchand ni de capability Xcode. `googlePayMerchantName` sur `<Payments>` définit uniquement le nom affiché dans la feuille.

## Thèmes

`appearance` sur `<WhopElements>` applique le thème à chaque élément situé en dessous, avec le même objet `theme` que celui accepté par les éléments web. Consultez [Apparence](https://docs.whop.com/fr/elements/latest/appearance.md).

## Ce que gèrent les éléments, et ce qui vous revient

Chaque élément récupère ses propres données et affiche ses propres états de chargement, vide et d'erreur. **La navigation et la soumission** vous reviennent : les éléments signalent via `onChange` et n'affichent jamais d'écran ni n'appellent votre backend.

## Dépannage

| Ce que vous voyez | Pourquoi |
| - | - |
| `BrandingRequiredError` lors de la confirmation | Aucun `BrandingElement` n'est monté. Montez-en un à l'intérieur de `<Payments>`. |
| `ChargeConfigError` | `<Payments>` n'a ni `plan`, ni paire `amount` et `currency`. |
| Aucune tuile de wallet | Le compte n'a aucun marchand Apple Pay enregistré, ou l'appareil ne peut pas présenter de feuille de paiement. |
| Les tuiles de moyens n'apparaissent jamais | `getToken` renvoie une clé API plutôt qu'un jeton d'accès, ou le jeton n'a pas le scope pour le compte. |
| Un champ de carte vide | Le build natif est antérieur au package. `@basis-theory/react-native-elements` s'installe avec lui, donc recompilez plutôt que de l'ajouter à la main. |

## Disponible dans React Native

Les éléments de paiement :

* [`PaymentElement`](https://docs.whop.com/fr/elements/latest/payments/payment) : les tuiles de moyens de paiement et tout ce dont le moyen sélectionné a besoin
* [`AddressElement`](https://docs.whop.com/fr/elements/latest/payments/address) : l'adresse de facturation au format du pays de l'acheteur
* [`CardElement`](https://docs.whop.com/fr/elements/latest/payments/card) : numéro, date d'expiration et code de sécurité en un seul composant
* [`CardFields`](https://docs.whop.com/fr/elements/latest/payments/cardFields) : les trois mêmes champs, placés individuellement
* [`EmailElement`](https://docs.whop.com/fr/elements/latest/payments/email) : l'e-mail de l'acheteur
* [`TaxIdElement`](https://docs.whop.com/fr/elements/latest/payments/taxId) : un type et un numéro d'immatriculation
* [`BrandingElement`](https://docs.whop.com/fr/elements/latest/payments/branding) : la mention Powered by Whop, obligatoire sur chaque formulaire

Les éléments de checkout :

* [`ExpressCheckoutElement`](https://docs.whop.com/fr/elements/latest/checkout/expressCheckout) : un seul appui Apple Pay ou Google Pay qui paie tout un checkout, sous `<Checkout>`


## Related topics

- [Premiers pas avec Element Sessions](https://docs.whop.com/fr/sdk/elements/whop-elements.md)
- [Activer les versements des sous-comptes](https://docs.whop.com/fr/developer/platforms/render-payout-portal.md)
- [ListElement](https://docs.whop.com/fr/elements/latest/wallet/balances-list.md)
