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

# Démarrage rapide de l'API Whop

> Effectuez votre premier appel à l'API Whop, créez un checkout, payez-le avec une carte de test et recevez le webhook, le tout dans le sandbox. Passez ensuite en production.

Ce démarrage rapide se déroule dans le sandbox, un environnement Whop distinct où l'argent ne circule jamais. Vous allez obtenir une clé API sandbox, effectuer votre premier appel, créer un checkout, le payer avec une carte de test et recevoir le webhook `payment.succeeded` sur votre serveur. La mise en production est la dernière étape, et consiste surtout à échanger des clés.

> [!TIP]
>
> Si vous utilisez un agent de code, donnez-lui cette page au format Markdown, `https://docs.whop.com/developer/quickstart.md`, ou collez le prompt de la page [Vue d'ensemble](https://docs.whop.com/fr/developer/start.md#build-with-your-coding-agent).

## Sandbox et production

Whop exécute deux environnements qui ne partagent rien : ni comptes, ni clés, ni produits, ni webhooks. Vous développez dans le sandbox et lancez en production. Chacune des valeurs ci-dessous change de l'un à l'autre.

| | Sandbox : développer et tester | Production : lancer |
| - | - | - |
| Argent | Ne circule jamais | Réel |
| Tableau de bord | [sandbox.whop.com](https://sandbox.whop.com) | [whop.com](https://whop.com) |
| Clés API et webhooks | [sandbox.whop.com/dashboard/developer](https://sandbox.whop.com/dashboard/developer) | [whop.com/dashboard/developer](https://whop.com/dashboard/developer) |
| URL de base de l'API | `https://sandbox-api.whop.com/api/v1` | `https://api.whop.com/api/v1` |
| Environnement du SDK | `Sandbox` | `Production`, la valeur par défaut du SDK |
| Pages de checkout | `sandbox.whop.com/checkout/...` | `whop.com/checkout/...` |
| `WHOP_ENVIRONMENT` | `sandbox` | `production` |

> [!WARNING]
>
> Les clés API sandbox et production se ressemblent en tout point : rien dans une clé n'indique à quel environnement elle appartient. Les extraits de code de cette page choisissent l'environnement à partir d'une variable `WHOP_ENVIRONMENT` au lieu de le coder en dur, de sorte que le même code fonctionne dans les deux. Le [serveur MCP Whop](https://docs.whop.com/fr/developer/ai/overview.md#mcp-server) agit uniquement sur les données de production.

## Obtenir une clé API sandbox

**1. Inscrivez-vous au sandbox**

Rendez-vous sur [sandbox.whop.com](https://sandbox.whop.com) et créez un compte. Il est distinct de tout compte que vous possédez sur whop.com. Le parcours d'inscription crée votre première entreprise, c'est-à-dire le compte qui possède les clés API, les produits, les webhooks et les paiements.

**2. Créez une clé API de compte**

Ouvrez [sandbox.whop.com/dashboard/developer](https://sandbox.whop.com/dashboard/developer). Dans **Account API Keys**, sélectionnez **Create** et donnez à la clé un nom comme `Local development`.

Pour ce démarrage rapide, utilisez le rôle Admin. Avant la production, passez à un ensemble de permissions personnalisé qui couvre uniquement les endpoints que vous appelez.

**3. Stockez la clé sur votre serveur**

Copiez la clé lorsque Whop l'affiche, puis placez-la dans votre fichier `.env` local avec l'environnement auquel elle appartient :

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

![Section Account API Keys du tableau de bord Whop affichant un nom de clé, une valeur masquée et le bouton Create](https://mintcdn.com/whop/xuW6TKFlagvnbmV0/images/developer-api-key-field.png?fit=max\&auto=format\&n=xuW6TKFlagvnbmV0\&q=85\&s=699bf36af18f7a12dfd855eb0684b38e)

> [!NOTE]
>
> Conservez `WHOP_API_KEY` sur votre serveur. Ne placez pas de clés API dans du code exécuté dans le navigateur, dans des applications mobiles ou dans des dépôts publics. Les clés sandbox et production se ressemblent en tout point : nommez-les de manière à pouvoir les distinguer.

Une clé API de compte convient lorsque votre serveur agit pour votre propre entreprise. Pour créer une app que d'autres entreprises installent, ou pour permettre aux utilisateurs de se connecter avec Whop, consultez [Authentification et clés API](https://docs.whop.com/fr/developer/guides/auth-scoping.md).

## Installer le 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]
>
> Cette page nécessite le SDK 2.7.0 ou une version ultérieure. Les versions antérieures n'acceptent pas le `variant` en ligne dans les configurations de checkout.

## Effectuer votre premier appel

Pointez le client vers l'environnement indiqué dans `WHOP_ENVIRONMENT` et récupérez le compte associé à votre clé. Cela confirme que la clé fonctionne et affiche l'ID de votre compte, qui commence par `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]
>
> Voici votre compte sandbox. La clé fonctionne.

## Créer un checkout

Un seul appel crée une variante et renvoie une `purchase_url`, une page de checkout hébergée sur `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
```

Vous ouvrirez cette URL lors de l'étape de paiement. Si vous avez déjà une variante, passez son ID dans `variant_id` au lieu du `variant` en ligne. Vous ne pouvez pas envoyer les deux. [Créer une configuration de checkout](https://docs.whop.com/fr/api-reference/checkout-configurations/create-a-checkout-configuration.md) liste toutes les options, notamment la tarification récurrente, les essais et les URL de redirection.

## Écouter le webhook

Configurez votre endpoint avant de payer, afin que l'événement `payment.succeeded` ait un point d'arrivée.

**1. Ajoutez un endpoint**

Ajoutez une route `POST` qui vérifie la signature et journalise l'événement. La vérification nécessite le corps brut de la requête : lisez-le donc avant tout parsing 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
```

Pendant le développement, exposez la route en HTTPS avec ngrok, Cloudflare Tunnel ou un autre tunnel.

**2. Créez le webhook dans le tableau de bord sandbox**

Ouvrez **Developer > Webhooks** dans le tableau de bord sandbox, puis sélectionnez **Create webhook**. Collez l'adresse HTTPS de votre endpoint, conservez la version d'API `v1` et sélectionnez `payment.succeeded`.

![Formulaire de création de webhook avec l'événement payment\_succeeded sélectionné dans la liste des événements](https://mintcdn.com/whop/RLIxcN4GVU-CLB5B/images/create-webhook-select-events.png?fit=max\&auto=format\&n=RLIxcN4GVU-CLB5B\&q=85\&s=079887392e21e4680a82415244aeaea4)

**3. Stockez le secret de signature**

Copiez le secret depuis la colonne **Secret** du webhook et ajoutez-le à `.env` exactement tel qu'affiché, préfixe `ws_` compris :

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

Redémarrez votre serveur pour qu'il prenne en compte la nouvelle valeur.

## Payer avec une carte de test

Ouvrez la `purchase_url` obtenue à l'étape du checkout et payez avec :

| Champ | Valeur |
| - | - |
| Numéro de carte | `4242 4242 4242 4242` |
| Date d'expiration | N'importe quelle date future, par exemple `12/34` |
| CVC | 3 chiffres quelconques, par exemple `123` |
| Adresse de facturation | N'importe quelle adresse |

En quelques secondes, votre serveur journalise `payment.succeeded` et l'ID du paiement, qui commence par `pay_`.

> [!TIP]
>
> Vous avez encaissé un paiement et traité son webhook de bout en bout. Rien n'a été débité.

Pour tester une carte refusée ou 3D Secure, utilisez les autres numéros de [Cartes de test](https://docs.whop.com/fr/developer/guides/sandbox.md#test-cards). Si rien n'arrive, consultez le journal de livraison du webhook dans le tableau de bord ainsi que [Livraison des webhooks](https://docs.whop.com/fr/developer/troubleshooting.md#webhook-delivery).

## Passer en production

Le sandbox et la production ne partagent rien : passer en production signifie donc refaire la configuration sur whop.com avec des identifiants de production. Votre code ne change pas. Seules les valeurs de votre environnement changent.

**1. Créez une clé de production**

Connectez-vous sur [whop.com](https://whop.com/start), ouvrez [whop.com/dashboard/developer](https://whop.com/dashboard/developer) et créez une clé API de compte avec uniquement les permissions qu'utilise votre intégration.

**2. Remplacez chaque valeur par son équivalent de production**

Dans votre environnement de production, définissez les trois variables avec des valeurs de production. Ne réutilisez jamais une clé ou un secret sandbox en production, ni l'inverse.

```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 vous appelez l'API directement, remplacez l'URL de base par `https://api.whop.com/api/v1`.

**3. Recréez ce que vous avez créé dans le sandbox**

Les produits, variantes, configurations de checkout et webhooks ne sont pas transférés. Créez le webhook de production avec votre URL de production et stockez son nouveau secret de signature.

**4. Fixez votre version d'API**

Le SDK envoie la version avec laquelle il a été construit. Si vous appelez l'API directement, envoyez `Api-Version-Date` avec chaque requête afin que les changements ultérieurs ne modifient pas vos réponses. Consultez [Versionnage de l'API](https://docs.whop.com/fr/developer/api/versioning.md).

> [!WARNING]
>
> Les liens de checkout de production encaissent de l'argent réel. Vérifiez quelle clé vous utilisez avant d'exécuter quoi que ce soit qui crée un débit ou déplace un solde.

## Construisez maintenant ce pour quoi vous êtes venu

> [card] [Vous vendez un abonnement ou un produit à paiement unique](https://docs.whop.com/fr/developer/guides/accept-payments.md)
>
> Liens de checkout, élément Checkout, variantes et essais.

> [card] [Vous devez de l'argent à d'autres personnes](https://docs.whop.com/fr/developer/platforms/manual-payouts.md)
>
> Versements, transferts, soldes et portail de versement.

> [card] [Vous prélevez une part de ce que d'autres vendent](https://docs.whop.com/fr/developer/platforms/quickstart.md)
>
> Sous-comptes, encaissement en leur nom et versements.

> [card] [Vous voulez de la distribution, pas seulement de l'infrastructure](https://docs.whop.com/fr/developer/guides/app-views.md)
>
> Des apps qui s'exécutent dans Whop, avec authentification, vues et CLI.

> [card] [Votre produit a besoin que les gens échangent entre eux](https://docs.whop.com/fr/developer/guides/chat/quickstart.md)
>
> Chat, messages privés et forums intégrables.

> [card] [Vous voulez simplement lire la référence](https://docs.whop.com/fr/api-reference/overview.md)
>
> Chaque ressource de l'API actuelle, avec un playground sur chaque endpoint.
