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

# TaxIdElement

> Collecte un numéro d'immatriculation 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.

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

Se monte à l'intérieur d'un scope `WhopPayments`. Un sélecteur de type d'immatriculation à côté de son champ de valeur, présélectionné à partir du pays de l'acheteur.

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>`. Un sélecteur de type d'immatriculation à côté d'un champ de valeur, afin qu'un acheteur saisissant un numéro de TVA ou de CUIT choisisse d'abord le bon type.

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

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

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

export function TaxStep({ country }: { country: string }) {
  return (
    <Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
      <TaxIdElement country={country} onChange={({ taxId }) => console.log(taxId.type, taxId.value)} />
    </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('taxId', { onChange: (e) => console.log(e) }).mount('#payments-taxId');
</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 address = PostalAddress()
    @State private var taxID: WhopTaxID?

    var body: some View {
        WhopPayments(accountID: "biz_xxxx", charge: .plan(id: "plan_xxxx")) { payments in
            ScrollView {
                VStack(alignment: .leading, spacing: 20) {
                WhopAddressElement(address: $address)
                WhopTaxIDElement(taxID: $taxID, country: address.country)
                    WhopBrandingElement()
                }
                .padding()
            }
        }
    }
}
```

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

[TaxIdElement exécuté sur Android, dans l'application d'exemple React Native](https://app.revyl.ai/embed/713e08f7-91e6-4449-905b-ceb4c18b83c2?controls=0)

## Props

**disabled** `boolean`

Désactive les deux champs pendant que l'hôte enregistre la dernière immatriculation validée. Par défaut : `false`.

**country** `string`

Pays de l'acheteur au format ISO 3166-1 alpha-2, utilisé pour présélectionner le type. `AR` sélectionne `ar_cuit`, `LI` sélectionne `li_uid`. Les pays de l'UE et les valeurs non mappées ou vides sélectionnent `eu_vat`. Les autres pays mappés sélectionnent leur propre premier type. Une sélection manuelle est conservée lors des changements de pays. Par défaut : `""`.

**defaultValue** `object`

`type` et `value` initiaux provenant d'une session reprise. Un `type` non pris en charge se rabat sur la valeur par défaut du pays.

**propriétés**

**type** `string` *required*

**value** `string` *required*

**error** `string`

Erreur de validation de l'API affichée sous le champ de valeur. Vide (par défaut), rien n'est affiché. Par défaut : `""`.

## Événements

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

### `onChange`

Se déclenche à la perte du focus ou sur Entrée lorsque la valeur n'est pas vide, ou lorsque le type change alors qu'une valeur est présente. Des valeurs consécutives identiques ne déclenchent qu'une fois. Effacer la valeur ne déclenche rien. L'hôte doit effacer les immatriculations enregistrées.

**payload** `object`

**propriétés**

**taxId** `object` *required*

**propriétés**

**type** `string` *required*

**valeurs**

L'une des valeurs `"ad_nrt"`, `"ao_tin"`, `"ar_cuit"`, `"al_tin"`, `"am_tin"`, `"aw_tin"`, `"au_abn"`, `"au_arn"`, `"eu_vat"`, `"az_tin"`, `"bs_tin"`, `"bh_vat"`, `"bd_bin"`, `"bb_tin"`, `"by_tin"`, `"bj_ifu"`, `"bo_tin"`, `"ba_tin"`, `"br_cnpj"`, `"br_cpf"`, `"bg_uic"`, `"bf_ifu"`, `"kh_tin"`, `"cm_niu"`, `"ca_bn"`, `"ca_gst_hst"`, `"ca_pst_bc"`, `"ca_pst_mb"`, `"ca_pst_sk"`, `"ca_qst"`, `"cv_nif"`, `"cl_tin"`, `"cn_tin"`, `"co_nit"`, `"cd_nif"`, `"cr_tin"`, `"hr_oib"`, `"do_rcn"`, `"ec_ruc"`, `"eg_tin"`, `"sv_nit"`, `"et_tin"`, `"eu_oss_vat"`, `"ge_vat"`, `"gh_tin"`, `"de_stn"`, `"gb_vat"`, `"gn_nif"`, `"hk_br"`, `"hu_tin"`, `"is_vat"`, `"in_gst"`, `"id_npwp"`, `"il_vat"`, `"jp_cn"`, `"jp_rn"`, `"jp_trn"`, `"kz_bin"`, `"ke_pin"`, `"kg_tin"`, `"la_tin"`, `"li_uid"`, `"li_vat"`, `"my_frp"`, `"my_itn"`, `"my_sst"`, `"mr_nif"`, `"mx_rfc"`, `"md_vat"`, `"me_pib"`, `"ma_vat"`, `"np_pan"`, `"nz_gst"`, `"ng_tin"`, `"mk_vat"`, `"no_vat"`, `"no_voec"`, `"om_vat"`, `"pe_ruc"`, `"ph_tin"`, `"pl_nip"`, `"ro_tin"`, `"ru_inn"`, `"ru_kpp"`, `"sa_vat"`, `"sn_ninea"`, `"rs_pib"`, `"sg_gst"`, `"sg_uen"`, `"si_tin"`, `"za_vat"`, `"kr_brn"`, `"es_cif"`, `"ch_uid"`, `"ch_vat"`, `"tw_vat"`, `"tj_tin"`, `"tz_vat"`, `"th_vat"`, `"tr_tin"`, `"ug_tin"`, `"ua_vat"`, `"ae_trn"`, `"us_ein"`, `"uy_ruc"`, `"uz_tin"`, `"uz_vat"`, `"ve_rif"`, `"vn_tin"`, `"zm_tin"`, `"zw_tin"`, `"sr_fin"` ou `"xi_vat"`.

**value** `string` *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\<TaxIdElementProps\>` *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-TaxId` | Racine de l'immatriculation fiscale |
| `.whop-TaxIdError` | Erreur de validation de l'API |
| `.whop-TaxIdInput` | Champ de saisie de la valeur d'immatriculation |
| `.whop-TaxIdLabel` | Libellé de la valeur d'immatriculation |
| `.whop-TaxIdTypeLabel` | Libellé du type d'immatriculation |
| `.whop-TaxIdTypeSelect` | Sélecteur du type d'immatriculation |

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

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

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

## Paramètres

**taxID** `Binding\<WhopTaxID?\>?`

Reçoit chaque immatriculation validée.

**country** `String?`

Pays de l'acheteur au format ISO 3166-1 alpha-2, utilisé pour présélectionner le type.

**defaultValue** `WhopTaxID?`

Une paire initiale provenant d'une session reprise. Un type non pris en charge se rabat sur la valeur par défaut.

**isDisabled** `Bool`

Désactive les deux champs pendant que vous enregistrez la dernière immatriculation validée. Par défaut : `false`.

**error** `String?`

Une erreur de validation de l'API, affichée sous le champ de valeur.

## `WhopTaxID`

Ce que renvoie une sélection :

* `type: WhopTaxIDType` : le type d'immatriculation, `eu_vat`, `ar_cuit`, …
* `value: String` : l'immatriculation elle-même

## États

S'affiche immédiatement. Une valeur qui ne correspond pas au format du type sélectionné affiche son erreur. `error` affiche un échec de validation de l'API sous le champ de valeur.

## Bon à savoir

* `AR` présélectionne `ar_cuit` ; les membres de l'UE et tout pays non mappé présélectionnent `eu_vat`. Un choix manuel est conservé lors des changements de pays.
* Transmettez le pays issu de l'élément d'adresse pour que les deux restent synchronisés.
* Le binding se déclenche à chaque immatriculation validée, et non à chaque frappe.

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

**country** `string`

Pays de l'acheteur au format ISO 3166-1 alpha-2, utilisé pour présélectionner le type. `AR` sélectionne `ar_cuit` ; les valeurs UE et non mappées sélectionnent `eu_vat`.

**defaultValue** `\{ type: string; value: string \}`

Paire initiale provenant d'une session reprise. Un type non pris en charge se rabat sur la valeur par défaut.

**disabled** `boolean`

Désactive les deux champs, le temps que vous enregistriez la dernière immatriculation validée.

**error** `string`

Un message de validation provenant de votre API, affiché sous le champ de valeur.

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

Se déclenche à chaque changement de type ou de valeur.

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

## `TaxIdChangePayload`

Ce que renvoie `onChange` :

* `taxId: { type: TaxIdType; value: string }` : le type d'immatriculation sélectionné et ce que l'acheteur a saisi

## États

S'affiche immédiatement. Le type est présélectionné à partir de `country` et le champ de valeur est validé selon le format de ce type. `onChange` se déclenche avec la paire courante.

## Bon à savoir

* `country` ne fait que présélectionner. Un acheteur qui choisit un type manuellement le conserve lors des changements de pays.
* Transmettez `error` pour afficher un message issu de votre propre validation d'API sous le champ de valeur.
* L'élément signale la paire. Son envoi vous revient : associez-la à votre propre commande ou fiche client.

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