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

# Een checkout insluiten

> Plaats de volledige checkout van Whop op je pagina met het Checkout-element, rechtstreeks vanuit de browser, en lever uit vanuit een webhook

Plaats de volledige checkout van Whop op je eigen pagina met het Checkout-element. Het draait volledig in de browser. Je server luistert alleen naar de webhook die meldt dat de koper heeft betaald.

De bestanden onder **Code** bevatten `Step X.Y`-opmerkingen die verwijzen naar de stappen hieronder. Kies één serverimplementatie en één clientimplementatie. De lijst bevat de bestanden voor elke optie.

## De checkout insluiten

### 1.1 De pakketten installeren (React)

Installeer de Whop Elements-pakketten voor 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 De scripttag toevoegen (JavaScript)

Laad het Whop Elements-script op de pagina waarop de checkout staat.

### 1.2 Het Checkout-element koppelen

Koppel `CheckoutElement` binnen een `Checkout`-handle en geef de variant door via de bestaande eigenschap `plan`. Het element opent zelf de checkoutsessie, berekent de prijs van de bestelling en verzamelt alles wat de verkoper heeft ingesteld. Er is geen servercode en geen API-sleutel op de pagina nodig: de variant bepaalt de prijs, dus de browser geeft nooit zelf een bedrag op.

Geef `metadata`, zoals je eigen bestel-ID, mee op de handle. Whop kopieert die naar de betaling en naar elke webhook erover. Stel `returnUrl` in op een pagina die je via `https` host. De koper komt daar terecht na een betaalstap buiten de site, zoals 3D Secure, een bankpagina of een financieringsaanvraag. Voeg er je eigen queryparameters aan toe, zoals de bestel-ID. Die blijven behouden tijdens de omweg.

Om een affiliatecode, een promotiecode of campagneattributie toe te voegen, geef je `affiliateCode`, `promoCode` of `attribution` mee op de handle. Een [checkoutconfiguratie](https://docs.whop.com/nl/api-reference/checkout-configurations/create-a-checkout-configuration.md) die op je server is aangemaakt, is alleen nodig als je die voorinstellingen buiten de clientcode wilt houden.

### 1.3 De voltooiing vastleggen

`onComplete` wordt één keer aangeroepen wanneer de checkout binnen het element is voltooid, vóór een eventuele navigatie naar `returnUrl`. Gebruik het voor analytics en advertentiepixels.

Lever er niet vanuit uit. Een checkout die bij een latere paginalading wordt hersteld, roept het opnieuw aan voor hetzelfde resultaat, en een betaalstap buiten de site wordt in plaats daarvan op de retourpagina voltooid.

## De retourpagina afhandelen

### 2.1 De uitkomst uit de URL lezen

De koper komt op `returnUrl` terecht, **wat er ook gebeurde** tijdens de stap buiten de site. Whop voegt twee queryparameters toe. `payment` is de `pay_`-ID. `status` is `succeeded` wanneer de koper heeft betaald, en `failed` of `canceled` wanneer dat niet zo is. Een financieringsaanvraag die de kredietverstrekker heeft afgewezen, komt hier terecht met `status=canceled`, precies zoals een goedgekeurde aanvraag terechtkomt met `status=succeeded`.

Je eigen parameters, zoals `order`, blijven in de URL staan. Kaartweigeringen bereiken deze pagina nooit, omdat het element ze inline toont. De retourpagina is de enige plek waar je site een mislukte betaling buiten de site ziet.

### 2.2 De juiste weergave tonen

Vertak op `status`. `succeeded` krijgt de bedankpagina. `failed` en `canceled` krijgen een melding dat de koper niets in rekening is gebracht, plus een link terug naar de checkout. Alles daarbuiten, zoals `processing`, betekent dat de betaling nog in behandeling is. Laat de koper weten dat je per e-mail bevestigt.

Behandel de pagina als een weergave van de uitkomst, niet als betalingsbewijs. Iedereen kan `status=succeeded` in een URL typen. Toegang, downloads en de afhandeling van bestellingen komen voort uit de webhook `payment.succeeded` op je server.

## Uitleveren vanaf je server

### 3.1 De Whop SDK installeren (Next.js)

De webhookhelper wordt meegeleverd met de Whop SDK. Installeer die op de server die de webhook ontvangt.

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

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

### 3.1 De Whop SDK installeren (Express)

De webhookhelper wordt meegeleverd met de Whop SDK. Installeer die op de server die de webhook ontvangt.

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

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

### 3.1 De Whop SDK installeren (Python)

De webhookhelper wordt meegeleverd met de Whop SDK. Installeer die op de server die de webhook ontvangt.

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

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

### 3.2 De betalingswebhook afhandelen

Whop stuurt `payment.succeeded` naar je webhookendpoint zodra de koper heeft betaald. Verifieer de handtekening met de SDK-helper en voer daarna het uitleverwerk uit: markeer de bestelling als betaald, verleen toegang en verstuur de e-mail. De betaling bevat de `metadata` die je op de Checkout-handle hebt ingesteld.

Uitlevering hoort hier thuis en nergens anders. De koper kan de browser sluiten voordat je retourpagina laadt, een doorverwijzing kan mislukken en iedereen kan handmatig een queryparameter typen. Volg de [Webhooks-gids](https://docs.whop.com/nl/developer/guides/webhooks.md) om de webhook aan te maken en het `ws_`-geheim op te slaan als `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>
```

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

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

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

## Volgende stappen

* [Referentie van het Checkout-element](https://docs.whop.com/nl/elements/latest/checkout/overview): elke optie, elk event en elke methode van de Checkout-handle.
* [Een checkout bouwen met payment elements](https://docs.whop.com/nl/developer/guides/payment-elements.md): ontwerp het formulier zelf en bevestig de betaling vanaf je server.
* [Webhooks](https://docs.whop.com/nl/developer/guides/webhooks.md): maak het endpoint aan, bewaar het ondertekeningsgeheim en handel nieuwe pogingen af.
* [Testen in de sandbox](https://docs.whop.com/nl/developer/guides/sandbox.md): voer een testbetaling uit met kaarten die slagen, mislukken en een actie vereisen.


## Related topics

- [Bouw een checkout met payment elements](https://docs.whop.com/nl/developer/guides/payment-elements.md)
- [Express Checkout toevoegen](https://docs.whop.com/nl/developer/guides/express-checkout.md)
- [Betalingen accepteren](https://docs.whop.com/nl/developer/guides/accept-payments.md)
