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

> Tres campos de tarjeta montables por separado y aislados según PCI para diseños personalizados: número, fecha de vencimiento y código de seguridad. Créalo con `payments.create("cardFields")`, coloca cada campo, habilita tu botón de pago desde `onChange` y confirma con `payments.createConfirmationToken()`. Los números de tarjeta permanecen en campos alojados.

> [!NOTE]
>
> Esta página documenta `@whop/elements@1.10.0` y `@whop/elements-react@1.10.0`.

*Desde `v1.0.0`.*

Se monta dentro de [`Payments`](https://docs.whop.com/es/elements/latest/payments/overview). Créalo para obtener un handle y luego monta sus elementos en ese handle. Llama a `destroy()` para eliminar el subcontrolador y liberar su espacio. Vuelve a crearlo para obtener un handle nuevo.

> [!NOTE]
>
> **Exclusivo.**`CardFields` es una alternativa a `PaymentElement` o `CardElement` en este handle de Payments. Monta uno a la vez. Destrúyelo antes de montar otro.

## Vista previa

Una demostración interactiva en vivo de la disposición predeterminada de este subcontrolador con datos de ejemplo:

Se monta dentro de un ámbito `WhopPayments`. Los mismos tres campos alojados que [`WhopCardElement`](https://docs.whop.com/es/elements/latest/payments/card#swift), colocados uno a uno dentro de su builder de contenido para que tu propio diseño decida dónde va cada uno.

El provider para campos de tarjeta colocados individualmente. Envuelve la parte de tu formulario que los contiene y luego coloca `CardNumberElement`, `CardExpiryElement` y `CardCvcElement` donde tu diseño los necesite.

## Vista previa

Ejecutándose en la app de ejemplo de React Native:

[CardFields ejecutándose en Android, en la app de ejemplo de 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()
            }
        }
    }
}
```

## Opciones

Pásalas a `payments.create('cardFields', { … })`, o como props en `<CardFields>` en React. Las props inyectadas por el padre nunca aparecen aquí.

**networks** `CardNetworkArt[]`

Las redes de tarjeta aceptadas por el vendedor en orden de visualización: los objetos `networks` de la entrada de tarjeta de la matriz, cuyos iconos servidos por la API determinan el logotipo de la marca del campo de número. Omítelo para obtenerlo junto con la clave.

**propiedades**

**brand** `string` *required*

Uno de `"visa"`, `"mastercard"`, `"amex"`, `"discover"`, `"jcb"`, `"diners"`, `"unionpay"`, `"elo"` o `"maestro"`.

**icons** `object` *required*

**propiedades**

**square** `object` *required*

**propiedades**

**light** `object` *required*

**propiedades**

**svg** `string` *required*

**dark** `object` *required*

**propiedades**

**svg** `string` *required*

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

`stacked` (predeterminado) dispone los campos compuestos como una fila de número encima de la fecha de vencimiento y el código de seguridad. `compact` los dispone en una fila. Los campos montados por separado ignoran este diseño y se renderizan con bordes completos y esquinas redondeadas. El valor predeterminado es `"stacked"`.

**publicKey** `string`

Clave publicable avanzada de Basis Theory. Omítela para obtener la clave automáticamente.

## Eventos

Pasa los callbacks en las opciones de creación o como props de React.

### `onChange`

Se dispara cuando cambia el estado de completitud. `complete` pasa a ser true después de que el comprador rellena los tres campos. Úsalo para habilitar la confirmación. `brand` es la red de la tarjeta detectada tal como la informa el campo; `network` es la misma detección en el vocabulario de redes de la API (coincide con los `networks` de la entrada de tarjeta de la matriz, `null` mientras se desconoce). `last4` son los últimos cuatro dígitos del número, `null` hasta que el número está lo bastante avanzado. `funding` es el tipo de financiación detectado (`credit`, `debit` o `prepaid`), `null` hasta que el número identifica uno. `issuingCountry` es el código de dos letras en minúsculas del país en el que se emitió la tarjeta, `null` hasta que el número identifica uno.

**payload** `object`

**propiedades**

**complete** `boolean` *required*

**brand** `string` *required*

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

Uno de `"visa"`, `"mastercard"`, `"amex"`, `"discover"`, `"jcb"`, `"diners"`, `"unionpay"`, `"elo"`, `"maestro"` o `null`.

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

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

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

## Métodos

Llámalos en el subhandle de `payments.create('cardFields', { … })`.

### `tokenize`

Método avanzado que tokeniza los tres campos sin crear un token de confirmación. Emite `tokenized` al controlador de pagos. Los errores de validación aparecen en el campo que falla y el método lanza una excepción. Usa `payments.createConfirmationToken()` para confirmar un pago.

**Parámetros**

**input** `object` *required*

**propiedades**

**accountId** `string`

**Devuelve** `Promise<object>`

**token** `string` *required*

### `collect`

`payments.createConfirmationToken()` llama a esta acción para `cardFields`. No la llames directamente. Tokeniza los campos y devuelve los datos usados para crear el token de confirmación.

**Parámetros**

**input** `object` *required*

**propiedades**

**billingDetails** `object`

**propiedades**

**email** `string`

**name** `string`

**address** `object`

**propiedades**

**country** `string`

**line1** `string`

**city** `string`

**postal\_code** `string`

**Devuelve** `Promise<object>`

**paymentMethod** `object` *required*

**propiedades**

**type** `string` *required*

**category** `string` *required*

**card** `object` *required*

**propiedades**

**token** `string` *required*

**billingDetails** `object` *required*

**propiedades**

**email** `string` *required*

**name** `string`

**address** `object`

**propiedades**

**country** `string`

**line1** `string`

**city** `string`

**postal\_code** `string`

### `update`

Combina nuevas props y callbacks en el subcontrolador.

**Parámetros**

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

### `destroy`

Destruye el subcontrolador y sus elementos, y luego libera su espacio exclusivo. Un `create("cardFields")` posterior empieza de cero.

## Parámetros

**publicKey** `String?`

Una clave publicable avanzada. Si la omites, se obtiene la propia de la cuenta.

**layout** `WhopCardElement.Layout`

Solo se lee cuando una unidad compuesta dispone los campos por sí misma. Los campos montados por separado lo ignoran.

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

Devuelve si está completo y la marca detectada.

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

Donde van las tres vistas de campo. Cualquier otra cosa aquí dentro se renderiza con normalidad.

## `WhopCardState`

Lo que devuelve una selección:

* `isComplete: Bool`: los tres campos son válidos
* `brand: String?`: la red detectada

## Estados

Cada campo se renderiza inmediatamente y valida a medida que el comprador escribe. `state.isComplete` pasa a ser true cuando los tres son válidos, dondequiera que los coloques.

## Información útil

* Las tres vistas de campo solo funcionan dentro de un builder `WhopCardFields`: leen la unidad que este crea. Montadas en cualquier otro lugar, no renderizan nada.
* Monta los tres. Una unidad a la que le falte uno nunca se completa, por lo que el botón de confirmar nunca se habilita.

## Instalación

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

> [!NOTE]
>
> Móntalo dentro de un ámbito `WhopPayments(accountID:charge:)`, que crea el controlador y se lo pasa a su contenido. `payments.buyer` es el comprador con sesión iniciada una vez que un inicio de sesión por correo electrónico lo ha verificado. `WhopBrandingElement` también tiene que estar en pantalla, porque Whop es el comerciante registrado en estas ventas y `createConfirmationToken` se rechaza sin él. Aplica estilo con `.whopElementsAppearance(_:)`. El módulo es `Elements`, no `WhopElements` del SDK de wallet. Consulta [Primeros pasos](https://docs.whop.com/es/elements/latest/getting-started.md) y [Appearance](https://docs.whop.com/es/elements/latest/appearance.md).

## Props

**children** `ReactNode` *required*

Tu diseño, con los tres elementos de campo en algún lugar de su interior.

**publicKey** `string`

Una clave publicable avanzada del tokenizador. Si la omites, el SDK obtiene por sí mismo la clave de la cuenta.

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

Da forma a los campos que se componen juntos. Los campos montados por separado lo ignoran y se renderizan con bordes completos. El valor predeterminado es `stacked`.

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

Se dispara en cada edición con el estado combinado de los campos montados.

## `CardFieldsChangePayload`

Lo que devuelve `onChange`:

* `complete: boolean`: todos los campos montados están rellenos y son válidos
* `errors: Record<string, string>`: mensajes por campo, con las claves `cardNumber`, `cardExpiry`, `cardCvc`

## Estados

Sus hijos se renderizan una vez que se resuelve la clave publicable. `onChange` informa del estado combinado de todos los campos montados, por lo que un solo handler cubre toda la tarjeta.

## Información útil

* Los números de tarjeta nunca pasan por tu código. Los campos son inputs nativos aislados según PCI y el SDK entrega a Whop un token, por lo que tu app queda fuera del alcance de PCI.
* Todos los campos deben estar dentro del mismo `CardFields`. Comparten una única tokenización, por lo que un campo montado fuera de él no recopila nada.
* `CardFields` registra la superficie de recopilación, por lo que `createConfirmationToken` tokeniza la tarjeta sin conexiones adicionales.
* La obtención de la clave publicable es automática. Pasa `publicKey` solo si ya tienes una.

> [!NOTE]
>
> Envuelve tu app en `<WhopElements getToken={…}>` una vez y luego monta `<Payments>` alrededor de los elementos. Consulta [Primeros pasos](https://docs.whop.com/es/elements/latest/getting-started.md) y [Appearance](https://docs.whop.com/es/elements/latest/appearance.md).

## Elementos

Los elementos que monta este subcontrolador. Cada uno tiene su propia página:

> [card] [CardNumberElement](https://docs.whop.com/es/elements/latest/payments/cardFields-cardNumber.md)
>
> Campo alojado del número de tarjeta, aislado según PCI. Los números de tarjeta nunca llegan a la página host.

> [card] [CardExpiryElement](https://docs.whop.com/es/elements/latest/payments/cardFields-cardExpiry.md)
>
> Campo alojado de la fecha de vencimiento de la tarjeta, aislado según PCI.

> [card] [CardCvcElement](https://docs.whop.com/es/elements/latest/payments/cardFields-cardCvc.md)
>
> Campo alojado del código de seguridad de la tarjeta, aislado según PCI.


## Related topics

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