Arquitectura de membresías recurrentes y suscripciones
Para clubes deportivos, espacios de coworking, redes de transporte, cajas de suscripción y asociaciones profesionales, los pases de monedero digital actúan como credenciales de membresía dinámicas en tiempo real. A diferencia de las tarjetas estáticas, un pase de suscripción en Apple Wallet y Google Wallet puede actualizar automáticamente su fecha de caducidad, su estado de membresía y la validez del código de barras a medida que los ciclos de facturación recurrente se renuevan, fallan o se cancelan.
Passinstance sincroniza los acuerdos de facturación por suscripción (desde Stripe Billing, PayPal Subscriptions o motores de suscripción propios) con el ciclo de vida del pase mediante controladores de webhooks automatizados y notificaciones push silenciosas:
Vincular suscripciones de pago a registros de pases
Para garantizar una sincronización continua del ciclo de vida recurrente, cada pase debe estar vinculado al registro de suscripción del cliente mediante el campo externalId:
-
1
Cuando el cliente se suscribe: Al crearse una suscripción inicial en Stripe o PayPal, su backend o la integración de pago de Passinstance captura el ID de suscripción (por ejemplo,
sub_1Q8xYz2e...) o el ID de cliente (por ejemplo,cus_987654...). -
2
Vinculación a
externalId: Passinstance almacena este identificador enPass.externalId. -
3
Configuración de la caducidad inicial: El campo
expirationDateinicial del pase se fija en la marca temporal Unix decurrent_period_endproporcionada por el proveedor de facturación.
Eventos de webhook del ciclo de vida y acciones automatizadas
Passinstance escucha los webhooks de facturación recurrente y activa las actualizaciones de estado correspondientes en el pase:
1. Suscripción renovada (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
Cuando un pago de suscripción mensual o anual se procesa correctamente:
-
Acción: Passinstance localiza el pase que coincide con
externalIdy extiendepass.expirationDatehasta la nueva fecha de finalización del ciclo de facturación. -
Actualización de campos: Cualquier campo dinámico que muestre
{validUntil}o{membershipExpiry}se actualiza con la nueva fecha. -
Notificación push: Apple Wallet recibe una actualización APNs silenciosa y Google Wallet actualiza el objeto vía REST. La pantalla de bloqueo puede mostrar un aviso discreto de actualización (por ejemplo, "Membresía renovada hasta el 31 de marzo").
2. Pago fallido / vencido (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
Si un cargo recurrente falla debido a una tarjeta caducada o fondos insuficientes:
-
Acción: El pase permanece activo durante el periodo de gracia configurado (por ejemplo, 7 días).
-
Actualización de campos: Un campo auxiliar o secundario cambia de
"ACTIVE"a"PAYMENT PAST DUE". -
Notificación de alerta: Se envía una notificación push al dispositivo del cliente: "Por favor, actualice su método de pago para mantener activa su membresía."
3. Suscripción cancelada o terminada (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
Cuando un cliente cancela su suscripción:
-
Acción: Al concluir el periodo ya pagado, Passinstance actualiza el estado del pase a
EXPIREDo establecepass.voided = true. -
Desactivación visual: Apple Wallet tacha el código de barras de acceso y muestra la etiqueta "Pase anulado". Google Wallet marca la tarjeta como caducada.
-
Rechazo en escáner: La validación física en tornos de gimnasio o recepción con Passinstance Scanner muestra de inmediato una pantalla roja con
EXPIREDoVOIDED.
Configuración paso a paso: conectar Stripe Billing con Passinstance
Paso 1: conecte Stripe en la configuración del espacio de trabajo
-
1
Vaya a Configuración -> Integraciones -> Pagos en el panel de control de Passinstance.
-
2
Conecte su cuenta de Stripe.
Paso 2: registre el endpoint de webhook en Stripe
En Stripe Dashboard -> Developers -> Webhooks, añada un endpoint que apunte a Passinstance:
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Seleccione los siguientes eventos:
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Paso 3: configure las reglas de caducidad de pases por suscripción
En la configuración de su plantilla de pase:
-
1
Abra Funcionalidades -> Caducidad y validez.
-
2
Seleccione Caducidad dinámica por suscripción.
-
3
Elija el comportamiento tras la cancelación: Caducar pase (permanece en el historial del monedero) o Anular pase (tacha el código de barras inmediatamente).
Gestión del estado de suscripción con Passinstance Scanner
Cuando el personal del gimnasio o los anfitriones del recinto escanean el pase de un socio con la aplicación Passinstance Scanner (Passinstance Scanner):
| Estado de la suscripción | Pantalla del escáner | Respuesta del escáner | Resultado |
|---|---|---|---|
| Activa y pagada | Pantalla verde | VALID | Acceso permitido al socio. Muestra el nombre del cliente y su nivel activo. |
| Pago vencido (periodo de gracia) | Pantalla ámbar | WARNING | Alerta al personal: "Periodo de gracia activo. Solicite al socio que actualice su tarjeta." |
| Cancelada / caducada | Pantalla roja | EXPIRED | El torno permanece bloqueado. Muestra "Membresía caducada el [Fecha]". |
| Revocada / anulada | Pantalla roja | VOIDED | Acceso bloqueado. Muestra "La tarjeta ha sido anulada por el emisor". |
Documentación relacionada
-
Venta de pases — Venta única de pases de pago mediante PassFlow.
-
Modos de escaneo y reglas de validación — Configuración de reglas del escáner y control de acceso en tornos.
-
Métodos de pago — Gestión de métodos de pago del espacio de trabajo.
-
Actualizar pases existentes — Mecánica de actualizaciones push en directo en APNs y Google Wallet.
