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

# Integra un checkout

> Inserta el checkout completo de Whop en tu página con el elemento Checkout, directamente desde el navegador, y realiza el fulfillment desde un webhook

Integra el checkout completo de Whop en tu propia página con el elemento Checkout. Se ejecuta íntegramente en el navegador. Tu servidor solo escucha el webhook que indica que el comprador ha pagado.

Los archivos de **Código** incluyen comentarios `Step X.Y` que remiten a los pasos siguientes. Elige una implementación de servidor y una implementación de cliente. La lista incluye los archivos de todas las opciones.

## Integra el checkout

### 1.1 Instala los paquetes (React)

Instala los paquetes de Whop Elements para React.

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

```bash pnpm theme={null}
pnpm add @whop/elements-react @whop/elements
```

### 1.1 Añade la etiqueta script (JavaScript)

Carga el script de Whop Elements en la página que aloja el checkout.

### 1.2 Monta el elemento Checkout

Monta `CheckoutElement` dentro de un handle `Checkout` y pasa la variante mediante la propiedad `plan` existente. El propio elemento abre la sesión de checkout, calcula el precio del pedido y recopila todo lo que el vendedor haya configurado. No necesita código de servidor ni una clave de API en la página: la variante define el precio, así que el navegador nunca establece un importe.

Pasa `metadata`, como tu propio ID de pedido, en el handle. Whop lo copia en el pago y en todos los webhooks relacionados con él. Establece `returnUrl` en una página que alojes con `https`. El comprador llega allí después de un paso de pago fuera del sitio, como 3D Secure, la página de un banco o una solicitud de financiación. Añade tus propios parámetros de consulta, como el ID del pedido. Se conservan durante todo el recorrido.

Para adjuntar un código de afiliado, un código promocional o la atribución de una campaña, pasa `affiliateCode`, `promoCode` o `attribution` en el handle. Solo necesitas una [configuración de checkout](https://docs.whop.com/es/api-reference/checkout-configurations/create-a-checkout-configuration.md) creada en tu servidor cuando quieras mantener esos ajustes predefinidos fuera del código del cliente.

### 1.3 Registra la finalización

`onComplete` se ejecuta una vez cuando el checkout se completa dentro del elemento, antes de cualquier navegación a `returnUrl`. Úsalo para analíticas y píxeles de anuncios.

No gestiones el pedido desde ahí. Un checkout restaurado al recargar la página más tarde lo vuelve a ejecutar con el mismo resultado, y un paso de pago fuera del sitio se completa en la página de retorno.

## Gestiona la página de retorno

### 2.1 Lee el resultado de la URL

El comprador llega a `returnUrl` **pase lo que pase** durante el paso fuera del sitio. Whop añade dos parámetros de consulta. `payment` es el ID `pay_`. `status` es `succeeded` cuando el comprador ha pagado, y `failed` o `canceled` cuando no. Una solicitud de financiación rechazada por el prestamista llega aquí con `status=canceled`, igual que una aprobada llega con `status=succeeded`.

Tus propios parámetros, como `order`, se mantienen en la URL. Los rechazos de tarjeta nunca llegan a esta página, porque el elemento los muestra en línea. La página de retorno es el único lugar donde tu sitio ve un pago fuera del sitio fallido.

### 2.2 Muestra la vista adecuada

Ramifica según `status`. `succeeded` muestra la página de agradecimiento. `failed` y `canceled` muestran un mensaje indicando que no se ha cobrado al comprador y un enlace para volver al checkout. Cualquier otro valor, como `processing`, significa que el cargo sigue pendiente. Indica al comprador que le confirmarás por correo electrónico.

Trata la página como una visualización del resultado, no como prueba de pago. Cualquiera puede escribir `status=succeeded` en una URL. El acceso, las descargas y la gestión del pedido dependen del webhook `payment.succeeded` en tu servidor.

## Gestiona el pedido desde tu servidor

### 3.1 Instala el SDK de Whop (Next.js)

El helper de webhooks se incluye en el SDK de Whop. Instálalo en el servidor que recibe el webhook.

```bash npm theme={null}
npm install @whop/sdk @vercel/functions
```

```bash pnpm theme={null}
pnpm add @whop/sdk @vercel/functions
```

### 3.1 Instala el SDK de Whop (Express)

El helper de webhooks se incluye en el SDK de Whop. Instálalo en el servidor que recibe el webhook.

```bash npm theme={null}
npm install @whop/sdk express
```

```bash pnpm theme={null}
pnpm add @whop/sdk express
```

### 3.1 Instala el SDK de Whop (Python)

El helper de webhooks se incluye en el SDK de Whop. Instálalo en el servidor que recibe el webhook.

```bash pip theme={null}
pip install whop-sdk fastapi
```

```bash poetry theme={null}
poetry add whop-sdk fastapi
```

### 3.2 Gestiona el webhook de pago

Whop envía `payment.succeeded` a tu endpoint de webhook una vez que el comprador ha pagado. Verifica la firma con el helper del SDK y, a continuación, gestiona el pedido: márcalo como pagado, concede el acceso y envía el correo electrónico. El pago incluye los `metadata` que estableciste en el handle de Checkout.

La gestión del pedido debe hacerse aquí y en ningún otro sitio. El comprador puede cerrar el navegador antes de que cargue tu página de retorno, una redirección puede fallar y cualquiera puede escribir un parámetro de consulta a mano. Sigue la [guía de Webhooks](https://docs.whop.com/es/developer/guides/webhooks.md) para crear el webhook y guardar su secreto `ws_` como `WHOP_WEBHOOK_SECRET`.

## Código

### Cliente: React — `CheckoutPage.tsx`

```tsx CheckoutPage.tsx theme={null}
// Step 1.1: Install the packages
import { Checkout, CheckoutElement, WhopElements } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

export function CheckoutPage({ orderId }: { orderId: string }) {
	return (
		<WhopElements elements={loadWhop()}>
			{/* Step 1.2: Mount the Checkout element */}
			<Checkout
				plan="plan_xxxxxxxxxxxxx"
				metadata={{ order_id: orderId }}
				returnUrl={`https://yoursite.com/checkout/return?order=${orderId}`}
				// Step 1.3: Record the completion
				onComplete={(completion) => {
					if (completion.result === "payment") {
						// Fire analytics or ad pixels here. Fulfill from the webhook, not from this callback.
						console.log("Checkout completed", completion.paymentId);
					}
				}}
			>
				{/* Step 1.2: Mount the Checkout element */}
				<CheckoutElement />
			</Checkout>
		</WhopElements>
	);
}
```

### Cliente: React — `CheckoutReturn.tsx`

```tsx CheckoutReturn.tsx theme={null}
export function CheckoutReturn() {
	// Step 2.1: Read the outcome from the URL
	// Whop appends `payment` and `status` to your returnUrl. Your own parameters (here `order`) survive.
	const params = new URLSearchParams(window.location.search);
	const paymentId = params.get("payment");
	const status = params.get("status");
	const orderId = params.get("order");

	// Step 2.2: Show the right face
	if (status === "succeeded") {
		return (
			<section>
				<h1>Thanks for your order</h1>
				<p>Payment {paymentId} is complete. A receipt is on its way to your email.</p>
			</section>
		);
	}

	if (status === "failed" || status === "canceled") {
		return (
			<section>
				<h1>Your payment did not go through</h1>
				<p>No money was taken. You can try again with another payment method.</p>
				<a href={`/checkout?order=${orderId}`}>Back to checkout</a>
			</section>
		);
	}

	return (
		<section>
			<h1>Confirming your payment</h1>
			<p>Your payment is still being processed. We will email you as soon as it is confirmed.</p>
		</section>
	);
}
```

### Cliente: JavaScript — `checkout.html`

```html checkout.html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <!-- Step 1.1: Add the script tag -->
    <script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
  </head>
  <body>
    <div id="checkout"></div>

    <script type="module">
      const orderId = new URLSearchParams(window.location.search).get("order");

      // Step 1.2: Mount the Checkout element
      const checkout = window.WhopElements().checkout.create({
        plan: "plan_xxxxxxxxxxxxx",
        metadata: { order_id: orderId },
        returnUrl: `https://yoursite.com/checkout/return?order=${orderId}`,
        // Step 1.3: Record the completion
        onComplete: (completion) => {
          if (completion.result === "payment") {
            // Fire analytics or ad pixels here. Fulfill from the webhook, not from this callback.
            console.log("Checkout completed", completion.paymentId);
          }
        },
      });
      // Step 1.2: Mount the Checkout element
      checkout.create("checkout").mount("#checkout");
    </script>
  </body>
</html>
```

### Cliente: JavaScript — `return.html`

```html return.html theme={null}
<!DOCTYPE html>
<html>
  <body>
    <section id="succeeded" hidden>
      <h1>Thanks for your order</h1>
      <p>Payment <span id="payment-id"></span> is complete. A receipt is on its way to your email.</p>
    </section>
    <section id="failed" hidden>
      <h1>Your payment did not go through</h1>
      <p>No money was taken. You can try again with another payment method.</p>
      <a id="retry" href="/checkout">Back to checkout</a>
    </section>
    <section id="pending" hidden>
      <h1>Confirming your payment</h1>
      <p>Your payment is still being processed. We will email you as soon as it is confirmed.</p>
    </section>

    <script type="module">
      // Step 2.1: Read the outcome from the URL
      // Whop appends `payment` and `status` to your returnUrl. Your own parameters (here `order`) survive.
      const params = new URLSearchParams(window.location.search);
      const paymentId = params.get("payment");
      const status = params.get("status");
      const orderId = params.get("order");

      // Step 2.2: Show the right face
      if (status === "succeeded") {
        document.querySelector("#payment-id").textContent = paymentId;
        document.querySelector("#succeeded").hidden = false;
      } else if (status === "failed" || status === "canceled") {
        document.querySelector("#retry").href = `/checkout?order=${orderId}`;
        document.querySelector("#failed").hidden = false;
      } else {
        document.querySelector("#pending").hidden = false;
      }
    </script>
  </body>
</html>
```

### Servidor: Next.js — `app/api/webhooks/whop/route.ts`

```typescript app/api/webhooks/whop/route.ts theme={null}
// Step 3.1: Install the Whop SDK
import { waitUntil } from "@vercel/functions";
import { unwrapWebhook } from "@whop/sdk/helpers";
import type { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
	// Step 3.2: Handle the payment webhook
	// Give the raw body. Parsing it first changes the bytes and the signature check fails.
	const payload = await request.text();
	const headers = Object.fromEntries(request.headers);

	const event = unwrapWebhook(payload, {
		headers,
		key: process.env.WHOP_WEBHOOK_SECRET!,
	});

	if (event.type === "payment.succeeded") {
		waitUntil(fulfillOrder(event.data));
	}

	// Respond in less than 5 seconds, or Whop retries.
	return new Response("OK", { status: 200 });
}

async function fulfillOrder(payment: Record<string, any>) {
	// Step 3.2: Handle the payment webhook
	// metadata.order_id is the value you set on the Checkout handle.
	const orderId = payment.metadata?.order_id;
	console.log(`[PAYMENT SUCCEEDED] ${payment.id} for order ${orderId}`);
	// Mark the order paid in your database and grant access here.
}
```

### Servidor: Express — `server.ts`

```typescript server.ts theme={null}
// Step 3.1: Install the Whop SDK
import { unwrapWebhook } from "@whop/sdk/helpers";
import express from "express";

const app = express();

// Step 3.2: Handle the payment webhook
// Read the raw body on this route: parsing it first changes the bytes and the signature check fails.
app.post(
	"/api/webhooks/whop",
	express.raw({ type: "application/json" }),
	(req, res) => {
		const event = unwrapWebhook(req.body.toString("utf8"), {
			headers: req.headers,
			key: process.env.WHOP_WEBHOOK_SECRET!,
		});

		if (event.type === "payment.succeeded") {
			// metadata.order_id is the value you set on the Checkout handle.
			const orderId = event.data.metadata?.order_id;
			console.log(`[PAYMENT SUCCEEDED] ${event.data.id} for order ${orderId}`);
			// Mark the order paid in your database and grant access here.
		}

		// Respond in less than 5 seconds, or Whop retries.
		res.sendStatus(200);
	},
);

app.listen(3000);
```

### Servidor: Python — `server.py`

```python server.py theme={null}
# Step 3.1: Install the Whop SDK
import os

from fastapi import BackgroundTasks, FastAPI, Request, Response
from whop_sdk.lib.verify_webhook import unwrap

app = FastAPI()


# Step 3.2: Handle the payment webhook
@app.post("/api/webhooks/whop")
async def whop_webhook(request: Request, background: BackgroundTasks):
    # Give the raw body. Parsing it first changes the bytes and the signature check fails.
    payload = await request.body()

    event = unwrap(payload, dict(request.headers), os.environ["WHOP_WEBHOOK_SECRET"])

    if event["type"] == "payment.succeeded":
        background.add_task(fulfill_order, event["data"])

    # Respond in less than 5 seconds, or Whop retries.
    return Response(status_code=200)


def fulfill_order(payment):
    # metadata.order_id is the value you set on the Checkout handle.
    order_id = (payment.get("metadata") or {}).get("order_id")
    print(f"[PAYMENT SUCCEEDED] {payment['id']} for order {order_id}")
    # Mark the order paid in your database and grant access here.
```

## Próximos pasos

* [Referencia del elemento Checkout](https://docs.whop.com/es/elements/latest/checkout/overview): todas las opciones, eventos y métodos del handle de Checkout.
* [Crea un checkout con payment elements](https://docs.whop.com/es/developer/guides/payment-elements.md): diseña el formulario tú mismo y confirma el pago desde tu servidor.
* [Webhooks](https://docs.whop.com/es/developer/guides/webhooks.md): crea el endpoint, guarda el secreto de firma y gestiona los reintentos.
* [Prueba en el sandbox](https://docs.whop.com/es/developer/guides/sandbox.md): realiza un cargo de prueba con tarjetas que se aprueban, fallan o requieren una acción.


## Related topics

- [Añade Express Checkout](https://docs.whop.com/es/developer/guides/express-checkout.md)
- [Aceptar pagos](https://docs.whop.com/es/developer/guides/accept-payments.md)
- [Crea un checkout con Payment Elements](https://docs.whop.com/es/developer/guides/payment-elements.md)
