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

# Ajouter Express Checkout

> Placez des boutons Apple Pay et Google Pay en un seul clic sur votre page avec l'élément Express Checkout, directement depuis le navigateur, et traitez la commande depuis un webhook

Ajoutez des boutons Apple Pay et Google Pay en un geste sur une page produit avec l'élément Express Checkout. Whop affiche les portefeuilles avec lesquels l'appareil peut payer et confirme le paiement pour vous. Votre serveur se contente d'écouter le webhook.

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.

## Ajouter les boutons de portefeuille

### 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 affiche les boutons.

### 1.2 Monter les boutons

Montez `ExpressCheckoutElement` dans un handle `Checkout` et passez la variante via la propriété `plan` existante. L'élément n'affiche que les portefeuilles avec lesquels l'appareil de l'acheteur peut payer, en commençant par le plus natif pour le navigateur, et n'affiche rien lorsqu'aucun portefeuille n'est disponible. Conservez un parcours de checkout classique sur la page pour ces acheteurs.

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`. Un achat terminé redirige l'onglet vers cette page, tout comme un paiement qui a nécessité une étape en pleine page.

Les portefeuilles ne s'ouvrent que sur les pages dont le domaine est prêt pour Apple Pay. Suivez [Activer Apple Pay et Google Pay](https://docs.whop.com/fr/payments/apple-pay.md) une fois par domaine, servez la page en `https` et testez sur un véritable appareil sur lequel un portefeuille est configuré.

### 1.3 Choisir les portefeuilles et la disposition

`wallets` limite les portefeuilles pouvant s'afficher, par exemple `["apple_pay"]`. L'élément n'affiche jamais un portefeuille que l'appareil ou la configuration des moyens de paiement du checkout ne peut pas prendre en charge : la liste est donc un plafond, pas une promesse.

`layout` organise les boutons. `auto` suit la largeur du conteneur, et `horizontal` ou `vertical` impose une disposition. `appearance` sur le handle applique un thème aux lignes de résultat et d'erreur de l'élément.

### 1.4 Enregistrer la finalisation

Un appui ouvre la fenêtre du portefeuille. Lorsque l'acheteur autorise le paiement, Whop le confirme sur la session de checkout, et la coche de la fenêtre suit cette confirmation. `onComplete` se déclenche une fois le résultat établi, 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. Un paiement parti vers une étape en pleine page se termine plutôt sur la page de retour.

## Gérer la page de retour

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

La plupart des paiements par portefeuille se règlent directement, et un paiement qui nécessite encore une étape l'exécute dans une boîte de dialogue lorsque l'étape s'y prête. Une étape qui ne peut s'exécuter qu'en pleine page, comme une redirection bancaire, quitte la page et renvoie l'acheteur vers `returnUrl` **quoi qu'il se soit passé**. 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.

Vos propres paramètres, comme `order`, restent dans l'URL. L'élément signale lui-même les refus en ligne, si bien que la page de retour est le seul endroit où votre site voit une étape externe échouée.

### 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 produit. 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. Un paiement par portefeuille indique `apple_pay` ou `google_pay` dans `payment_method_type`, et 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 — `BuyButton.tsx`

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

export function BuyButton({ orderId }: { orderId: string }) {
	return (
		<WhopElements elements={loadWhop()}>
			{/* Step 1.2: Mount the buttons */}
			<Checkout
				plan="plan_xxxxxxxxxxxxx"
				metadata={{ order_id: orderId }}
				returnUrl={`https://yoursite.com/checkout/return?order=${orderId}`}
				// Step 1.4: 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("Express checkout completed", completion.paymentId);
					}
				}}
			>
				{/* Step 1.3: Pick the wallets and layout */}
				<ExpressCheckoutElement layout="horizontal" wallets={["apple_pay", "google_pay"]} />
			</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 — `buy.html`

```html buy.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="express-checkout"></div>

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

      // Step 1.2: Mount the buttons
      const checkout = window.WhopElements().checkout.create({
        plan: "plan_xxxxxxxxxxxxx",
        metadata: { order_id: orderId },
        returnUrl: `https://yoursite.com/checkout/return?order=${orderId}`,
        // Step 1.4: 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("Express checkout completed", completion.paymentId);
          }
        },
      });
      // Step 1.3: Pick the wallets and layout
      checkout
        .create("expressCheckout", { layout: "horizontal", wallets: ["apple_pay", "google_pay"] })
        .mount("#express-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 Express Checkout](https://docs.whop.com/fr/elements/latest/checkout/expressCheckout.md) : chaque option, événement et point d'accroche de style de l'élément.
* [Ouvrir une feuille de wallet depuis votre propre bouton](https://docs.whop.com/fr/developer/guides/payment-request.md) : affichez vous-même le bouton et fixez vous-même le prix de la commande avec la ressource payment request.
* [Activer Apple Pay et Google Pay](https://docs.whop.com/fr/payments/apple-pay.md) : ajoutez Apple Pay à votre domaine.
* [Intégrer un checkout](https://docs.whop.com/fr/developer/guides/embed-checkout.md) : le formulaire de checkout complet, qui affiche déjà les boutons de wallet au-dessus.


## Related topics

- [ExpressCheckoutElement](https://docs.whop.com/fr/elements/latest/checkout/expressCheckout.md)
- [Checkout](https://docs.whop.com/fr/elements/latest/checkout/overview.md)
- [Ouvrir une feuille de portefeuille depuis votre propre bouton](https://docs.whop.com/fr/developer/guides/payment-request.md)
