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

# Installations d'applications

> Sachez quand un compte installe ou supprime votre application, et reliez chaque installation à l'enregistrement correspondant dans votre propre système.

Une installation d'application correspond à une installation de votre application sur un compte Whop. Votre application reçoit `app_installation.created` lorsqu'un compte l'installe et `app_installation.deleted` lorsqu'un compte la supprime. Chaque installation stocke également deux valeurs que seule votre application peut modifier. `external_id` relie l'installation à un enregistrement de votre système, et `metadata` contient de petites valeurs, comme un curseur de synchronisation.

## Une boutique en ligne qui encaisse des paiements via Whop

Ce guide suit une application fictive. Market Lane est un outil de création de boutiques en ligne, et son application Whop permet à une entreprise d'encaisser des paiements sur sa boutique Market Lane via Whop. Chaque boutique possède un identifiant, comme `river-coffee`, et chaque paiement sur Market Lane commence par cet identifiant.

Market Lane doit connaître trois choses :

1. Le moment où une entreprise installe l'application, afin de connecter la boutique de l'entreprise.
2. Le compte Whop qui encaisse le paiement lorsqu'un paiement commence sur une boutique.
3. Le moment où une entreprise supprime l'application, afin que sa boutique cesse de proposer Whop au moment du paiement.

**1. Demander les permissions dont votre application a besoin**

Dans les [permissions](https://docs.whop.com/fr/developer/guides/permissions.md) de votre application, demandez `checkout_configuration:create` pour créer des paiements sur le compte, et `webhook_receive:payments` pour être notifié lorsqu'ils sont réglés. L'entreprise approuve les deux lorsqu'elle installe l'application.

**2. Abonner le webhook de votre application**

Créez un webhook qui appartient à votre application, et non à votre compte : définissez `resource_id` sur l'ID de votre application. Il reçoit les événements d'installation de chaque compte qui installe votre application, ainsi que les événements de paiement autorisés par ces comptes.

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/webhooks" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://marketlane.example/webhooks/whop",
    "resource_id": "app_XXXXXXXX",
    "events": ["app_installation.created", "app_installation.deleted", "payment.succeeded"]
  }'
```

La clé doit disposer de `developer:manage_webhook` sur le compte propriétaire de l'application. Conservez le `webhook_secret` de la réponse et vérifiez chaque livraison comme décrit dans [Webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md).

Seuls les webhooks propres à votre application reçoivent les événements d'installation. Les webhooks d'un compte ne les reçoivent jamais, même pour les applications installées sur ce compte.

**3. Connecter la boutique lorsqu'une entreprise installe l'application**

`app_installation.created` contient l'installation dans `data`. Le champ `account_id` de l'enveloppe correspond à l'entreprise qui a installé l'application :

```json theme={null}
{
  "type": "app_installation.created",
  "account_id": "biz_J8n2R5p9T1w4Kx",
  "data": {
    "id": "aag_T4k8M2p6W9r3Qx",
    "app": { "id": "app_XXXXXXXX", "name": "Market Lane" },
    "account": { "id": "biz_J8n2R5p9T1w4Kx", "title": "River Coffee" },
    "external_id": null,
    "metadata": {},
    "requesting_reauthorization": false
  }
}
```

Market Lane demande à l'entreprise quelle boutique connecter. Lorsqu'elle choisit `river-coffee`, Market Lane enregistre l'identifiant sur l'installation en tant que `external_id` :

```bash theme={null}
curl -X PATCH "https://api.whop.com/api/v1/app_installations/aag_T4k8M2p6W9r3Qx" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "river-coffee",
    "metadata": { "connected_at": "2026-10-26T00:00:00Z" }
  }'
```

**4. Trouver le compte lorsqu'un paiement commence**

Un client passe commande sur `river-coffee`. La requête ne contient que l'identifiant de la boutique : Market Lane recherche donc l'installation par `external_id` :

```bash theme={null}
curl "https://api.whop.com/api/v1/app_installations?external_id=river-coffee" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY"
```

Le résultat contient au plus une installation, et son `account.id` est le compte qui encaisse le paiement. Market Lane crée un paiement sur ce compte avec `POST /checkout_configurations`, place son propre ID de commande dans `metadata` et redirige le client vers la `purchase_url`. Market Lane ne conserve aucune table de correspondance entre identifiants de boutique et comptes Whop, car l'installation fait office de correspondance.

**5. Marquer la commande comme payée**

`payment.succeeded` arrive sur le même webhook. Son `account_id` est l'entreprise de la boutique, et le paiement contient les `metadata` du paiement initial : Market Lane retrouve donc la commande grâce à son ID et la marque comme payée.

**6. Désactiver les paiements Whop lorsque l'entreprise supprime l'application**

`app_installation.deleted` arrive dès qu'une entreprise supprime votre application. Market Lane cesse immédiatement de proposer Whop au moment du paiement sur `river-coffee`, afin qu'aucun client n'atteigne un paiement voué à l'échec. L'installation n'apparaît plus dans `GET /app_installations`, et votre application ne peut plus agir sur ce compte.

**7. Reconnecter lors d'une réinstallation**

Si l'entreprise installe à nouveau l'application, vous recevez un nouvel événement `app_installation.created`. Il s'agit de la même installation : `id`, `created_at`, `external_id` et `metadata` sont tous restaurés. Market Lane voit `external_id: "river-coffee"` dans la charge utile et réactive les paiements Whop pour cette boutique, sans demander à l'entreprise de la reconnecter.

## Stocker votre propre ID sur une installation

* **`external_id` est unique parmi les installations de votre application.** Définir une valeur déjà utilisée par une autre installation renvoie une erreur `409` : deux entreprises ne peuvent donc jamais revendiquer la même boutique. Les valeurs sont sensibles à la casse : `River-Coffee` et `river-coffee` sont différentes.
* **`metadata` est fusionné.** Les clés que vous envoyez sont définies, une clé définie sur `null` est supprimée, les clés que vous omettez ne changent pas, et `{}` efface toutes les clés. Les valeurs sont des chaînes de caractères.
* **Une installation supprimée conserve son `external_id`.** Tant qu'une entreprise a supprimé votre application, aucune autre installation de votre application ne peut prendre cette valeur. Si l'entreprise installe à nouveau l'application, la valeur est restaurée avec elle.
* **Ne stockez pas de secrets.** Votre compte développeur peut lire `metadata` et `external_id`.

## Gérer les événements répétés

* **Attendez-vous à des répétitions.** Une entreprise peut installer, supprimer, puis réinstaller votre application. Traitez un `app_installation.created` portant sur une installation que vous connaissez déjà comme une réinstallation.
* **Ignorez les doublons grâce au `webhook-id`.** Whop relance les livraisons qui ne reçoivent pas de réponse `2xx`, et une relance conserve le même `webhook-id`.

## Qui peut lire les installations

| Appelant | Accès |
| - | - |
| La clé API de votre application | Liste, récupère et met à jour les installations de votre application, y compris `metadata` et `external_id`. La clé doit disposer de `developer:app_installation:read` pour la lecture et de `developer:app_installation:update` pour la mise à jour. |
| Votre compte développeur | Liste toutes les installations de votre application avec `GET /app_installations?app_id=app_XXXXXXXX`. Nécessite `developer:basic:read`. |
| Le compte sur lequel l'application est installée | Liste les applications installées sur ce compte. Il voit toujours `metadata` et `external_id` avec la valeur `null`. |

## Étapes suivantes

> [card] [Webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md)
>
> Vérifiez les signatures, gérez les relances et consultez tous les événements.

> [card] [Référence de l'API App Installations](https://docs.whop.com/fr/api-reference/app-installations/app-installation)
>
> Tous les champs et endpoints des installations d'applications.

> [card] [Accepter des paiements](https://docs.whop.com/fr/developer/guides/accept-payments.md)
>
> Créez des paiements et livrez les commandes à partir de `payment.succeeded`.

> [card] [Permissions](https://docs.whop.com/fr/developer/guides/permissions.md)
>
> Déclarez les permissions que votre application demande lors de l'installation.


## Related topics

- [Vues d'application](https://docs.whop.com/fr/developer/guides/app-views.md)
- [Build d'application](https://docs.whop.com/fr/api-reference/legacy/app-builds/app-build.md)
- [Authentification et clés API](https://docs.whop.com/fr/developer/guides/auth-scoping.md)
