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

# Checkout

> 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. Móntalo con `items`, un único `plan` o una `checkoutConfiguration` que hayas creado, y el elemento abre la sesión de checkout por sí mismo; la credencial de la sesión nunca sale del elemento. Una configuración de checkout en modo setup monta el mismo elemento para guardar un método de pago: no se cobra nada, el método del comprador se guarda para que lo cobres más tarde y el checkout finalizado redirige con `setup_intent_id`. El comprador paga dentro del elemento, y un checkout finalizado redirige la pestaña actual a `returnUrl`, incluida la página que contiene el elemento. Realiza el cumplimiento a partir de webhooks en lugar de un callback del navegador. Sin `returnUrl`, el comprador permanece en la propia vista de éxito del elemento. El elemento gestiona automáticamente un paso de pago externo, como 3DS o la página de un banco. En whop.com, devuelve al comprador al checkout restaurado; en un embed, el comprador vuelve a la misma `returnUrl` sea cual sea el resultado, con los parámetros de consulta `payment` y `status` (`succeeded`, `failed` o `canceled`), por lo que la página en `returnUrl` debe leer `status` antes de tratar la visita como una venta. Un pago que falla dentro del elemento vuelve a abrir el mismo checkout mostrando el motivo, para que el comprador pueda pagar de nuevo. Todas las opciones se establecen en la creación: el elemento genera una sesión de checkout a partir de estos valores al montarse. Cambiar una más tarde con `update()` o con nuevas props de React falla en lugar de modificar el pedido existente. Monta un nuevo checkout para cambiar lo que se compra.

> [!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, Checkout } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Checkout /* options */>
        {/* mount elements here */}
      </Checkout>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const checkout = window.WhopElements().checkout.create({ /* options */ });
</script>
```

## Opciones

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

**plan** `string`

ID de un plan existente, con prefijo `plan_`. Atajo para un array `items` que contiene este plan y `quantity`. El plan define el precio; ningún importe puede afirmarse del lado del cliente. Pasa `plan`, `items` o una `checkoutConfiguration`. Solo se establece en la creación: la sesión se genera a partir de él, y cambiarlo más tarde se rechaza.

**quantity** `number`

Cuántas unidades comprar. Los planes que no permiten múltiplos rechazan valores superiores a 1. Solo se establece en la creación: la sesión se genera con él, y cambiarlo más tarde se rechaza. @default 1

**items** `CheckoutItemInput[]`

Los planes de este checkout y cuántas unidades de cada uno comprar. Todos los artículos deben pertenecer al mismo vendedor y usar condiciones de facturación compatibles; la API valida el carrito completo y le pone precio como un único cobro. Pásalo en lugar de `plan`, `quantity` o `checkoutConfiguration`. Solo se establece en la creación: la sesión se genera a partir de este carrito exacto, y cambiarlo más tarde se rechaza.

**propiedades**

**plan** `string` *required*

ID de un plan existente, con prefijo `plan_`.

**quantity** `number`

Número de unidades que comprar. Por defecto es 1; los planes pueden no permitir cantidades superiores a 1.

**checkoutConfiguration** `string`

ID de una configuración de checkout existente, con prefijo `ch_`. El elemento crea la sesión de checkout a partir de ella: la configuración indica el plan que se vende (o, en modo `setup`, ningún plan: el checkout guarda un método de pago y no cobra nada) e inicializa sus propios valores predefinidos de código de afiliado, metadatos, redirección y método de pago; una opción pasada aquí junto a ella prevalece sobre la copia de la configuración, campo por campo. Pasa `plan` junto a ella solo para establecer `quantity`; debe ser el propio plan de la configuración, que nunca puede sustituirse por debajo de sus valores predefinidos. Solo se establece en la creación.

**promoCode** `string`

Un código promocional que se aplica antes de que el comprador vea el precio: el descuento está en la primera cotización, y el comprador todavía puede cambiarlo o quitarlo. Pasa el código que traía un enlace de marketing: un código caducado o que nunca fue válido abre el checkout a precio completo con el motivo en la fila de la promoción, nunca un checkout que no se abre. Solo se establece en la creación.

**affiliateCode** `string`

El afiliado al que se atribuye este checkout. Solo se establece en la creación.

**attribution** `CheckoutAttributionInput`

De dónde vino esta venta, para los informes de la cuenta: los parámetros de campaña del enlace por el que llegó el comprador (`utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`, cualquier otro parámetro `utm_*` en `utm`, un `trackingLinkId` de Whop, un `funnelId` y tu propio `source`). Todo esto se registra en el pedido y nunca se muestra al comprador. Solo se establece en la creación.

**propiedades**

**utmSource** `string`

**utmMedium** `string`

**utmCampaign** `string`

**utmTerm** `string`

**utmContent** `string`

**trackingLinkId** `string`

**funnelId** `string`

**source** `string`

**utm** `Record\<string, string\>`

Cualquier otro parámetro `utm_*` que traía el enlace, indexado por su nombre completo (`{ utm_funnel: 'spring' }`). Las claves que no empiezan por `utm_` se ignoran, y los campos con nombre anteriores prevalecen sobre la misma clave aquí.

**metadata** `Record\<string, string\>`

Tus propios pares clave/valor que se registran en el pedido y se leen de vuelta en el pago: IDs de pedido, IDs de carrito o cualquier cosa con la que concilies. Hasta 40 pares de strings. Solo se establece en la creación.

**returnUrl** `string`

Adónde llega el comprador después de un paso de pago externo, sea cual sea su resultado. La pestaña llega con `payment` (el ID `pay_`; `setup` con el ID `sint_` para un checkout en modo setup) y `status` (`succeeded`, `failed` o `canceled`) añadidos, y tus otros parámetros de consulta intactos. Ramifica según `status` antes de mostrar una página de éxito: un paso externo rechazado o abandonado también llega aquí. Realiza el cumplimiento a partir de webhooks, no a partir de esta visita. Solo https (http para localhost). Solo se establece en la creación.

**appearance** `Appearance`

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

**locale** `WhopElementsLocale`

Configuración regional para el texto de la interfaz de los elementos de este grupo. Establécela en una de las configuraciones regionales incluidas en la app para anular 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.

### `onComplete`

Se dispara una vez por montaje cuando el checkout se completa y su resultado es definitivo. `result` indica qué resultado quedó: `payment` (el comprador pagó, `paymentId`), `waitlist_entry` (el comprador se unió a una lista de espera, `entryId`) o `setup` (un checkout en modo setup guardó el método de pago, `setupIntentId`); `sessionId` es la sesión de checkout en cualquier caso. Se dispara antes de cualquier navegación a `returnUrl`, así que aquí es donde tus propias analíticas o píxeles de anuncios registran la compra. Realiza el cumplimiento a partir de webhooks, no a partir de este callback: un checkout restaurado en una carga de página posterior lo dispara de nuevo para el mismo resultado.

**payload** `CheckoutPaymentCompletion | CheckoutWaitlistCompletion | CheckoutSetupCompletion`

**CheckoutPaymentCompletion**

**sessionId** `string` *required*

La sesión de checkout, con prefijo `chs_`.

**result** `"payment"` *required*

**paymentId** `string` *required*

El pago, con prefijo `pay_`: el ID con el que registrar la compra.

**CheckoutWaitlistCompletion**

**sessionId** `string` *required*

La sesión de checkout, con prefijo `chs_`.

**result** `"waitlist_entry"` *required*

**entryId** `string` *required*

La entrada de la lista de espera, con prefijo `ent_`.

**CheckoutSetupCompletion**

**sessionId** `string` *required*

La sesión de checkout, con prefijo `chs_`.

**result** `"setup"` *required*

**setupIntentId** `string` *required*

La configuración guardada, con prefijo `sint_`.

### `onLoadingChange`

Se ejecuta cuando cambia el estado de carga agrupado. El valor es `true` mientras algún elemento montado todavía se está cargando.

**loading** `boolean`

## Métodos

Llámalos en el handle de Checkout obtenido de `whop.checkout.create({ … })` o `useCheckout()`.

### `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\<CheckoutOptions\>` *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.

## Recursos

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

> [card] [CheckoutSession](https://docs.whop.com/es/elements/latest/checkout/checkoutSession.md)
>
> Sesión de checkout headless de bajo nivel para una página que dibuja su propio botón de PayPal. `load()` crea la sesión de checkout a partir de `lineItems`; `show("paypal", { termsAccepted: true })` envía al comprador a PayPal (una ventana emergente en escritorio, la pestaña completa en teléfonos) y se resuelve con el pago una vez que el comprador lo aprueba. Con `paymentMethodOptions.paypal.requestShipping`, PayPal le pide al comprador una dirección de envío y el webhook de la cuenta suscrito a `shipping_address.changed` calcula el precio de cada una en tu servidor mientras el comprador está en PayPal; el pago se crea solo después de que el comprador lo aprueba, a ese precio. Tras una redirección de página completa, la promesa nunca se resuelve; en su lugar, lee el resultado de los parámetros de consulta `payment` y `status` de `redirectUrl`.

## Elementos

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

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

> [card] [CheckoutElement](https://docs.whop.com/es/elements/latest/checkout/checkout.md)
>
> La superficie de checkout completa: resumen del pedido con la cotización en vivo, introducción de código promocional, la moneda en la que paga el comprador, todo lo que este checkout tiene que recopilar del comprador, la superficie de métodos de pago compuesta y el flujo de pago. Lo que recopila es lo que haya configurado el vendedor (correo electrónico, sus propias preguntas, un número de teléfono, una dirección de envío para productos físicos, una aceptación explícita de sus términos), mostrado junto en una sola pantalla en el orden que eligió, de modo que un vendedor que empiece a pedir algo nuevo no necesita ningún cambio aquí. Renderiza toda la compra; el controlador de checkout es dueño de la sesión y de la credencial. Después de un pago que necesita un paso externo, esta misma superficie muestra el resultado que informa el servidor cuando el comprador regresa.

> [card] [ExpressCheckoutElement](https://docs.whop.com/es/elements/latest/checkout/expressCheckout.md)
>
> Botones de Apple Pay, Google Pay y PayPal de una sola pulsación para un checkout: el monedero recopila lo que la sesión todavía necesite (el correo electrónico del comprador, una dirección de envío para productos físicos, un número de teléfono cuando el vendedor lo pide en Apple Pay y Google Pay, y en Apple Pay un código promocional cuando el vendedor ofrece introducirlo) y una pulsación finaliza la compra. Comparte el espacio de entrada del checkout con el elemento de checkout completo, por lo que un handle monta exactamente uno de los dos: este botón solo, cuando la compra es lo bastante sencilla como para que una hoja la finalice, o la superficie de checkout completa para todo lo demás. Renderiza solo los monederos con los que el dispositivo del comprador puede pagar realmente (y que permite la propia configuración de métodos de pago del checkout), usando el diseño de botón servido, y no renderiza nada cuando no hay ningún monedero disponible. PayPal aparece cuando el vendedor lo acepta, se abre en su propia ventana y guarda la cuenta de PayPal del comprador con la compra, de modo que una renovación, una prueba gratuita y los cobros posteriores que haga el vendedor funcionan como una tarjeta guardada. Los tres monederos requieren Apple Pay en el dominio de la página: las páginas propias de whop.com están aprobadas previamente, y cualquier otro sitio debe añadir Apple Pay a su dominio mediante la [API de Domains](https://docs.whop.com/es/api-reference/beta/domains/domain) antes de que cualquiera de estos botones se renderice allí. Ofrecer Google Pay en tu propio sitio está sujeto a los Términos de servicio de la API de Google Pay. Un checkout que la hoja no puede finalizar de forma fiable (unirse a una lista de espera, una transferencia, una pregunta de formulario que solo una página puede hacer) se rechaza de forma explícita en lugar de renderizar un botón condenado al fracaso.


## Related topics

- [CheckoutSession](https://docs.whop.com/es/elements/latest/checkout/checkoutSession.md)
- [CheckoutElement](https://docs.whop.com/es/elements/latest/checkout/checkout.md)
- [Configuración de checkout](https://docs.whop.com/es/api-reference/legacy/checkout-configurations/checkout-configuration.md)
