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

# CardElement

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

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

*Depuis `v1.0.0`.*

Se monte à l'intérieur de [`Payments`](https://docs.whop.com/fr/elements/latest/payments/overview). Transmettez les props et les callbacks via les options de création ou les props React.

> [!NOTE]
>
> **Exclusif.**`CardElement` est une alternative à `PaymentElement` ou `CardFields` dans ce handle Payments. Montez-en un seul à la fois. Détruisez-le avant d'en monter un autre.

> [!NOTE]
>
> **Attend `BrandingElement`.** Cet élément reste dans son état de chargement tant que `BrandingElement` n'est pas monté dans le même handle Payments.

Se monte à l'intérieur d'un scope `WhopPayments`. Les trois saisies de carte réunies en une seule unité, isolées PCI par le tokenizer : le numéro, la date d'expiration et le code de sécurité n'entrent donc jamais dans votre processus.

Montez-le à l'intérieur de `<Payments>`, qui gère le débit et le jeton de confirmation. `<Payments>` se monte lui-même à l'intérieur de `<WhopElements>`. Utilisez-le lorsque le formulaire accepte une carte et rien d'autre : il s'enregistre lui-même comme surface de collecte, de sorte que `createConfirmationToken` le tokenise sans aucun autre branchement.

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <CardElement onChange={(e) => console.log(e)} />
        <BrandingElement />
      </Payments>
    </WhopElements>
  );
}
```

```tsx React Native theme={null}
import { CardElement, Payments } from '@whop/elements-react-native';

export function CardStep() {
  return (
    <Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
      <CardElement layout="stacked" onChange={({ complete }) => console.log(complete)} />
    </Payments>
  );
}
```

```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('card', { onChange: (e) => console.log(e) }).mount('#payments-card');
  payments.create('branding').mount('#payments-branding');
</script>
```

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

// .whopElements(environment:) runs once at the app root. See Getting started.
struct CheckoutScreen: View {
    @State private var card = WhopCardState(isComplete: false, brand: nil)

    var body: some View {
        WhopPayments(accountID: "biz_xxxx", charge: .plan(id: "plan_xxxx")) { payments in
            ScrollView {
                VStack(alignment: .leading, spacing: 20) {
                WhopCardElement(layout: .stacked, state: $card)
                    WhopBrandingElement()
                }
                .padding()
            }
        }
    }
}
```

Données d'exemple. [Ouvrir le Playground](https://docs.whop.com/fr/elements/latest/payments/overview#playground).

[CardElement exécuté sur Android, dans l'application d'exemple React Native](https://app.revyl.ai/embed/97dfb742-fe50-4fe7-a817-87ea4585f159?controls=0)

## Props

**layout** `"compact" | "stacked"`

`stacked` (par défaut) place le numéro de carte au-dessus de la date d'expiration et du code de sécurité. `compact` place les trois sur une seule ligne. Par défaut : `"stacked"`.

## Événements

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

### `onChange`

Se déclenche lorsque les champs de carte changent. `complete` passe à true une fois que l'acheteur a rempli les trois. Utilisez-le pour activer la confirmation. `brand` est le réseau de carte détecté. `funding` est le type de financement détecté (`credit`, `debit` ou `prepaid`), `null` tant que le numéro n'en identifie pas un. `issuingCountry` est le code à deux lettres en minuscules du pays d'émission de la carte, `null` tant que le numéro n'en identifie pas un.

**payload** `object`

**propriétés**

**complete** `boolean` *required*

**brand** `string` *required*

**funding** `string | null` *required*

**issuingCountry** `string | null` *required*

### `onLoaderStart`

S'exécute après le premier affichage du squelette de chargement et avant `onReady`.

### `onReady`

S'exécute après le premier affichage complet de l'élément.

### `onError`

S'exécute lorsque l'élément ne parvient pas à se charger ou plante. L'affichage de repli reste visible. Utilisez `code` pour une gestion programmatique. `sourceKey` identifie une source d'état hôte en échec.

**e** `object`

**propriétés**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## Méthodes

Appelez-les sur le handle renvoyé par `create`, ou via une `ref` React.

### `mount`

Monte l'élément dans `target` et démarre le chargement. Les composants React se montent eux-mêmes.

**Paramètres**

**target** `string | HTMLElement` *required*

### `destroy`

Supprime l'élément et libère son frame et ses abonnements. Vous pouvez l'appeler plusieurs fois. React supprime l'élément automatiquement.

### `update`

Fusionne de nouvelles props dans l'élément monté. Avec React, modifiez plutôt les props du composant.

**Paramètres**

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

## Style

Stylisez ces parties via `appearance.classes`. Utilisez le camel case ou le kebab case pour les noms de propriétés et incluez les unités. Les feuilles de style de la page ne peuvent pas atteindre le frame de l'élément. Le framework valide chaque déclaration avant de l'injecter.

| Classe | Cible |
| - | - |
| `.whop-Card` | Racine de l'élément de carte |
| `.whop-CardError` | Panneau d'erreur de configuration de la carte |
| `.whop-CardField` | Champ du numéro de carte, de la date d'expiration ou du code de sécurité |
| `.whop-CardFieldError` | Message de validation de la carte |
| `.whop-CardFieldGroup` | Champs empilés du numéro de carte, de la date d'expiration et du code de sécurité |
| `.whop-CardFieldInput` | Conteneur de saisie PCI avec bordure |
| `.whop-CardFieldInputFocused` | Conteneur de saisie PCI ayant le focus |
| `.whop-CardFieldInputInvalid` | Conteneur de saisie PCI invalide ou incomplet |
| `.whop-CardFieldRow` | Ligne compacte du numéro de carte, de la date d'expiration et du code de sécurité |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Card': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// 9 classes use this shape
payments.update({
  appearance: { classes: { 'whop-Card': { fontWeight: '700' } } }
});
```

Avec React, transmettez `appearance` à `<Payments>`. Définissez-la globalement avec `WhopElements({ appearance })`.

## Paramètres

**layout** `WhopCardElement.Layout`

`.stacked` place le numéro au-dessus de la date d'expiration et du code de sécurité ; `.compact` place les trois sur une seule ligne. Par défaut : `.stacked`.

**publicKey** `String?`

Une clé publiable avancée. Omettez-la et celle du compte est récupérée.

**state** `Binding\<WhopCardState\>?`

Relit l'état de complétude et la marque détectée.

## `WhopCardState`

Ce que renvoie une sélection :

* `isComplete: Bool` : les trois champs sont valides
* `brand: String?` : le réseau détecté, dès que le numéro en identifie un

## États

S'affiche immédiatement et valide au fil de la saisie de l'acheteur. La marque apparaît dès que le numéro en identifie une. `state.isComplete` passe à true lorsque les trois champs sont valides.

## Bon à savoir

* Utilisez-le à la place de [`WhopPaymentElement`](https://docs.whop.com/fr/elements/latest/payments/payment#swift) lorsque la carte est le seul moyen de paiement que vous acceptez. Monter les deux crée un conflit : le contrôleur génère le jeton à partir d'une seule surface de collecte.
* `createConfirmationToken(billingDetails:)` nécessite le nom du titulaire de la carte pour le paiement par carte : transmettez-en un ou montez un élément d'adresse qui le collecte.
* `publicKey` est une option avancée de contournement. Omettez-la et le SDK récupère la clé de tokenizer du compte.

## Installation

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

> [!NOTE]
>
> Montez-le à l'intérieur d'un scope `WhopPayments(accountID:charge:)`, qui crée le contrôleur et le transmet à son contenu. `payments.buyer` est l'acheteur connecté dès qu'une connexion par e-mail en a authentifié un. `WhopBrandingElement` doit aussi être à l'écran, car Whop est le marchand officiel (merchant of record) de ces ventes et `createConfirmationToken` refuse sans lui. Stylisez avec `.whopElementsAppearance(_:)`. Le module est `Elements`, et non `WhopElements` du SDK wallet. Consultez [Premiers pas](https://docs.whop.com/fr/elements/latest/getting-started.md) et [Apparence](https://docs.whop.com/fr/elements/latest/appearance.md).

## Props

**layout** `'stacked' | 'compact'`

`stacked` place le numéro au-dessus de la date d'expiration et du code de sécurité. `compact` place les trois sur une seule ligne. Par défaut : `stacked`.

**onChange** `(payload: CardFieldsChangePayload) =\> void`

Se déclenche à chaque modification avec l'état de complétude et les erreurs par champ.

**style** `StyleProp\<ViewStyle\>`

Appliqué à la `View` externe de l'élément. Pour la personnalisation du thème, préférez `appearance.parts` sur le provider, qui couvre tous les éléments de cette interface. Notez que les noms de parties React Native forment aujourd'hui leur propre ensemble, distinct des noms de classes `whop-*` du web : un objet appearance web ne peut donc pas être repris tel quel.

**fallback** `ReactNode`

Affiché à la place du squelette intégré pendant le chargement de l'élément.

**onReady** `() =\> void`

Se déclenche une fois que l'élément est interactif. `<Payments>` les regroupe, donc c'est généralement son propre `onLoadingChange` qu'il vous faut.

**onError** `(error: \{ message: string; code?: string \}) =\> void`

Un échec de chargement ou de configuration pour cet élément. L'élément affiche sa propre vue d'erreur dans tous les cas.

## `CardFieldsChangePayload`

Ce que renvoie `onChange` :

* `complete: boolean` : chaque champ est rempli et valide
* `errors: Record<string, string>` : messages par champ, vide exactement lorsque `complete` vaut true

## États

Les trois champs s'affichent ensemble une fois la clé publiable résolue. `onChange` signale `complete` lorsque les trois sont valides, et l'élément affiche ses propres erreurs par champ.

## Bon à savoir

* Les numéros de carte ne passent jamais par votre code. Les champs sont des saisies natives isolées PCI, et le SDK transmet un jeton à Whop : votre application reste donc hors du périmètre PCI.
* Le monter fait de la carte la surface de collecte du provider, de sorte que `createConfirmationToken` la tokenise sans branchement supplémentaire. Ne le montez pas à côté d'un `PaymentElement` : une seule surface de collecte est active à la fois.
* Pour un formulaire où les trois champs s'insèrent dans votre propre mise en page, utilisez plutôt [`CardFields`](https://docs.whop.com/fr/elements/latest/payments/cardFields).

> [!NOTE]
>
> Enveloppez votre application dans `<WhopElements getToken={…}>` une seule fois, puis montez `<Payments>` autour des éléments. Consultez [Premiers pas](https://docs.whop.com/fr/elements/latest/getting-started.md) et [Apparence](https://docs.whop.com/fr/elements/latest/appearance.md).
