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

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

> [!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). Créez-le pour obtenir un handle, puis montez ses éléments sur ce handle. Appelez `destroy()` pour supprimer le sous-contrôleur et libérer son emplacement. Créez-le à nouveau pour obtenir un nouveau handle.

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

## Aperçu

Une démo interactive en direct de la disposition par défaut de ce sous-contrôleur, avec des données d'exemple :

Se monte à l'intérieur d'un scope `WhopPayments`. Les trois mêmes saisies hébergées que [`WhopCardElement`](https://docs.whop.com/fr/elements/latest/payments/card#swift), placées une par une dans son builder de contenu pour que votre propre mise en page décide de l'emplacement de chacune.

Le provider des champs de carte placés individuellement. Enveloppez la partie de votre formulaire qui les contient, puis placez `CardNumberElement`, `CardExpiryElement` et `CardCvcElement` là où votre mise en page le souhaite.

## Aperçu

Exécuté dans l'application d'exemple React Native :

[CardFields exécuté sur Android, dans l'application d'exemple React Native](https://app.revyl.ai/embed/4a22f507-3667-4162-b83f-1d7a7d4fa900?controls=0)

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <CardFields>
          <CardNumberElement />
          <CardExpiryElement />
          <CardCvcElement />
        </CardFields>
        <BrandingElement />
      </Payments>
    </WhopElements>
  );
}
```

```tsx React Native theme={null}
import { View } from 'react-native';
import {
  CardCvcElement,
  CardExpiryElement,
  CardFields,
  CardNumberElement,
  Payments,
} from '@whop/elements-react-native';

export function CardForm() {
  return (
    <Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
      <CardFields onChange={({ complete }) => console.log(complete)}>
        <CardNumberElement />
        <View style={{ flexDirection: 'row', gap: 8 }}>
          <CardExpiryElement style={{ flex: 1 }} />
          <CardCvcElement style={{ flex: 1 }} />
        </View>
      </CardFields>
    </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 */ });
  const cardFields = payments.create('cardFields', { /* options */ });
  cardFields.create('cardNumber').mount('#payments-cardFields-cardNumber');
  cardFields.create('cardExpiry').mount('#payments-cardFields-cardExpiry');
  cardFields.create('cardCvc').mount('#payments-cardFields-cardCvc');
  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) {
                WhopCardFields(state: $card) {
                    WhopCardNumberElement()
                    HStack(alignment: .top, spacing: 8) {
                        WhopCardExpiryElement()
                        WhopCardCVCElement()
                    }
                }
                    WhopBrandingElement()
                }
                .padding()
            }
        }
    }
}
```

## Options

Transmettez-les à `payments.create('cardFields', { … })`, ou comme props sur `<CardFields>` avec React. Les props injectées par le parent n'apparaissent jamais ici.

**networks** `CardNetworkArt[]`

Les réseaux de carte acceptés par le vendeur, dans l'ordre d'affichage — les objets `networks` de l'entrée carte de la matrice, dont les icônes fournies par l'API déterminent le visuel de marque du champ de numéro. Omettez-le pour qu'il soit récupéré avec la clé.

**propriétés**

**brand** `string` *required*

L'une des valeurs `"visa"`, `"mastercard"`, `"amex"`, `"discover"`, `"jcb"`, `"diners"`, `"unionpay"`, `"elo"` ou `"maestro"`.

**icons** `object` *required*

**propriétés**

**square** `object` *required*

**propriétés**

**light** `object` *required*

**propriétés**

**svg** `string` *required*

**dark** `object` *required*

**propriétés**

**svg** `string` *required*

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

`stacked` (par défaut) agence les champs composés avec une ligne pour le numéro au-dessus de la date d'expiration et du code de sécurité. `compact` les agence sur une seule ligne. Les champs montés séparément ignorent cette disposition et s'affichent avec des bordures complètes et des coins arrondis. Par défaut : `"stacked"`.

**publicKey** `string`

Clé publiable Basis Theory avancée. Omettez-la pour récupérer la clé automatiquement.

## Événements

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

### `onChange`

Se déclenche lorsque l'état de complétude change. `complete` passe à true une fois que l'acheteur a rempli les trois champs. Utilisez-le pour activer la confirmation. `brand` est le réseau de carte détecté tel que le champ le signale ; `network` est la même détection dans le vocabulaire de réseaux de l'API (correspond aux `networks` de l'entrée carte de la matrice, `null` tant qu'il est inconnu). `last4` correspond aux quatre derniers chiffres du numéro, `null` tant que la saisie du numéro n'est pas assez avancée. `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*

**network** `string | null` *required*

L'une des valeurs `"visa"`, `"mastercard"`, `"amex"`, `"discover"`, `"jcb"`, `"diners"`, `"unionpay"`, `"elo"`, `"maestro"` ou `null`.

**last4** `string | null` *required*

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

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

## Méthodes

Appelez-les sur le sous-handle obtenu avec `payments.create('cardFields', { … })`.

### `tokenize`

Méthode avancée qui tokenise les trois champs sans créer de jeton de confirmation. Elle émet `tokenized` vers le contrôleur de paiements. Les erreurs de validation apparaissent sur le champ en échec, et la méthode lève une exception. Utilisez `payments.createConfirmationToken()` pour confirmer un paiement.

**Paramètres**

**input** `object` *required*

**propriétés**

**accountId** `string`

**Renvoie** `Promise<object>`

**token** `string` *required*

### `collect`

`payments.createConfirmationToken()` appelle cette action pour `cardFields`. Ne l'appelez pas directement. Elle tokenise les champs et renvoie les données utilisées pour créer le jeton de confirmation.

**Paramètres**

**input** `object` *required*

**propriétés**

**billingDetails** `object`

**propriétés**

**email** `string`

**name** `string`

**address** `object`

**propriétés**

**country** `string`

**line1** `string`

**city** `string`

**postal\_code** `string`

**Renvoie** `Promise<object>`

**paymentMethod** `object` *required*

**propriétés**

**type** `string` *required*

**category** `string` *required*

**card** `object` *required*

**propriétés**

**token** `string` *required*

**billingDetails** `object` *required*

**propriétés**

**email** `string` *required*

**name** `string`

**address** `object`

**propriétés**

**country** `string`

**line1** `string`

**city** `string`

**postal\_code** `string`

### `update`

Fusionne de nouvelles props et de nouveaux callbacks dans le sous-contrôleur.

**Paramètres**

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

### `destroy`

Détruit le sous-contrôleur et ses éléments, puis libère son emplacement exclusif. Un `create("cardFields")` ultérieur repart de zéro.

## Paramètres

**publicKey** `String?`

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

**layout** `WhopCardElement.Layout`

Lu uniquement lorsqu'une unité composée agence elle-même les champs. Les champs montés séparément l'ignorent.

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

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

**content** `() -\> Content` *required*

L'endroit où vont les trois vues de champ. Tout autre contenu placé ici s'affiche normalement.

## `WhopCardState`

Ce que renvoie une sélection :

* `isComplete: Bool` : les trois champs sont valides
* `brand: String?` : le réseau détecté

## États

Chaque champ s'affiche immédiatement et valide au fil de la saisie de l'acheteur. `state.isComplete` passe à true lorsque les trois sont valides, où que vous les placiez.

## Bon à savoir

* Les trois vues de champ ne fonctionnent qu'à l'intérieur d'un builder `WhopCardFields` : elles lisent l'unité qu'il crée. Montées ailleurs, elles n'affichent rien.
* Montez les trois. Une unité à laquelle il en manque un n'est jamais complète, donc le bouton de confirmation ne s'active jamais.

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

**children** `ReactNode` *required*

Votre mise en page, avec les trois éléments de champ placés quelque part à l'intérieur.

**publicKey** `string`

Une clé publiable de tokenizer avancée. Omettez-la et le SDK récupère lui-même la clé du compte.

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

Agence les champs composés ensemble. Les champs montés séparément l'ignorent et s'affichent avec des bordures complètes. Par défaut : `stacked`.

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

Se déclenche à chaque modification avec l'état combiné des champs montés.

## `CardFieldsChangePayload`

Ce que renvoie `onChange` :

* `complete: boolean` : chaque champ monté est rempli et valide
* `errors: Record<string, string>` : messages par champ, avec les clés `cardNumber`, `cardExpiry`, `cardCvc`

## États

Ses enfants s'affichent une fois la clé publiable résolue. `onChange` signale l'état combiné de chaque champ monté, de sorte qu'un seul handler couvre toute la carte.

## 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.
* Chaque champ doit se trouver dans le même `CardFields`. Ils partagent une seule tokenisation, donc un champ monté en dehors ne collecte rien.
* `CardFields` enregistre la surface de collecte, de sorte que `createConfirmationToken` tokenise la carte sans branchement supplémentaire.
* La récupération de la clé publiable est automatique. Ne transmettez `publicKey` que si vous en détenez déjà une.

> [!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).

## Éléments

Les éléments que monte ce sous-contrôleur. Chacun a sa propre page :

> [card] [CardNumberElement](https://docs.whop.com/fr/elements/latest/payments/cardFields-cardNumber.md)
>
> Champ hébergé du numéro de carte, isolé PCI. Les numéros de carte n'atteignent jamais la page hôte.

> [card] [CardExpiryElement](https://docs.whop.com/fr/elements/latest/payments/cardFields-cardExpiry.md)
>
> Champ hébergé de la date d'expiration de la carte, isolé PCI.

> [card] [CardCvcElement](https://docs.whop.com/fr/elements/latest/payments/cardFields-cardCvc.md)
>
> Champ hébergé du code de sécurité de la carte, isolé PCI.


## Related topics

- [CardCvcElement](https://docs.whop.com/fr/elements/latest/payments/cardFields-cardCvc.md)
- [CardExpiryElement](https://docs.whop.com/fr/elements/latest/payments/cardFields-cardExpiry.md)
- [CardNumberElement](https://docs.whop.com/fr/elements/latest/payments/cardFields-cardNumber.md)
