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

# Intégrer un checkout

> Intégrez l'intégralité du checkout de Whop dans votre page avec l'élément Checkout, directement depuis le navigateur, et traitez la commande depuis un webhook

Intégrez l'intégralité du checkout de Whop dans votre propre page avec l'élément Checkout. Il s'exécute entièrement dans le navigateur. Votre serveur se contente d'écouter le webhook qui indique que l'acheteur a payé.

Les fichiers sous **Code** contiennent des commentaires `Step X.Y` qui renvoient aux étapes ci-dessous. Choisissez une implémentation serveur et une implémentation client. La liste comprend les fichiers de chaque option.

## Intégrer le checkout

### 1.1 Installer les paquets (React)

Installez les paquets Whop Elements pour 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 Ajouter la balise script (JavaScript)

Chargez le script Whop Elements sur la page qui héberge le checkout.

### 1.2 Monter l'élément Checkout

Montez `CheckoutElement` dans un handle `Checkout` et passez la variante via la propriété `plan` existante. L'élément ouvre lui-même la session de checkout, calcule le prix de la commande et collecte tout ce que le vendeur a configuré. Il ne nécessite aucun code serveur ni aucune clé API sur la page : la variante définit le prix, donc le navigateur n'impose jamais de montant.

Passez des `metadata`, comme votre propre ID de commande, sur le handle. Whop les copie sur le paiement et sur chaque webhook qui le concerne. Définissez `returnUrl` sur une page que vous hébergez en `https`. L'acheteur y arrive après une étape de paiement externe, comme 3D Secure, une page bancaire ou une demande de financement. Ajoutez-y vos propres paramètres de requête, comme l'ID de commande. Ils sont conservés pendant l'aller-retour.

Pour associer un code d'affiliation, un code promo ou une attribution de campagne, passez `affiliateCode`, `promoCode` ou `attribution` sur le handle. Une [configuration de checkout](https://docs.whop.com/fr/api-reference/checkout-configurations/create-a-checkout-configuration.md) créée sur votre serveur n'est nécessaire que si vous souhaitez garder ces préréglages hors du code client.

### 1.3 Enregistrer la finalisation

`onComplete` se déclenche une fois lorsque le checkout se termine dans l'élément, avant toute navigation vers `returnUrl`. Utilisez-le pour les analyses et les pixels publicitaires.

N'exécutez pas la commande à partir de ce callback. Un checkout restauré lors d'un chargement ultérieur de la page le déclenche à nouveau pour le même résultat, et une étape de paiement externe se termine plutôt sur la page de retour.

## Gérer la page de retour

### 2.1 Lire le résultat dans l'URL

L'acheteur arrive sur `returnUrl` **quoi qu'il se soit passé** pendant l'étape externe. Whop ajoute deux paramètres de requête. `payment` est l'ID `pay_`. `status` vaut `succeeded` lorsque l'acheteur a payé, et `failed` ou `canceled` dans le cas contraire. Une demande de financement refusée par le prêteur arrive ici avec `status=canceled`, exactement comme une demande approuvée arrive avec `status=succeeded`.

Vos propres paramètres, comme `order`, restent dans l'URL. Les refus de carte n'atteignent jamais cette page, car l'élément les affiche directement. La page de retour est le seul endroit où votre site voit un paiement externe échoué.

### 2.2 Afficher le bon écran

Faites un branchement sur `status`. `succeeded` affiche la page de remerciement. `failed` et `canceled` affichent un message indiquant que l'acheteur n'a pas été débité, ainsi qu'un lien pour revenir au checkout. Toute autre valeur, comme `processing`, signifie que le paiement est encore en attente. Indiquez à l'acheteur que vous confirmerez par e-mail.

Considérez cette page comme un affichage du résultat, et non comme une preuve de paiement. N'importe qui peut saisir `status=succeeded` dans une URL. L'accès, les téléchargements et l'exécution des commandes proviennent du webhook `payment.succeeded` sur votre serveur.

## Exécuter la commande depuis votre serveur

### 3.1 Installer le SDK Whop (Next.js)

L'utilitaire de webhook est fourni avec le SDK Whop. Installez-le sur le serveur qui reçoit le webhook.

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

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

### 3.1 Installer le SDK Whop (Express)

L'utilitaire de webhook est fourni avec le SDK Whop. Installez-le sur le serveur qui reçoit le webhook.

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

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

### 3.1 Installer le SDK Whop (Python)

L'utilitaire de webhook est fourni avec le SDK Whop. Installez-le sur le serveur qui reçoit le webhook.

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

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

### 3.2 Gérer le webhook de paiement

Whop envoie `payment.succeeded` à votre endpoint de webhook une fois que l'acheteur a payé. Vérifiez la signature avec l'utilitaire du SDK, puis exécutez la commande : marquez la commande comme payée, accordez l'accès et envoyez l'e-mail. Le paiement contient les `metadata` que vous avez définies sur le handle Checkout.

L'exécution de la commande a sa place ici et nulle part ailleurs. L'acheteur peut fermer le navigateur avant le chargement de votre page de retour, une redirection peut échouer, et n'importe qui peut saisir un paramètre de requête à la main. Suivez le [guide des webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md) pour créer le webhook et stocker son secret `ws_` dans `WHOP_WEBHOOK_SECRET`.

## Code

### Client : 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>
	);
}
```

### Client : 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>
	);
}
```

### Client : 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>
```

### Client : 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>
```

### Serveur : 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.
}
```

### Serveur : 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);
```

### Serveur : 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.
```

## Prochaines étapes

* [Référence de l'élément Checkout](https://docs.whop.com/fr/elements/latest/checkout/overview) : chaque option, événement et méthode du handle Checkout.
* [Créer un checkout avec les éléments de paiement](https://docs.whop.com/fr/developer/guides/payment-elements.md) : concevez vous-même le formulaire et confirmez le paiement depuis votre serveur.
* [Webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md) : créez l'endpoint, stockez le secret de signature et gérez les nouvelles tentatives.
* [Tester dans le sandbox](https://docs.whop.com/fr/developer/guides/sandbox.md) : effectuez un paiement de test avec des cartes qui réussissent, échouent ou nécessitent une action.


## Related topics

- [Créer un checkout avec les Payment Elements](https://docs.whop.com/fr/developer/guides/payment-elements.md)
- [Ajouter Express Checkout](https://docs.whop.com/fr/developer/guides/express-checkout.md)
- [Vue d'ensemble des paiements](https://docs.whop.com/fr/developer/payments/overview.md)
