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

# Inicio rápido de la API de Whop

> Haz tu primera llamada a la API de Whop, crea un checkout, págalo con una tarjeta de prueba y recibe el webhook, todo en el sandbox. Después cambia a producción.

Este inicio rápido se ejecuta en el sandbox, un entorno de Whop independiente en el que el dinero nunca se mueve. Obtendrás una clave de API de sandbox, harás tu primera llamada, crearás un checkout, lo pagarás con una tarjeta de prueba y recibirás el webhook `payment.succeeded` en tu servidor. Pasar a producción es el último paso y consiste, sobre todo, en cambiar las claves.

> [!TIP]
>
> Si usas un agente de programación, dale esta página en Markdown, `https://docs.whop.com/developer/quickstart.md`, o pega el prompt de la [Descripción general](https://docs.whop.com/es/developer/start.md#build-with-your-coding-agent).

## Sandbox y producción

Whop ejecuta dos entornos que no comparten nada: ni cuentas, ni claves, ni productos, ni webhooks. Construyes en el sandbox y lanzas en producción. Todos los valores siguientes cambian entre uno y otro.

| | Sandbox: construir y probar | Producción: lanzar |
| - | - | - |
| Dinero | Nunca se mueve | Real |
| Panel | [sandbox.whop.com](https://sandbox.whop.com) | [whop.com](https://whop.com) |
| Claves de API y webhooks | [sandbox.whop.com/dashboard/developer](https://sandbox.whop.com/dashboard/developer) | [whop.com/dashboard/developer](https://whop.com/dashboard/developer) |
| URL base de la API | `https://sandbox-api.whop.com/api/v1` | `https://api.whop.com/api/v1` |
| Entorno del SDK | `Sandbox` | `Production`, el valor predeterminado del SDK |
| Páginas de checkout | `sandbox.whop.com/checkout/...` | `whop.com/checkout/...` |
| `WHOP_ENVIRONMENT` | `sandbox` | `production` |

> [!WARNING]
>
> Las claves de API de sandbox y de producción tienen el mismo aspecto, así que nada en una clave te indica a qué entorno pertenece. Los fragmentos de esta página eligen el entorno a partir de una variable `WHOP_ENVIRONMENT` en lugar de fijarlo en el código, de modo que el mismo código funciona en ambos. El [servidor MCP de Whop](https://docs.whop.com/es/developer/ai/overview.md#mcp-server) solo actúa sobre datos de producción.

## Obtén una clave de API de sandbox

**1. Regístrate en el sandbox**

Ve a [sandbox.whop.com](https://sandbox.whop.com) y crea una cuenta. Es independiente de cualquier cuenta que tengas en whop.com. El proceso de registro crea tu primer negocio, que es la Account propietaria de las claves de API, los productos, los webhooks y los pagos.

**2. Crea una clave de API de Account**

Abre [sandbox.whop.com/dashboard/developer](https://sandbox.whop.com/dashboard/developer). En **Account API Keys**, selecciona **Create** y ponle a la clave un nombre como `Local development`.

Para este inicio rápido, usa el rol Admin. Antes de pasar a producción, cambia a un conjunto de permisos personalizado que cubra solo los endpoints que llamas.

**3. Guarda la clave en tu servidor**

Copia la clave cuando Whop la muestre y ponla en tu archivo `.env` local junto con el entorno al que pertenece:

```bash theme={null}
WHOP_ENVIRONMENT=sandbox
WHOP_API_KEY=your_sandbox_key
```

![Sección Account API Keys del panel de Whop con el nombre de una clave, su valor enmascarado y el botón Create](https://mintcdn.com/whop/xuW6TKFlagvnbmV0/images/developer-api-key-field.png?fit=max\&auto=format\&n=xuW6TKFlagvnbmV0\&q=85\&s=699bf36af18f7a12dfd855eb0684b38e)

> [!NOTE]
>
> Mantén `WHOP_API_KEY` en tu servidor. No pongas claves de API en código del navegador, apps móviles ni repositorios públicos. Las claves de sandbox y de producción tienen el mismo aspecto, así que ponles nombres que te permitan distinguirlas.

Una clave de API de Account es lo adecuado cuando tu servidor actúa en nombre de tu propio negocio. Para crear una app que instalen otros negocios, o para permitir que los usuarios inicien sesión con Whop, consulta [Autenticación y claves de API](https://docs.whop.com/es/developer/guides/auth-scoping.md).

## Instala el SDK

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

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

```bash Ruby theme={null}
gem install whop_sdk
```

> [!NOTE]
>
> Esta página requiere el SDK 2.7.0 o posterior. Las versiones anteriores no aceptan el `variant` en línea en las configuraciones de checkout.

## Haz tu primera llamada

Apunta el cliente al entorno indicado en `WHOP_ENVIRONMENT` y recupera la cuenta asociada a tu clave. Esto confirma que la clave funciona e imprime el ID de tu cuenta, que empieza por `biz_`.

```typescript TypeScript theme={null}
import { WhopClient, WhopEnvironment } from "@whop/sdk";

const apiKey = process.env.WHOP_API_KEY;

if (!apiKey) {
  throw new Error("Set WHOP_API_KEY");
}

const client = new WhopClient({
  token: apiKey,
  environment: process.env.WHOP_ENVIRONMENT === "production" ? WhopEnvironment.Production : WhopEnvironment.Sandbox,
});

const account = await client.accounts.me();

console.log(account.id);
```

```python Python theme={null}
import os
from whop_sdk import Whop, WhopEnvironment

client = Whop(
    token=os.environ["WHOP_API_KEY"],
    environment=WhopEnvironment.PRODUCTION if os.environ.get("WHOP_ENVIRONMENT") == "production" else WhopEnvironment.SANDBOX,
)

account = client.accounts.me()

print(account.id)
```

```ruby Ruby theme={null}
require "whop_sdk"

whop = Whop_sdk::Client.new(
  token: ENV.fetch("WHOP_API_KEY"),
  environment: ENV["WHOP_ENVIRONMENT"] == "production" ? Whop_sdk::Environment::PRODUCTION : Whop_sdk::Environment::SANDBOX,
)

account = whop.accounts.me

puts account.id
```

```bash curl (sandbox) theme={null}
curl https://sandbox-api.whop.com/api/v1/accounts/me \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-11-04-1"
```

```json Response (trimmed) theme={null}
{
	"id": "biz_XXXXXXXX",
	"title": "Acme Studio",
	"route": "acme-studio",
	"status": "active"
}
```

> [!TIP]
>
> Esa es tu cuenta de sandbox. La clave funciona.

## Crea un checkout

Una sola llamada crea una variante y devuelve una `purchase_url`, una página de checkout alojada en `sandbox.whop.com`.

```typescript TypeScript theme={null}
const checkout = await client.checkoutConfigurations.create({
	variant: {
		title: "Starter",
		billing_type: "one_time",
		initial_price: 10.0,
		currency: "usd",
	},
});

console.log(checkout.purchase_url);
```

```python Python theme={null}
checkout = client.checkout_configurations.create(
    variant={
        "title": "Starter",
        "billing_type": "one_time",
        "initial_price": 10.0,
        "currency": "usd",
    },
)

print(checkout.purchase_url)
```

```ruby Ruby theme={null}
checkout = whop.checkout_configurations.create(
  variant: {
    title: "Starter",
    billing_type: "one_time",
    initial_price: 10.0,
    currency: "usd",
  },
)

puts checkout.purchase_url
```

Abrirás esta URL en el paso del pago. Si ya tienes una variante, pasa su ID como `variant_id` en lugar del `variant` en línea. No puedes enviar ambos. [Crear configuración de checkout](https://docs.whop.com/es/api-reference/checkout-configurations/create-a-checkout-configuration.md) enumera todas las opciones, incluidos los precios recurrentes, las pruebas gratuitas y las URL de redirección.

## Escucha el webhook

Configura tu endpoint antes de pagar, para que el evento `payment.succeeded` tenga dónde llegar.

**1. Añade un endpoint**

Añade una ruta `POST` que verifique la firma y registre el evento. La verificación necesita el cuerpo sin procesar de la solicitud, así que léelo antes de cualquier análisis de JSON.

```typescript TypeScript + Next.js theme={null}
import { unwrapWebhook } from "@whop/sdk/helpers";
import type { NextRequest } from "next/server";

export async function POST(request: NextRequest): Promise<Response> {
  const event = unwrapWebhook<{ type: string; data: { id: string } }>(await request.text(), {
    headers: Object.fromEntries(request.headers),
    key: process.env.WHOP_WEBHOOK_SECRET!,
  });

  console.log(event.type, event.data.id);

  return new Response("OK", { status: 200 });
}
```

```python Python + FastAPI theme={null}
import os

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

app = FastAPI()

@app.post("/api/webhooks/whop")
async def whop_webhook(request: Request):
    event = unwrap(await request.body(), headers=dict(request.headers), key=os.environ["WHOP_WEBHOOK_SECRET"])

    print(event["type"], event["data"]["id"])

    return Response(status_code=200)
```

```ruby Ruby on Rails theme={null}
class Api::WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def whop
    event = WhopSDK::Helpers::VerifyWebhook.unwrap(
      request.raw_post,
      headers: {
        "webhook-id" => request.headers["webhook-id"],
        "webhook-timestamp" => request.headers["webhook-timestamp"],
        "webhook-signature" => request.headers["webhook-signature"],
      },
      key: ENV.fetch("WHOP_WEBHOOK_SECRET"),
    )

    Rails.logger.info("#{event[:type]} #{event[:data][:id]}")

    head :ok
  end
end
```

Mientras desarrollas, expón la ruta por HTTPS con ngrok, Cloudflare Tunnel u otro túnel.

**2. Crea el webhook en el panel del sandbox**

Abre **Developer > Webhooks** en el panel del sandbox y selecciona **Create webhook**. Pega la dirección HTTPS de tu endpoint, deja la versión de la API en `v1` y selecciona `payment.succeeded`.

![Formulario para crear un webhook con el evento payment\_succeeded seleccionado en la lista de eventos](https://mintcdn.com/whop/RLIxcN4GVU-CLB5B/images/create-webhook-select-events.png?fit=max\&auto=format\&n=RLIxcN4GVU-CLB5B\&q=85\&s=079887392e21e4680a82415244aeaea4)

**3. Guarda el secreto de firma**

Copia el secreto de la columna **Secret** del webhook y añádelo a `.env` exactamente como se muestra, con el prefijo `ws_` incluido:

```bash theme={null}
WHOP_WEBHOOK_SECRET=ws_your_secret
```

Reinicia tu servidor para que cargue el nuevo valor.

## Paga con una tarjeta de prueba

Abre la `purchase_url` del paso del checkout y paga con:

| Campo | Valor |
| - | - |
| Número de tarjeta | `4242 4242 4242 4242` |
| Vencimiento | Cualquier fecha futura, como `12/34` |
| CVC | Cualesquiera 3 dígitos, como `123` |
| Dirección de facturación | Cualquier dirección |

En unos segundos, tu servidor registra `payment.succeeded` y el ID del pago, que empieza por `pay_`.

> [!TIP]
>
> Has cobrado un pago y gestionado su webhook de principio a fin. No se ha cobrado nada.

Para probar una tarjeta rechazada o 3D Secure, usa los otros números de [Tarjetas de prueba](https://docs.whop.com/es/developer/guides/sandbox.md#test-cards). Si no llega nada, revisa el registro de entregas del webhook en el panel y [Entrega de webhooks](https://docs.whop.com/es/developer/troubleshooting.md#webhook-delivery).

## Pasa a producción

El sandbox y la producción no comparten nada, así que pasar a producción significa repetir la configuración en whop.com con credenciales de producción. Tu código no cambia. Solo cambian los valores de tu entorno.

**1. Crea una clave de producción**

Inicia sesión en [whop.com](https://whop.com/start), abre [whop.com/dashboard/developer](https://whop.com/dashboard/developer) y crea una clave de API de Account solo con los permisos que usa tu integración.

**2. Cambia cada valor por su equivalente de producción**

En tu entorno de producción, establece las tres variables con valores de producción. Nunca reutilices una clave o un secreto de sandbox en producción, ni al revés.

```bash Sandbox theme={null}
WHOP_ENVIRONMENT=sandbox
WHOP_API_KEY=your_sandbox_key
WHOP_WEBHOOK_SECRET=ws_your_sandbox_secret
```

```bash Production theme={null}
WHOP_ENVIRONMENT=production
WHOP_API_KEY=your_production_key
WHOP_WEBHOOK_SECRET=ws_your_production_secret
```

Si llamas a la API directamente, cambia la URL base a `https://api.whop.com/api/v1`.

**3. Vuelve a crear lo que hiciste en el sandbox**

Los productos, las variantes, las configuraciones de checkout y los webhooks no se trasladan. Crea el webhook de producción con tu URL de producción y guarda su nuevo secreto de firma.

**4. Fija tu versión de la API**

El SDK envía la versión con la que se compiló. Si llamas a la API directamente, envía `Api-Version-Date` en cada solicitud para que los cambios posteriores no alteren tus respuestas. Consulta [Versionado de la API](https://docs.whop.com/es/developer/api/versioning.md).

> [!WARNING]
>
> Los enlaces de checkout de producción cobran dinero real. Comprueba qué clave tienes antes de ejecutar cualquier cosa que cree un cargo o mueva un saldo.

## Ahora construye lo que viniste a hacer

> [card] [Vendes una suscripción o un producto de pago único](https://docs.whop.com/es/developer/guides/accept-payments.md)
>
> Enlaces de checkout, el elemento Checkout, variantes y pruebas gratuitas.

> [card] [Debes dinero a otras personas](https://docs.whop.com/es/developer/platforms/manual-payouts.md)
>
> Pagos salientes, transferencias, saldos y el portal de pagos.

> [card] [Te quedas con una parte de lo que venden otros](https://docs.whop.com/es/developer/platforms/quickstart.md)
>
> Subcuentas, cobros en su nombre y pagos a ellas.

> [card] [Quieres distribución, no solo infraestructura](https://docs.whop.com/es/developer/guides/app-views.md)
>
> Apps que se ejecutan dentro de Whop, con autenticación, vistas y la CLI.

> [card] [Tu producto necesita que las personas hablen entre sí](https://docs.whop.com/es/developer/guides/chat/quickstart.md)
>
> Chat, mensajes directos y foros que puedes integrar.

> [card] [Solo quieres leer la referencia](https://docs.whop.com/es/api-reference/overview.md)
>
> Todos los recursos de la API actual, con un playground en cada endpoint.


## Related topics

- [Conceptos principales de la API de Whop](https://docs.whop.com/es/developer/concepts.md)
- [Inicio rápido de plataformas](https://docs.whop.com/es/developer/platforms/quickstart.md)
- [Solución de problemas de integraciones con Whop](https://docs.whop.com/es/developer/troubleshooting.md)
