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

# Payments

> Cobra un pago a partir de un ID `plan_` o de una moneda y un importe en línea, o guarda un método de pago sin cobrar con `mode: "setup"`. Monta PaymentElement, CardElement o CardFields y luego llama a `payments.createConfirmationToken` con los datos de facturación. Las selecciones de billetera abren su hoja automáticamente. Cuando la cuenta ofrece vinculación bancaria en la página (`bank_debit.bank_connection` en su tipo de método de pago de cuenta bancaria), seleccionar una cuenta bancaria también abre Plaid Link en la página. Si el comprador cierra cualquiera de las dos, la llamada se rechaza con `payment_request_cancelled`, que tu handler de pago debe tratar como una cancelación. Confirma el token en el servidor y luego pasa el `client_secret` del pago o del setup intent a `handleNextAction` para cualquier paso pendiente.

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

*Desde `v1.0.0`.*

## Playground

Combina los elementos con datos de ejemplo. Usa los controles, añade y organiza elementos, y observa cómo se disparan los eventos en vivo:

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        {/* mount elements here */}
      </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 */ });
</script>
```

## Opciones

Pásalas a `whop.payments.create({ … })`, o como props de `<Payments>` en React.

> [!NOTE]
>
> Pasa exactamente una de estas combinaciones:
>
> * `accountId` y `plan`
> * `accountId`, `currency` y `amount`
> * `accountId`, `mode: "setup"` y `currency`
> * ninguno de `plan`, `currency`, `amount` o `mode`

**accountId** `string`

ID de la cuenta, con el prefijo `biz_`. Omítelo solo al llamar a métodos estáticos sin una superficie de cuenta.

**mode** `"payment" | "setup"`

Modo de montaje, `payment` de forma predeterminada. `setup` guarda un método de pago y no cobra nada, ni ahora ni después: solo se ofrecen los métodos que se pueden guardar y no se aplican los límites de importe. Confirma con `createConfirmationToken()` y luego crea el setup intent en el servidor.

**plan** `string`

ID del plan, con el prefijo `plan_`. Se resuelve en el cliente en la moneda, el importe y la configuración de métodos. Pasa un plan o una moneda y un importe en línea, nunca ambos.

**offerAmounts** `object`

Totales `feeInclusive` y `feeFree` en unidades menores que se usan para filtrar los métodos cuando el checkout recalcula `amount` para un método sin comisión, como BNPL. Cada método se compara con su total correspondiente, lo que evita que desaparezca el método sin comisión seleccionado. Si se omite, `amount` filtra todos los métodos.

**propiedades**

**feeInclusive** `number` *required*

**feeFree** `number` *required*

**returnUrl** `string`

URL de retorno para pasos bancarios externos o de 3DS. De forma predeterminada, es la página de montaje. El comprador llega ahí sea cual sea el resultado, con `payment` (o `setup`), `status` (`succeeded`, `failed`, `canceled` o un estado aún pendiente como `processing`) y `client_secret` añadidos, así que ramifica según `status` antes de mostrar una página de éxito.

**setupFutureUsage** `"off_session" | "on_session"`

Un setup guarda el método de pago para uso `off_session`, el único uso que acepta un setup.

**previewWalletAvailability** `WalletAvailability`

Anulación de la disponibilidad de billeteras para vistas previas deterministas. Los checkouts en vivo sondean el host.

**propiedades**

**applePay** `boolean` *required*

**googlePay** `boolean` *required*

**payPal** `boolean`

**order** `("apple_pay" | "google_pay" | "paypal_express")[]`

Las billeteras ordenadas según qué hoja es nativa de este navegador (Apple Pay primero en WebKit, Google Pay primero en todos los demás, PayPal al final), para que los botones exprés se apilen empezando por el mejor. Ausente en la disponibilidad indicada por el consumidor (vistas previas) y en los formatos de datos anteriores a ella. Una unión en línea, no el WalletSheetType de payment-request: ese módulo ya importa este.

**wallets** `object`

Los detalles de cada billetera disponible, con el tipo de billetera como clave. Ausente en la disponibilidad indicada por el consumidor (vistas previas).

**propiedades**

**apple\_pay** `WalletDetails`

**propiedades**

**button** `WalletButtonArt`

El diseño oficial del botón de la billetera. Ausente cuando no se ha publicado ninguno.

**propiedades**

**light** `object` *required*

Para páginas claras.

**propiedades**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

Para páginas oscuras.

**propiedades**

**color** `string` *required*

**image** `string` *required*

**google\_pay** `WalletDetails`

**propiedades**

**button** `WalletButtonArt`

El diseño oficial del botón de la billetera. Ausente cuando no se ha publicado ninguno.

**propiedades**

**light** `object` *required*

Para páginas claras.

**propiedades**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

Para páginas oscuras.

**propiedades**

**color** `string` *required*

**image** `string` *required*

**paypal\_express** `WalletDetails`

**propiedades**

**button** `WalletButtonArt`

El diseño oficial del botón de la billetera. Ausente cuando no se ha publicado ninguno.

**propiedades**

**light** `object` *required*

Para páginas claras.

**propiedades**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

Para páginas oscuras.

**propiedades**

**color** `string` *required*

**image** `string` *required*

**currency** `string`

Código de moneda ISO 4217 de tres letras en minúsculas. Filtra la matriz de métodos de pago.

**amount** `number`

Importe del pago en unidades menores. No se ofrecen los métodos cuyos límites lo excluyen.

**paymentMethodConfiguration** `object`

Filtros de métodos de pago de la cuenta en el formato `enabled`, `disabled` e `include_platform_defaults` de la API. `disabled` elimina tipos, `enabled` restaura tipos ofrecidos e `include_platform_defaults: false` deja solo los tipos habilitados. Los planes proporcionan su propia configuración.

**propiedades**

**enabled** `string[]`

**disabled** `string[]`

**include\_platform\_defaults** `boolean`

**appearance** `Appearance`

Personalización visual de los elementos de este grupo. Sobrescribe el `WhopElements({ appearance })` global. Cámbialo en vivo con `update({ appearance })`.

**locale** `WhopElementsLocale`

Configuración regional del texto de la interfaz de los elementos de este grupo. Establécela en una de las configuraciones regionales incluidas en la app para sobrescribir la configuración global. Cualquier otro valor recurre a la configuración regional predeterminada.

## Eventos

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

### `onLoadingChange`

Se ejecuta cuando cambia el estado de carga agrupado. El valor es `true` mientras algún elemento montado siga cargándose.

**loading** `boolean`

## Métodos

Llámalos en el handle de Payments obtenido de `whop.payments.create({ … })` o `usePayments()`.

### `createConfirmationToken`

Crea un token de confirmación para el método seleccionado desde tu botón de pago. Pasa los datos de facturación del checkout. Deben incluir `email`. Proporciona `phone` para los métodos que lo requieren cuando la recopilación de datos de facturación está desactivada. Las tarjetas también necesitan `name` y una dirección que contenga `line1` y `country`. Las selecciones de billetera abren su hoja durante la interacción con el botón de pago. Cuando la cuenta ofrece vinculación bancaria en la página (`bank_debit.bank_connection` en su tipo de método de pago de cuenta bancaria), seleccionar una cuenta bancaria también abre Plaid Link durante esa interacción, y la llamada se resuelve una vez que el comprador ha vinculado una cuenta. Eso requiere una página de whop.com o un dominio preparado para Apple Pay mediante la [API de Domains](https://docs.whop.com/es/api-reference/beta/domains/domain), y una Content Security Policy que permita los hosts de Plaid que devuelve `contentSecurityPolicy()`. De lo contrario, el comprador vincula la cuenta después de enviar el pago. Si el comprador cierra la hoja o Link, la llamada se rechaza con `payment_request_cancelled`: trátalo como una cancelación, no como un error de pago, y deja que el comprador vuelva a pagar. Confirma el `confirmationToken` devuelto en el servidor y luego llama a `WhopElements.payments.handleNextAction(…)`. Se ejecuta en tu página (en el host), no en el iframe del controlador.

**Parámetros**

**input** `object` *required*

**propiedades**

**billingDetails** `object`

**propiedades**

**email** `string`

**name** `string`

**phone** `string`

**address** `object`

**propiedades**

**country** `string`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**Devuelve** `Promise<object>`

**confirmationToken** `string` *required*

**type** `string` *required*

### `update`

Combina nuevas opciones del handle en todos los elementos montados. En React, cambia las props del namespace en su lugar.

**Parámetros**

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

### `destroy`

Destruye todos los elementos y subcontroladores que creó este handle, elimina el frame del controlador y libera sus suscripciones. Puedes llamarlo más de una vez, pero un handle destruido rechaza cualquier otra llamada: crea un nuevo handle para empezar de nuevo. React elimina el grupo automáticamente cuando el provider se desmonta.

## Métodos estáticos

Llámalos sin montar nada: `whop.payments.<method>(…)` en vanilla o `useWhop().payments.<method>(…)` en React.

### `handleNextAction`

Completa el paso pendiente de un pago confirmado sin montar un elemento. `clientSecret` identifica el pago. No necesitas un ID de pago. Los pasos en línea se abren en un diálogo y se resuelven con `redirected: false`. Cerrar el diálogo devuelve el estado actual del pago, que puede seguir pendiente. Los pasos de página completa redirigen con `redirected: true` a `return_url`, o a un recibo alojado cuando el pago no tiene URL de retorno. Dentro de un iframe, navegan en la pestaña de nivel superior. Si la página contenedora rechaza esa navegación, se rechazan con el código `TAB_NAVIGATION_BLOCKED` y el pago sigue pendiente. Establece `returnUrl` para actualizar el destino antes de la presentación. Un fallo en la actualización se rechaza antes de que se ejecute cualquier paso. Los pasos en línea nunca navegan a esa URL. Un pago cuyo cobro aún se está decidiendo se consulta periódicamente hasta que aparece un paso o se resuelve; un pago ya decidido sin ningún paso se resuelve inmediatamente.

**Parámetros**

**input** `object` *required*

**propiedades**

**clientSecret** `string` *required*

**returnUrl** `string`

**pollIntervalMs** `number`

**Devuelve** `Promise<object>`

**status** `string` *required*

**redirected** `boolean` *required*

**lastPaymentError** `object | null` *required*

**propiedades**

**code** `string | null`

**decline\_code** `string | null`

**message** `string | null`

## Recursos

Crea estos objetos del SDK sin montar un elemento. Cada uno tiene su propia página:

> [card] [PaymentRequest](https://docs.whop.com/es/elements/latest/payments/paymentRequest.md)
>
> Hoja de bajo nivel de Apple Pay, Google Pay o PayPal para botones personalizados, checkout exprés y callbacks de envío. Los mosaicos de billetera automatizan este flujo mediante `payments.createConfirmationToken`. Espera a `canMakePayment()` para comprobar la disponibilidad y preparar la billetera, y luego llama a `show(type)` de forma síncrona en el handler de la interacción del usuario. El `ctok` resuelto es un token de confirmación con el prefijo `ctok_`. Confírmalo en el servidor como un token emitido por un elemento. Un token de PayPal cobra como máximo el total que PayPal mostró al comprador.

## Política de seguridad de contenido

Parte del trabajo de este grupo se ejecuta en tu página, no en un frame. Una página con una Content Security Policy necesita estos orígenes. `contentSecurityPolicy()` de `@whop/elements` devuelve todos los orígenes de esta tabla. El origen de sandbox se aplica con `environment: "sandbox"`.

| Requisito | Directiva | Origen en producción | Origen en sandbox |
| - | - | - | - |
| Script de Plaid Link | `script-src` | `https://cdn.plaid.com` | Igual |
| ↳ Frame de Plaid Link, que abre el script de Plaid | `frame-src` | `https://cdn.plaid.com` | Igual |
| ↳ API de Plaid, a la que llama el script de Plaid | `connect-src` | `https://production.plaid.com` | `https://sandbox.plaid.com` |

## Elementos

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

> [card] [AddressElement](https://docs.whop.com/es/elements/latest/payments/address.md)
>
> Recopila una dirección de facturación o de envío. Los campos, su orden y la validación siguen el país seleccionado. Incluye autocompletado de la calle (a pantalla completa en teléfonos) y métodos para leer o validar la dirección.

> [card] [EmailElement](https://docs.whop.com/es/elements/latest/payments/email.md)
>
> Recopila el correo electrónico del comprador y lo pasa a `payments.createConfirmationToken()` mientras está montado. Un `billingDetails.email` explícito tiene prioridad. Si coincide con una cuenta de Whop, muestra un inicio de sesión opcional con verificación por código, o con la passkey de la cuenta si tiene una. Un inicio de sesión correcto desbloquea los métodos de pago guardados en el elemento de pago. Los compradores pueden continuar como invitados.

> [card] [TaxIdElement](https://docs.whop.com/es/elements/latest/payments/taxId.md)
>
> Recopila un registro fiscal empresarial aceptado por la API. Las etiquetas usan nombres orientados al comprador. El marcador de posición coincide con el formato seleccionado. `country` preselecciona un tipo. `onChange` emite los pares confirmados. El host proporciona los errores de validación de la API.

> [card] [BrandingElement](https://docs.whop.com/es/elements/latest/payments/branding.md)
>
> **Obligatorio: los demás elementos, excepto `AddressElement`, `EmailElement` y `TaxIdElement`, lo esperan.** El aviso de comerciante registrado (merchant of record) de Whop: la aceptación por parte del comprador de los Términos de servicio para compradores y la Política de privacidad de Whop, con el logotipo textual de Whop. Obligatorio: los elementos de pago, de tarjeta y de campos de tarjeta permanecen en su estado de carga hasta que se monta, y los pagos no pueden confirmarse sin él.

**Alternativas.** Monta uno a la vez. Destrúyelo antes de montar otro:

> [card] [PaymentElement](https://docs.whop.com/es/elements/latest/payments/payment.md)
>
> Muestra los métodos de pago disponibles y recopila los campos obligatorios y los avisos del método seleccionado. Usa `change` para habilitar tu botón de pago. En su handler de activación, llama a `payments.createConfirmationToken()`. Confirma el token en el servidor y luego pasa cualquier paso pendiente a `payments.handleNextAction(…)`. Usa `addressChange` para actualizaciones que dependen de la dirección.

> [card] [CardElement](https://docs.whop.com/es/elements/latest/payments/card.md)
>
> 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`.

> [card] [CardFields](https://docs.whop.com/es/elements/latest/payments/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. *(subcontrolador, 3 elementos)*


## Related topics

- [Retrieve Payment](https://docs.whop.com/es/api-reference/payments/retrieve-payment.md)
- [Retry Payment](https://docs.whop.com/es/api-reference/payments/retry-payment.md)
- [Void Payment](https://docs.whop.com/es/api-reference/payments/void-payment.md)
