Skip to content
Guía del Centro de ayuda · Distribución de pases
5 min de lecturaVerificado 2026-11-16

Vender suscripciones

Venda membresías digitales recurrentes, sincronizando Stripe Billing o PayPal Subscriptions con las fechas de caducidad y cambios de estado de los pases.

En esta guía

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:

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
SINCRONIZACIÓN DE CICLO DE VIDA DE SUSCRIPCIONES
ETAPA 01 MOTOR DE FACTURACIÓN POR SUSCRIPCIÓN DEL CLIENTE
Stripe Billing | PayPal Subscriptions | Motor recurrente propio
ETAPA 02 RECEPTOR DE WEBHOOKS DE PASSINSTANCE (/webhooks/billing)
Empareja el ID de suscripción o correo del cliente con Pass.externalId
ETAPA 03 (Renovación exitosa) | (Pago fallido) | (Cancelada)
1
EXTENDER CADUCIDAD
Actualiza expirationDate al nuevo fin de periodo
Push APNs silencioso
Actualización Google
2
ALERTA DE GRACIA
Actualiza campo:
"Pago vencido"
Push en pantalla de bloqueo
Permite periodo de gracia en escáner
3
CADUCAR O ANULAR
Estado: EXPIRED o voided: true
Código de barras tachado
El escáner rechaza el acceso

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. 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. 2
    Vinculación a externalId: Passinstance almacena este identificador en Pass.externalId.
  3. 3
    Configuración de la caducidad inicial: El campo expirationDate inicial del pase se fija en la marca temporal Unix de current_period_end proporcionada 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 externalId y extiende pass.expirationDate hasta 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 EXPIRED o establece pass.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 EXPIRED o VOIDED.

Configuración paso a paso: conectar Stripe Billing con Passinstance

Paso 1: conecte Stripe en la configuración del espacio de trabajo

  1. 1
    Vaya a Configuración -> Integraciones -> Pagos en el panel de control de Passinstance.
  2. 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:

TEXT
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. 1
    Abra Funcionalidades -> Caducidad y validez.
  2. 2
    Seleccione Caducidad dinámica por suscripción.
  3. 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ónPantalla del escánerRespuesta del escánerResultado
Activa y pagadaPantalla verdeVALIDAcceso permitido al socio. Muestra el nombre del cliente y su nivel activo.
Pago vencido (periodo de gracia)Pantalla ámbarWARNINGAlerta al personal: "Periodo de gracia activo. Solicite al socio que actualice su tarjeta."
Cancelada / caducadaPantalla rojaEXPIREDEl torno permanece bloqueado. Muestra "Membresía caducada el [Fecha]".
Revocada / anuladaPantalla rojaVOIDEDAcceso bloqueado. Muestra "La tarjeta ha sido anulada por el emisor".

Documentación relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.