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

> Campos predispuestos para el número de tarjeta, la fecha de vencimiento y el código de seguridad. Créalo con `payments.create("card")`, habilita tu botón de pago desde `onChange` y confirma con `payments.createConfirmationToken()`. Los números de tarjeta permanecen en campos alojados aislados según PCI. `layout` admite `stacked` (predeterminado) y `compact`.

> [!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). Pasa props y callbacks mediante las opciones de creación o las props de React.

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

> [!NOTE]
>
> **Espera a `BrandingElement`.** Este elemento permanece en su estado de carga hasta que `BrandingElement` se monta en el mismo handle de Payments.

Se monta dentro de un ámbito `WhopPayments`. Los tres campos de la tarjeta como una sola unidad, aislados según PCI por el tokenizador, de modo que el número, la fecha de vencimiento y el código de seguridad nunca entran en tu proceso.

Móntalo dentro de `<Payments>`, que gestiona el cobro y el token de confirmación. `<Payments>` se monta a su vez dentro de `<WhopElements>`. Úsalo cuando el formulario acepta una tarjeta y nada más: se registra a sí mismo como la superficie de recopilación, por lo que `createConfirmationToken` lo tokeniza sin necesidad de conectar nada más.

```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()
            }
        }
    }
}
```

Datos de ejemplo. [Abre el Playground](https://docs.whop.com/es/elements/latest/payments/overview#playground).

[CardElement ejecutándose en Android, en la app de ejemplo de React Native](https://app.revyl.ai/embed/97dfb742-fe50-4fe7-a817-87ea4585f159?controls=0)

## Props

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

`stacked` (predeterminado) coloca el número de tarjeta encima de la fecha de vencimiento y el código de seguridad. `compact` coloca los tres en una fila. El valor predeterminado es `"stacked"`.

## Eventos

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

### `onChange`

Se dispara cuando cambian los campos de la tarjeta. `complete` pasa a ser true después de que el comprador rellena los tres. Úsalo para habilitar la confirmación. `brand` es la red de la tarjeta detectada. `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*

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

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

### `onLoaderStart`

Se ejecuta después de que el esqueleto de carga se pinta por primera vez y antes de `onReady`.

### `onReady`

Se ejecuta después del primer pintado completo del elemento.

### `onError`

Se ejecuta cuando el elemento no se carga o falla. El contenido de respaldo permanece visible. Usa `code` para el manejo programático. `sourceKey` identifica una fuente de estado del host que falló.

**e** `object`

**propiedades**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## Métodos

Llámalos en el handle que devuelve `create`, o a través de una `ref` de React.

### `mount`

Monta el elemento en `target` y comienza a cargarlo. Los componentes de React se montan solos.

**Parámetros**

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

### `destroy`

Elimina el elemento y libera su frame y sus suscripciones. Puedes llamarlo más de una vez. React elimina el elemento automáticamente.

### `update`

Combina nuevas props en el elemento montado. En React, cambia las props del componente en su lugar.

**Parámetros**

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

## Estilos

Aplica estilo a estas partes mediante `appearance.classes`. Usa camel case o kebab case para los nombres de las propiedades e incluye las unidades. Las hojas de estilo de la página no pueden llegar al frame del elemento. El framework valida cada declaración antes de inyectarla.

| Clase | Aplica a |
| - | - |
| `.whop-Card` | Raíz del elemento de tarjeta |
| `.whop-CardError` | Panel de error de configuración de la tarjeta |
| `.whop-CardField` | Campo de número de tarjeta, fecha de vencimiento o código de seguridad |
| `.whop-CardFieldError` | Mensaje de validación de la tarjeta |
| `.whop-CardFieldGroup` | Campos apilados de número de tarjeta, fecha de vencimiento y código de seguridad |
| `.whop-CardFieldInput` | Contenedor con borde del campo PCI |
| `.whop-CardFieldInputFocused` | Contenedor del campo PCI con foco |
| `.whop-CardFieldInputInvalid` | Contenedor del campo PCI no válido o incompleto |
| `.whop-CardFieldRow` | Fila compacta de número de tarjeta, fecha de vencimiento y código de seguridad |

```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' } } }
});
```

En React, pasa `appearance` a `<Payments>`. Establécelo globalmente con `WhopElements({ appearance })`.

## Parámetros

**layout** `WhopCardElement.Layout`

`.stacked` coloca el número encima de la fecha de vencimiento y el código de seguridad; `.compact` coloca los tres en una fila. El valor predeterminado es `.stacked`.

**publicKey** `String?`

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

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

Devuelve si está completo y la marca detectada.

## `WhopCardState`

Lo que devuelve una selección:

* `isComplete: Bool`: los tres campos son válidos
* `brand: String?`: la red detectada, una vez que el número identifica una

## Estados

Se renderiza inmediatamente y valida a medida que el comprador escribe. La marca aparece una vez que el número identifica una. `state.isComplete` pasa a ser true cuando los tres campos son válidos.

## Información útil

* Úsalo en lugar de [`WhopPaymentElement`](https://docs.whop.com/es/elements/latest/payments/payment#swift) cuando la tarjeta es el único método que aceptas. Montar ambos genera un conflicto: el controlador emite el token desde una única superficie de recopilación.
* `createConfirmationToken(billingDetails:)` necesita el nombre del titular de la tarjeta para el pago con tarjeta, así que pasa uno o monta un elemento de dirección que lo recopile.
* `publicKey` es una vía de escape avanzada. Si la omites, el SDK obtiene la clave del tokenizador de la cuenta.

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

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

`stacked` coloca el número encima de la fecha de vencimiento y el código de seguridad. `compact` coloca los tres en una fila. El valor predeterminado es `stacked`.

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

Se dispara en cada edición con el estado de completitud y los errores por campo.

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

Se aplica al `View` exterior del elemento. Para la personalización del tema, es preferible `appearance.parts` en el provider, que cubre todos los elementos de esta superficie. Ten en cuenta que, por ahora, los nombres de las partes de React Native son un conjunto propio, no los nombres de clase `whop-*` de la web, por lo que un objeto de appearance de la web no se puede trasladar sin cambios.

**fallback** `ReactNode`

Se renderiza en lugar del esqueleto integrado mientras el elemento se carga.

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

Se dispara una vez que el elemento es interactivo. `<Payments>` los agrupa, así que normalmente lo que quieres es su propio `onLoadingChange`.

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

Un fallo de carga o de configuración de este elemento. En cualquier caso, el elemento renderiza su propia vista de error.

## `CardFieldsChangePayload`

Lo que devuelve `onChange`:

* `complete: boolean`: todos los campos están rellenos y son válidos
* `errors: Record<string, string>`: mensajes por campo, vacío exactamente cuando `complete` es true

## Estados

Los tres campos se renderizan juntos una vez que se resuelve la clave publicable. `onChange` informa de `complete` cuando los tres son válidos, y el elemento muestra sus propios errores por campo.

## 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.
* Al montarlo, la tarjeta pasa a ser la superficie de recopilación del provider, por lo que `createConfirmationToken` la tokeniza sin conexiones adicionales. No lo montes junto a un `PaymentElement`: solo hay una superficie de recopilación activa a la vez.
* Para un formulario en el que los tres campos se colocan en tu propio diseño, usa [`CardFields`](https://docs.whop.com/es/elements/latest/payments/cardFields) en su lugar.

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


## Related topics

- [CardFields](https://docs.whop.com/es/elements/latest/payments/cardFields.md)
- [Primeros pasos con Elements](https://docs.whop.com/es/elements/latest/getting-started.md)
- [PaymentElement](https://docs.whop.com/es/elements/latest/payments/payment.md)
