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

# Primeros pasos con Elements

> Instala Whop Elements y monta tu primer elemento en React, JavaScript, Swift o React Native.

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

Whop Elements son componentes de interfaz alojados y personalizables que incrustas en tu propio sitio. Cada elemento se renderiza en un frame aislado servido desde la CDN de Whop. Instalas un paquete ligero y completamente tipado, y el código de los elementos se mantiene actualizado por sí solo.

Whop Elements son componentes de interfaz personalizables que puedes importar en tu app de iOS. Se distribuyen como un único paquete SPM de Swift. Cada uno es una vista SwiftUI normal que obtiene sus propios datos y gestiona su propio estado, de modo que una pantalla de saldo son un par de vistas en un `VStack` en lugar de una capa de red y un view model. Añade el paquete, indica al SDK cómo obtener un token de acceso y coloca los elementos en tu jerarquía de vistas.

Whop Elements son componentes de interfaz personalizables que puedes incorporar a una app de React Native. Son componentes reales de React Native, no web views: los mosaicos de métodos de pago, el formulario de dirección y los campos de tarjeta son todos entradas nativas, y Apple Pay y Google Pay abren la hoja propia de la plataforma. Instala el paquete, indica al SDK cómo obtener un token de acceso y monta los elementos.

## Instalación

Añade el paquete a tu `Package.swift` (o usa **File → Add Package Dependencies** en Xcode):

Instala el SDK:

```bash React theme={null}
npm install @whop/elements-react @whop/elements
```

```bash React Native theme={null}
npm install @whop/elements-react-native
```

```bash JavaScript theme={null}
npm install @whop/elements
```

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

## Requisitos

| | |
| - | - |
| React | `^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0`, para `@whop/elements-react`. |
| Política de seguridad de contenido (CSP) | Tu política necesita todas las fuentes de la [tabla de Content Security Policy](#content-security-policy) que aparece a continuación. |

### Política de seguridad de contenido

| Requisito | Directiva | Fuente en producción | Fuente en sandbox |
| - | - | - | - |
| Frames de Elements | `frame-src` | `https://cdn.whop.com` | Igual |
| La etiqueta script, si la cargas | `script-src` | `https://cdn.whop.com` | Igual |
| La API de Whop | `connect-src` | `https://api.whop.com` | `https://sandbox-api.whop.com` |
| El píxel de Whop | `script-src` | `https://t.whop.tw` | Ninguna |
| El píxel de Whop | `connect-src` | `https://t.whop.tw` | Ninguna |
| Apple Pay, Google Pay y PayPal | `frame-src` | `https://checkout.paypal.com` `https://assets.braintreegateway.com` `https://www.paypal.com` | `https://checkout.paypal.com` `https://assets.braintreegateway.com` `https://www.sandbox.paypal.com` |
| Apple Pay, Google Pay y PayPal | `script-src` | `https://pay.google.com` `https://applepay.cdn-apple.com` `https://js.braintreegateway.com` `https://assets.braintreegateway.com` `https://www.paypal.com` `https://c.paypal.com` | `https://pay.google.com` `https://applepay.cdn-apple.com` `https://js.braintreegateway.com` `https://assets.braintreegateway.com` `https://www.sandbox.paypal.com` `https://c.paypal.com` |
| Apple Pay, Google Pay y PayPal | `connect-src` | `https://pay.google.com` `https://google.com` `https://account.google.com` `https://www.google.com` `https://api.basistheory.com` `https://payments.braintree-api.com` `https://api.braintreegateway.com` `https://api-m.paypal.com` `https://www.paypal.com` | `https://pay.google.com` `https://google.com` `https://account.google.com` `https://www.google.com` `https://api.basistheory.com` `https://payments.sandbox.braintree-api.com` `https://api.sandbox.braintreegateway.com` `https://api-m.sandbox.paypal.com` `https://www.sandbox.paypal.com` |
| Apple Pay, Google Pay y PayPal | `img-src` | `https://www.paypalobjects.com` | Igual |
| Vinculación de cuentas bancarias con Plaid | `frame-src` | `https://cdn.plaid.com` | Igual |
| Vinculación de cuentas bancarias con Plaid | `script-src` | `https://cdn.plaid.com` | Igual |
| Vinculación de cuentas bancarias con Plaid | `connect-src` | `https://production.plaid.com` | `https://sandbox.plaid.com` |

`contentSecurityPolicy()` de `@whop/elements` devuelve todas las fuentes de esta tabla para el entorno que le pases. Las filas del trabajo del lado de la página se ejecutan en tu página, no en un frame. Los scripts que cargan los elementos para Apple Pay, Google Pay y PayPal y para la vinculación de cuentas bancarias con Plaid provienen de otras empresas y pueden cargar recursos más allá de estas filas. Consulta también las indicaciones sobre Content Security Policy de cada proveedor.

> [!WARNING]
>
> Los elementos se renderizan en frames servidos desde `cdn.whop.com`. Parte de su trabajo se ejecuta en tu página y llama a `api.whop.com` desde ella, como Apple Pay, Google Pay y PayPal y la vinculación de cuentas bancarias con Plaid. Si tu CSP bloquea cualquiera de los dos orígenes, obtienes un espacio en blanco en lugar del elemento o una solicitud fallida, y el error solo aparece en la consola del navegador.

> [!NOTE]
>
> Un elemento modal oscurece tu página detrás de él con un estilo en línea. Un `style-src` que no permite estilos en línea deja la página sin oscurecer, pero el modal sigue funcionando.

## Antes de empezar

Necesitas dos cosas:

1. **Un `accountId`.** Un ID de cuenta, con prefijo `biz_`, o un ID de usuario, con prefijo `user_`, para los datos propios del usuario. Las superficies de pago aceptan en su lugar un plan o un importe, y cada página de elemento indica cuál necesita.
2. **Un endpoint de servidor que cree un token de acceso**, con el alcance de los elementos que montes.

> [!WARNING]
>
> Nunca pongas una clave de API de Whop en código del navegador. Crea tokens, así que cualquiera que abra las herramientas de desarrollo del navegador puede leer la cuenta. Crea el token en tu servidor y envía solo el token.

Tu servidor llama a [Create Access Token](https://docs.whop.com/es/api-reference/access-tokens/create-access-token.md) con la cuenta y los alcances que necesitan los elementos:

```http theme={null}
POST https://api.whop.com/api/v1/access_tokens
Authorization: Bearer <api_key>
Content-Type: application/json

{ "company_id": "biz_xxxxxxxx", "scoped_actions": ["company:balance:read"] }
```

## Requisitos

| | |
| - | - |
| Plataforma | iOS 18.0+ |
| Herramientas | Swift 6.0 |
| Instalación | Swift Package Manager |

## Antes de empezar

Necesitas dos cosas:

1. **Un `accountId`.** Un ID de cuenta, con prefijo `biz_`, o un ID de usuario, con prefijo `user_`, para el saldo propio del usuario.
2. **Un endpoint de servidor que cree un token de acceso** para la cuenta. Nunca incluyas una clave de API de Whop en la app. Crea tokens, así que cualquiera que la extraiga puede leer la cuenta. Crea el token en tu servidor y devuelve solo eso.

Una etiqueta `user_…` lee los datos propios del visitante, por lo que usa OAuth del visitante (`WhopSDK.configureWithOAuth`) en lugar de un token. Las vistas de chat también.

Tu servidor llama a [Create Access Token](https://docs.whop.com/es/api-reference/access-tokens/create-access-token.md) con la cuenta y el alcance que necesitan los elementos:

```http theme={null}
POST https://api.whop.com/api/v1/access_tokens
Authorization: Bearer <api_key>
Content-Type: application/json

{ "company_id": "biz_xxxxxxxx", "scoped_actions": ["company:balance:read"] }
```

## Requisitos

| | |
| - | - |
| React Native | `0.87+` con Swift Package Manager, `0.86+` con CocoaPods. New Architecture (Fabric) habilitada |
| React | `19.2.3+` |
| iOS | 15.1+ |
| Android | `minSdk 24`, `compileSdk 37` |

> [!NOTE]
>
> **Funciona cualquiera de los dos gestores de dependencias de iOS.** El paquete incluye tanto un `ios/Package.swift` como un podspec, y las herramientas eligen uno. El autolinker de Swift Package Manager de React Native prefiere el `Package.swift`, así que el podspec no afecta a una app que ya usa SPM. Una app con CocoaPods, lo que hoy incluye todas las apps de Expo, se vincula mediante el podspec y no necesita nada más. La versión mínima de React Native es más alta con SPM porque `Package.swift` vincula dos XCFrameworks de solo cabeceras que se publicaron por primera vez en 0.87.

> [!NOTE]
>
> El código nativo es Swift y Kotlin generado mediante React Native Codegen: nada aquí te pide editar a mano Objective-C o Java, y no hay dependencias nativas complementarias que instalar.

## Antes de empezar

Necesitas dos cosas:

1. **Un `accountId`.** Un ID de empresa, con prefijo `biz_`.
2. **Un endpoint de servidor que genere un token de acceso** para esa cuenta. Nunca incluyas una clave de API de Whop en la app: crea tokens, así que cualquiera que la extraiga puede actuar como la cuenta. Genera el token en tu servidor y devuelve solo eso.

Tu servidor llama a [Create Access Token](https://docs.whop.com/es/api-reference/access-tokens/create-access-token.md) y devuelve el resultado a `getToken`.

## Monta tu primer elemento

Una app completa. `configure` se ejecuta una vez al iniciar, y los elementos muestran un indicador de carga hasta que termina, así que nada compite con él:

Un checkout completo. `<WhopElements>` contiene el resolvedor del token, `<Payments>` contiene el cobro y los elementos entre ellos lo recopilan:

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <PaymentElement />
        <AddressElement />
        <CardElement />
        <EmailElement />
        <TaxIdElement />
        <BrandingElement />
      </Payments>
    </WhopElements>
  );
}
```

```tsx React Native theme={null}
import { useRef, useState } from 'react';
import { Button, ScrollView } from 'react-native';
import {
  AddressElement,
  BrandingElement,
  EmailElement,
  PaymentElement,
  Payments,
  WhopElements,
  type PaymentsHandle,
} from '@whop/elements-react-native';

export function Checkout() {
  const payments = useRef<PaymentsHandle | null>(null);
  const [ready, setReady] = useState(false);

  return (
    // Called again before every request, so fetch rather than cache.
    <WhopElements getToken={() => myBackend.whopAccessToken()}>
      <Payments ref={payments} accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
        <ScrollView>
          <EmailElement />
          <AddressElement />
          <PaymentElement onChange={(p) => setReady(p.complete)} />
          <BrandingElement />
        </ScrollView>
        <Button
          title="Pay"
          disabled={!ready}
          onPress={async () => {
            const token = await payments.current!.createConfirmationToken();
            // Confirm server-side, then hand the payment's client_secret back:
            // await payments.current!.handleNextAction({ clientSecret });
            console.log(token.confirmationToken);
          }}
        />
      </Payments>
    </WhopElements>
  );
}
```

```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('payment').mount('#payments-payment');
  payments.create('address').mount('#payments-address');
  payments.create('card').mount('#payments-card');
  payments.create('email').mount('#payments-email');
  payments.create('taxId').mount('#payments-taxId');
  payments.create('branding').mount('#payments-branding');
</script>
```

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

/// The SDK calls this again before the token expires, so fetch rather than cache.
final class WalletTokenProvider: WhopTokenProvider {
    func getToken() async -> WhopTokenResponse {
        WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
    }
}

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            WalletScreen()
                .task { await WhopSDK.configure(tokenProvider: WalletTokenProvider()) }
        }
    }
}

struct WalletScreen: View {
    var body: some View {
        ScrollView {
            VStack(spacing: 24) {
                BalanceElement(accountId: "biz_xxxxxxxx")
                ListElement(accountId: "biz_xxxxxxxx")
            }
            .padding()
        }
    }
}
```

¿Prefieres npm en lugar de la etiqueta script? `loadWhop()` inyecta el mismo script alojado y resuelve el constructor global:

```ts theme={null}
import { loadWhop } from "@whop/elements";

const whop = (await loadWhop())({ locale: "en" });
const payments = whop.payments.create({ /* options */ });
```

## Autenticación

Pasa un `accessToken` al crear el handle. **Usa un token para todo el handle, no uno por elemento.** El handle envía ese token a todos los elementos que contiene, así que solicita en ese único token todos los alcances que necesites. Cada página de elemento enumera los alcances que lee.

```tsx React theme={null}
<Ads accountId="biz_xxxxxxxx" accessToken={token}>
  {/* elements */}
</Ads>
```

```ts JavaScript theme={null}
const ads = whop.ads.create({ accountId: "biz_xxxxxxxx", accessToken });
```

El token es un valor que estableces tú, no un callback al que llama el SDK. Establece uno nuevo antes de que caduque:

```ts theme={null}
ads.update({ accessToken: await createAccessToken() });
```

> [!NOTE]
>
> Si omites `accessToken`, las solicitudes usan en su lugar la cookie de sesión del visitante. Esto funciona **solo en whop.com**. La API no envía `Access-Control-Allow-Credentials` en las solicitudes preflight de origen cruzado, así que una página en tu propio dominio no tiene ninguna sesión a la que recurrir y debe pasar un token.

## Configuración global

Todo lo que pasas en la construcción se aplica a todos los grupos de elementos creados a partir de esa instancia (las opciones propias de un handle pueden anularlo por grupo):

**appearance** `Appearance`

Personalización visual para todos los elementos: `theme` (claro/oscuro + paletas), `variables` (propiedades personalizadas de CSS) y `classes` (declaraciones de estilo por parte). El esquema de color se aplica antes del primer pintado de un elemento, así que las páginas oscuras nunca muestran un destello claro. Consulta [Appearance](https://docs.whop.com/es/elements/latest/appearance.md).

**locale** `string`

Configuración regional para el texto de la interfaz de los elementos: una de las configuraciones regionales incluidas en la app; cualquier otro valor recurre a la configuración regional predeterminada. Por defecto es `"en"`.

Uno de `"en"`, `"es"`, `"zh"`, `"nl"`, `"pt"`, `"de"`, `"hu"`, `"it"`, `"fr"`, `"ja"`, `"pl"` o `"tr"`.

**environment** `"production" | "sandbox"`

Con qué entorno de la API de Whop se comunican los elementos: `"sandbox"` apunta a la API de sandbox (datos de prueba; no se mueve dinero real). Elegir un entorno es la única forma de cambiar adónde envían los elementos lo que escribe un comprador, y ambos entornos son de Whop. El entorno sandbox todavía no está disponible de forma general. Por defecto es `"production"`.

**toasts** `boolean`

Si los elementos pueden mostrar notificaciones toast en tu página: mensajes de estado breves ("Payment method added", "Payment failed") que se muestran en la esquina inferior derecha. Establécelo en `false` para desactivarlas por completo. Por defecto es `true`.

**skipPixel** `boolean`

Omite el píxel de Whop. Por defecto, los elementos cargan el píxel de anuncios de Whop en una página que todavía no lo ejecuta, limitado a la cuenta para la que trabajan (el `accountId` de un grupo de elementos, o el vendedor del plan de un checkout), y vinculan las analíticas de los elementos al ID de visitante del píxel, un vínculo de identidad único que permite unir la actividad de los elementos con tus datos de atribución de anuncios en el grafo de identidad de Whop. Establécelo en `true` para no hacer ninguna de las dos cosas. Las analíticas de uso en sí no se ven afectadas (desactívalas por handle con `analytics: false`). Por defecto es `false`.

```ts theme={null}
const whop = WhopElements({
  locale: 'es',
  appearance: { theme: { appearance: 'dark', accentColor: 'blue' } }
});
```

En React, el mismo objeto se pasa en `<WhopElements appearance={…} locale={…}>`.

La opción global `toasts` está activa en esta página: el botón de abajo envía una a través del mismo canal que usan los elementos, con el tema del `appearance` de esta página:

## De qué se encargan los elementos y de qué te encargas tú

Cada elemento obtiene sus propios datos y renderiza sus propios estados de carga, vacío y error.

Tú te encargas de la **navegación y el almacenamiento**. Los elementos informan de las selecciones y los resultados como eventos, y nunca escriben en tu base de datos.

La excepción es un flujo que sale de la página. Cuando un elemento acepta una `returnUrl`, navega la pestaña hasta ella, por lo que el comprador puede acabar fuera de tu página. El comprador llega ahí tanto después de un paso externo fallido o abandonado como después de uno exitoso, con `status` (`succeeded`, `failed` o `canceled`) y el ID del intento añadidos a la URL, así que la página en `returnUrl` tiene que leer `status` antes de mostrar un mensaje de éxito. Realiza el cumplimiento a partir de webhooks en lugar de un callback del navegador.

Los elementos se ejecutan en frames, así que solo los valores serializables cruzan el límite. No hay DOM compartido y la identidad de los objetos no se conserva.

## Solución de problemas

| Lo que ves | Por qué |
| - | - |
| Un espacio en blanco en lugar del elemento | Tu CSP bloquea `cdn.whop.com`. Añádelo a `frame-src`, y a `script-src` si usas la etiqueta script. |
| La consola muestra una infracción de Content Security Policy | A tu política le falta una fuente. Compárala con la tabla de Requisitos. `contentSecurityPolicy()` devuelve todas las fuentes de esa tabla, y el script de otra empresa puede necesitar más fuentes propias. |
| `mount()` no hace nada | El selector no coincidió con ningún nodo. El destino ya debe estar en el DOM. |
| El elemento se carga pero permanece vacío | Al token le falta un alcance que lee ese elemento. Revisa los alcances indicados en la página del elemento. |
| Las solicitudes fallan en tu propio dominio | No se pasó ningún token. El recurso a la sesión solo funciona en whop.com. |
| Funcionaba y dejó de funcionar | El token caducó. Crea uno nuevo y pásalo con `update({ accessToken })`. |

## Elementos disponibles

> [card] [Payments](https://docs.whop.com/es/elements/latest/payments/overview)
>
> Cobra un pago a partir de un ID `plan_` o de una moneda e importe en línea, o guarda un método de pago sin cobrar con `mode: "setup"`.

> [card] [Verifications](https://docs.whop.com/es/elements/latest/verifications/overview)
>
> Recopila y verifica la información de identidad de una cuenta.

> [card] [Checkout](https://docs.whop.com/es/elements/latest/checkout/overview)
>
> Gestiona un checkout alojado completo para uno o más planes (resumen de precios detallado, códigos promocionales, la moneda en la que paga el comprador y toda la superficie de cobro, con los elementos de pagos compuestos dentro) contra la API de sesiones de checkout de Whop.

> [card] [Ads](https://docs.whop.com/es/elements/latest/ads/overview)
>
> Una cuenta publicitaria.

> [card] [Tracking](https://docs.whop.com/es/elements/latest/tracking/overview)
>
> La audiencia rastreada de una cuenta: todas las personas que ha visto su píxel y todos los eventos que realizaron.

> [card] [Wallet](https://docs.whop.com/es/elements/latest/wallet/overview)
>
> Gestiona las superficies de dinero de una cuenta.

> [card] [Websites](https://docs.whop.com/es/elements/latest/websites/overview)
>
> Los sitios web de una cuenta: todos los sitios creados en whop.site más todos los dominios de los que informa el Whop Pixel, con el tráfico y los ingresos atribuidos por dominio.

> [card] [Dashboard](https://docs.whop.com/es/elements/latest/dashboard/overview)
>
> Las superficies del propio panel de una cuenta, incrustadas en tu sitio.

> [card] [Delivery](https://docs.whop.com/es/elements/latest/delivery/overview)
>
> Seguimiento de entregas para los clientes de una empresa.

> [card] [Chat](https://docs.whop.com/es/elements/latest/chat/overview)
>
> Chat en tiempo real con una lista de canales y búsqueda de mensajes.

## Siguientes pasos

* [Appearance](https://docs.whop.com/es/elements/latest/appearance.md): temas, variables CSS y cambio de estilo por parte
* [Create Access Token](https://docs.whop.com/es/api-reference/access-tokens/create-access-token.md): el endpoint con el que tu servidor genera tokens

## Autenticación

`getToken()` es tu único punto de integración, y el SDK lo llama **de nuevo antes de que caduque el token**, así que devuelve un token nuevo cada vez en lugar de almacenar uno en caché:

```swift theme={null}
final class WalletTokenProvider: WhopTokenProvider {
    func getToken() async -> WhopTokenResponse {
        // your backend, not the Whop API directly
        WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
    }
}
```

Configúralo una vez, en cualquier lugar por encima de los elementos. `WhopSDK` es global para el proceso, así que solo hace falta una segunda llamada cuando cambia la cuenta:

```swift theme={null}
await WhopSDK.configure(tokenProvider: WalletTokenProvider())
```

El chat y los mensajes directos autentican al **visitante** en lugar de a una cuenta, mediante OAuth: `WhopSDK.configureWithOAuth(appId:)`.

## Temas

`.whopTheme(_:)` se propaga a través del entorno de SwiftUI, así que una sola llamada aplica el tema a todos los elementos que hay debajo. Seis roles, cada uno un `WhopTint`:

```swift theme={null}
ListElement(accountId: "biz_xxxxxxxx")
    .whopTheme(WhopTheme(accent: .blue, danger: .red, success: .green))
```

Los valores por defecto son `accent: .blue`, `neutral: .gray`, `danger: .red`, `info: .sky`, `success: .green`, `warning: .amber`. `WhopTheme.default` incluye los seis. Las vistas siguen por sí solas la apariencia clara/oscura del sistema.

## De qué se encargan los elementos y de qué te encargas tú

Cada vista obtiene sus propios datos y renderiza sus propios estados de carga, vacío y error, incluido un reintento. Tú te encargas de la **navegación**: los callbacks de selección te entregan un valor y nunca abren una pantalla.

```swift theme={null}
ListElement(accountId: account) { balance in
    path.append(Route.asset(balance.symbol))   // your router, your screen
}
```

## Solución de problemas

| Lo que ves | Por qué |
| - | - |
| `Authentication failed` | El token falta, ha caducado o es una **clave de API** en lugar de un token de acceso. `getToken()` debe devolver un token generado por [Create Access Token](https://docs.whop.com/es/api-reference/access-tokens/create-access-token.md). |
| Una vista permanece vacía | El token es válido pero no tiene el alcance para esa lectura. Los saldos necesitan `company:balance:read`. |
| `Couldn't load this account` | El `accountId` no es uno que este token pueda leer. |
| Un gráfico sin línea | El historial de saldo solo está disponible para IDs de cuenta con prefijo `biz_`, no para cuentas personales con prefijo `user_`. |

## Disponible en iOS

Las vistas de wallet, cada una con un simulador en vivo en su página:

* [`BalanceElement`](https://docs.whop.com/es/elements/latest/wallet/balances-balance#swift): el saldo total, su tendencia y el selector de rango
* [`ListElement`](https://docs.whop.com/es/elements/latest/wallet/balances-list#swift): la lista de activos
* [`ActivityElement`](https://docs.whop.com/es/elements/latest/wallet/activity#swift): el feed de actividad del libro contable

`WhopChatView` y `WhopDMsListView` se incluyen en el mismo paquete para el chat autenticado por el visitante. Consulta el [README](https://github.com/whopio/whopsdk-elements-swift).

## Payments en iOS

Los elementos de pagos se distribuyen en su propio paquete, [`whopio/elements-swift`](https://github.com/whopio/elements-swift), que ofrece un módulo `Elements`. El módulo del SDK de wallet es `WhopElements`, así que ambos se instalan uno junto al otro:

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

El módulo es `Elements`, no `WhopElements`, así que `import Elements` es la única línea que cambia. La configuración también es distinta y se divide como lo hace SwiftUI: la configuración se hereda desde la raíz de la app, y un cobro es un ámbito. Nada necesita un token, porque el token de confirmación se genera a partir de lo que escribió el comprador y se confirma en tu servidor:

```swift theme={null}
// once, at the app root
WindowGroup {
    CheckoutScreen()
        .whopElements(environment: .production)
}

// one charge, and the elements that collect for it
WhopPayments(accountID: "biz_xxxxxxxx", charge: .plan(id: "plan_xxxxxxxx")) { payments in
    WhopEmailElement()
    WhopPaymentElement()
    WhopBrandingElement()
    Button("Pay") { Task { try await payments.createConfirmationToken() } }
        .disabled(!payments.isComplete)
}
```

* [`WhopPaymentElement`](https://docs.whop.com/es/elements/latest/payments/payment#swift): los mosaicos de métodos y lo que recopile el método seleccionado
* [`WhopCardElement`](https://docs.whop.com/es/elements/latest/payments/card#swift) y [`WhopCardFields`](https://docs.whop.com/es/elements/latest/payments/cardFields#swift): los campos de tarjeta alojados, como una sola unidad o colocados uno a uno
* [`WhopAddressElement`](https://docs.whop.com/es/elements/latest/payments/address#swift): la dirección de facturación, en el formato propio del país
* [`WhopEmailElement`](https://docs.whop.com/es/elements/latest/payments/email#swift) y [`WhopTaxIDElement`](https://docs.whop.com/es/elements/latest/payments/taxId#swift)
* [`WhopBrandingElement`](https://docs.whop.com/es/elements/latest/payments/branding#swift): obligatorio junto a cualquier superficie de pago
* [`WhopPaymentRequest`](https://docs.whop.com/es/elements/latest/payments/paymentRequest#swift): Apple Pay sin ningún elemento montado

Los datos de la tarjeta se capturan mediante campos alojados aislados según PCI y nunca entran en tu proceso. Aplica estilo a todo con `.whopElementsAppearance(_:)` en lugar de `.whopTheme(_:)`.

## Autenticación

`getToken` es tu único punto de integración, y el SDK lo llama **antes de cada solicitud**, así que devuelve un token nuevo en lugar de almacenar uno en caché:

```tsx theme={null}
<WhopElements getToken={async () => (await fetch('/api/whop-token')).text()}>
  {/* your app */}
</WhopElements>
```

Un elemento que no necesita credenciales funciona sin él, así que puedes renderizar un formulario de tarjeta antes de conectar tu backend.

## Cobrar un pago

La recopilación y la confirmación están separadas, y la separación es deliberada: la app nunca ve un número de tarjeta y tu servidor nunca confía en el cliente.

1. Los elementos recopilan. Los números de tarjeta van directamente de los campos aislados según PCI a un token, nunca a través de tu código.
2. `createConfirmationToken()` devuelve un **token de confirmación**, que es seguro enviar a tu propio backend.
3. Tu backend confirma el pago con la API de Whop.
4. Si la API responde que el pago necesita algo más del comprador, pasa su `client_secret` a `handleNextAction()` y el SDK ejecuta el paso de 3D Secure o de redirección.

```tsx theme={null}
const token = await payments.current!.createConfirmationToken();
const { status, clientSecret } = await myBackend.confirm(token.confirmationToken);
if (status === 'requires_action') await payments.current!.handleNextAction({ clientSecret });
```

## Redirecciones y 3D Secure

Los pasos fuera de la app abren el **navegador del sistema** (`ASWebAuthenticationSession` en iOS, Custom Tabs en Android), nunca un WebView, de modo que la página del emisor queda fuera del límite de confianza de tu app y sus cookies quedan fuera del almacén de tu app.

Establece `returnUrl` en `<Payments>` en una URL **https** que alojes tú. La API rechaza cualquier cosa que no sea https o loopback (`PaymentsApi::ValidateReturnUrl`), así que un esquema de app personalizado no funcionará aquí, y tampoco lo necesitas: `handleNextAction` consulta el pago hasta que se resuelve y cierra el navegador por sí mismo, en lugar de esperar un deep link de vuelta a tu app.

```tsx theme={null}
<Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx" returnUrl="https://example.com/checkout/return">
```

## Apple Pay y Google Pay

Los mosaicos de monedero aparecen una vez que la plataforma puede presentar una hoja, y no hay nada que configurar para ninguno de los dos. Apple Pay usa el comerciante registrado en la cuenta de Whop, así que tu app no necesita identificador de comerciante ni capability de Xcode. `googlePayMerchantName` en `<Payments>` solo establece el nombre que se muestra en la hoja.

## Temas

`appearance` en `<WhopElements>` aplica el tema a todos los elementos que hay debajo, con el mismo objeto `theme` que aceptan los elementos web. Consulta [Appearance](https://docs.whop.com/es/elements/latest/appearance.md).

## De qué se encargan los elementos y de qué te encargas tú

Cada elemento obtiene sus propios datos y renderiza sus propios estados de carga, vacío y error. Tú te encargas de la **navegación y el envío**: los elementos informan mediante `onChange` y nunca abren una pantalla ni llaman a tu backend.

## Solución de problemas

| Lo que ves | Por qué |
| - | - |
| `BrandingRequiredError` al confirmar | No hay ningún `BrandingElement` montado. Monta uno dentro de `<Payments>`. |
| `ChargeConfigError` | `<Payments>` no tiene ni un `plan` ni un par de `amount` y `currency`. |
| No aparece ningún mosaico de monedero | La cuenta no tiene ningún comerciante de Apple Pay registrado, o el dispositivo no puede presentar una hoja. |
| Los mosaicos de métodos nunca aparecen | `getToken` está devolviendo una clave de API en lugar de un token de acceso, o el token no tiene alcance para la cuenta. |
| Un campo de tarjeta en blanco | La compilación nativa es anterior al paquete. `@basis-theory/react-native-elements` se instala con él, así que vuelve a compilar en lugar de añadirlo a mano. |

## Disponible en React Native

Los elementos de pagos:

* [`PaymentElement`](https://docs.whop.com/es/elements/latest/payments/payment): los mosaicos de métodos y todo lo que necesita el método seleccionado
* [`AddressElement`](https://docs.whop.com/es/elements/latest/payments/address): la dirección de facturación en el formato del propio país del comprador
* [`CardElement`](https://docs.whop.com/es/elements/latest/payments/card): número, vencimiento y código de seguridad como un solo componente
* [`CardFields`](https://docs.whop.com/es/elements/latest/payments/cardFields): los mismos tres campos, colocados individualmente
* [`EmailElement`](https://docs.whop.com/es/elements/latest/payments/email): el correo electrónico del comprador
* [`TaxIdElement`](https://docs.whop.com/es/elements/latest/payments/taxId): un tipo y número de registro
* [`BrandingElement`](https://docs.whop.com/es/elements/latest/payments/branding): la marca Powered by Whop, obligatoria en todo formulario

Los elementos de checkout:

* [`ExpressCheckoutElement`](https://docs.whop.com/es/elements/latest/checkout/expressCheckout): una pulsación de Apple Pay o Google Pay que paga todo un checkout, dentro de `<Checkout>`


## Related topics

- [Primeros pasos con Element Sessions](https://docs.whop.com/es/sdk/elements/whop-elements.md)
- [Habilitar pagos salientes de subcuentas](https://docs.whop.com/es/developer/platforms/render-payout-portal.md)
- [ListElement](https://docs.whop.com/es/elements/latest/wallet/balances-list.md)
