Skip to main content
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 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.
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.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 :
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 :
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 :
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

Étapes suivantes

Webhooks

Vérifiez les signatures, gérez les relances et consultez tous les événements.

Référence de l'API App Installations

Tous les champs et endpoints des installations d’applications.

Accepter des paiements

Créez des paiements et livrez les commandes à partir de payment.succeeded.

Permissions

Déclarez les permissions que votre application demande lors de l’installation.