Skip to main content
Una instalación de app es una instalación de tu app en una cuenta de Whop. Tu app recibe app_installation.created cuando una cuenta la instala y app_installation.deleted cuando una cuenta la elimina. Cada instalación también guarda dos valores que solo tu app puede cambiar. external_id vincula la instalación con un registro de tu sistema, y metadata contiene valores pequeños, como un cursor de sincronización.

Una tienda online que cobra pagos a través de Whop

Esta guía sigue una app inventada. Market Lane es un creador de tiendas online, y su app de Whop permite que un negocio cobre pagos en su tienda de Market Lane a través de Whop. Cada tienda tiene un identificador, como river-coffee, y cada checkout en Market Lane empieza con ese identificador. Market Lane necesita saber tres cosas:
  1. Cuándo un negocio instala la app, para poder conectar la tienda del negocio.
  2. Qué cuenta de Whop recibe el pago cuando empieza un checkout en una tienda.
  3. Cuándo un negocio elimina la app, para que su tienda deje de ofrecer Whop en el checkout.
1

Solicita los permisos que necesita tu app

En los permisos de tu app, solicita checkout_configuration:create para crear checkouts en la cuenta y webhook_receive:payments para enterarte de cuándo se pagan. El negocio aprueba ambos cuando instala la app.
2

Suscribe el webhook de tu app

Crea un webhook que pertenezca a tu app, no a tu cuenta: establece resource_id con el ID de tu app. Recibe los eventos de instalación de cada cuenta que instala tu app, además de los eventos de pago que esas cuentas concedieron.
La clave necesita developer:manage_webhook en la cuenta propietaria de la app. Guarda el webhook_secret de la respuesta y verifica cada entrega como se describe en Webhooks.Solo los webhooks propios de tu app reciben eventos de instalación. Los webhooks de una cuenta nunca los reciben, ni siquiera para las apps instaladas en esa cuenta.
3

Conecta la tienda cuando un negocio instala la app

app_installation.created lleva la instalación en data. El account_id del sobre es el negocio que instaló la app:
Market Lane pregunta al negocio qué tienda conectar. Cuando elige river-coffee, Market Lane guarda el identificador en la instalación como external_id:
4

Encuentra la cuenta cuando empieza un checkout

Un comprador hace el checkout en river-coffee. La solicitud solo lleva el identificador de la tienda, así que Market Lane busca la instalación por external_id:
El resultado tiene como máximo una instalación, y su account.id es la cuenta que recibe el pago. Market Lane crea un checkout en esa cuenta con POST /checkout_configurations, pone su propio ID de pedido en metadata y envía al comprador a la purchase_url. Market Lane no mantiene ninguna tabla de identificadores de tienda y cuentas de Whop, porque la instalación es la correspondencia.
5

Marca el pedido como pagado

payment.succeeded llega al mismo webhook. Su account_id es el negocio de la tienda y el pago lleva los metadata del checkout, así que Market Lane encuentra el pedido por su ID y lo marca como pagado.
6

Desactiva los pagos de Whop cuando el negocio elimina la app

app_installation.deleted llega en cuanto un negocio elimina tu app. Market Lane deja de ofrecer Whop en el checkout de river-coffee de inmediato, para que ningún comprador llegue a un checkout que fallaría. La instalación deja de aparecer en GET /app_installations y tu app ya no puede actuar sobre esa cuenta.
7

Vuelve a conectar al reinstalar

Si el negocio vuelve a instalar la app, recibes otro app_installation.created. Es la misma instalación: el id, created_at, external_id y metadata vuelven todos. Market Lane ve external_id: "river-coffee" en la carga útil y reactiva los pagos de Whop para esa tienda, sin pedir al negocio que la vuelva a conectar.

Guarda tu propio ID en una instalación

  • external_id es único entre las instalaciones de tu app. Establecer un valor que ya tiene otra instalación devuelve un 409, así que dos negocios nunca pueden reclamar la misma tienda. Los valores distinguen mayúsculas y minúsculas: River-Coffee y river-coffee son distintos.
  • metadata se fusiona. Las claves que envías se establecen, una clave con valor null se elimina, las claves que omites no cambian y {} borra todas las claves. Los valores son cadenas.
  • Una instalación eliminada conserva su external_id. Mientras un negocio tenga tu app eliminada, ninguna otra instalación de tu app puede tomar ese valor. Si el negocio vuelve a instalar la app, el valor regresa con ella.
  • No guardes secretos. Tu cuenta de desarrollador puede leer metadata y external_id.

Gestionar eventos repetidos

  • Cuenta con repeticiones. Un negocio puede instalar, eliminar y volver a instalar tu app. Trata un app_installation.created de una instalación que ya conoces como una reinstalación.
  • Ignora los duplicados por webhook-id. Whop reintenta las entregas que no obtienen una respuesta 2xx, y un reintento conserva el mismo webhook-id.

Quién puede leer las instalaciones

Próximos pasos

Webhooks

Verifica firmas, gestiona reintentos y consulta todos los eventos.

Referencia de la API de instalaciones de apps

Todos los campos y endpoints de las instalaciones de apps.

Aceptar pagos

Crea checkouts y entrega pedidos a partir de payment.succeeded.

Permisos

Declara los permisos que tu app solicita al instalarse.