Arquitetura de adesões recorrentes e subscrições
Para ginásios, espaços de coworking, redes de transportes, caixas de subscrição e associações profissionais, os passes de carteiras digitais funcionam como credenciais de adesão dinâmicas em tempo real. Ao contrário dos cartões estáticos, um passe de subscrição na Apple Wallet e na Google Wallet pode atualizar automaticamente a sua data de expiração, o estado de adesão e a validade do código de barras conforme os ciclos de faturação recorrente são concluídos com sucesso, falham ou são cancelados.
A Passinstance sincroniza acordos de faturação de subscrições (a partir do Stripe Billing, PayPal Subscriptions ou backends de subscrição personalizados) com o ciclo de vida do passe através de gestores automáticos de webhooks e notificações push silenciosas:
Associar subscrições de pagamento a registos de passes
Para garantir uma sincronização recorrente sem falhas do ciclo de vida, cada passe tem de estar vinculado ao registo de subscrição do cliente através do campo externalId:
-
1
Quando o Cliente Subscreve: Quando é criada uma subscrição inicial na Stripe ou no PayPal, o seu backend ou a integração de checkout da Passinstance capta o ID de subscrição (por exemplo,
sub_1Q8xYz2e...) ou o ID de cliente (por exemplo,cus_987654...). -
2
Vinculação a
externalId: A Passinstance armazena este ID emPass.externalId. -
3
Definição da Expiração Inicial: A
expirationDateinicial do passe é definida para o carimbo temporal Unix decurrent_period_endproveniente do fornecedor de faturação.
Eventos de ciclo de vida de webhooks e ações automatizadas
A Passinstance escuta os webhooks de faturação recorrente e aciona as correspondentes atualizações de estado do passe:
1. Subscrição renovada (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
Quando um pagamento de subscrição mensal ou anual é bem-sucedido:
-
Ação: A Passinstance localiza o passe correspondente a
externalIde prolongapass.expirationDatepara a data de fim do novo ciclo de faturação. -
Atualização de Campos: Qualquer campo dinâmico que apresente
{validUntil}ou{membershipExpiry}atualiza-se para a nova data. -
Notificação Push: A Apple Wallet recebe uma atualização APNs silenciosa; a Google Wallet atualiza o objeto via REST. O ecrã bloqueado pode apresentar uma faixa discreta de atualização (por exemplo, "Adesão renovada até 31 de março").
2. Falha de pagamento / Em atraso (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
Se uma cobrança recorrente falhar devido a um cartão de crédito expirado ou saldo insuficiente:
-
Ação: O passe mantém-se ativo durante o período de carência configurado (por exemplo, 7 dias).
-
Atualização de Campos: Um campo auxiliar ou secundário muda de
"ACTIVE"para"PAYMENT PAST DUE". -
Notificação de Alerta: É enviada uma notificação push para o dispositivo do cliente: "Atualize o seu método de pagamento para manter a sua adesão ativa."
3. Subscrição cancelada ou terminada (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
Quando um cliente termina a sua subscrição:
-
Ação: No final do período faturado já pago, a Passinstance atualiza o estado do passe para
EXPIREDou definepass.voided = true. -
Desativação Visual: A Apple Wallet risca o código de barras de check-in e apresenta o selo "Passe Anulado". A Google Wallet marca o cartão como expirado.
-
Rejeição no Scanner: A validação física em torniquetes de ginásio ou receções através do Passinstance Scanner apresenta imediatamente um ecrã vermelho com
EXPIREDouVOIDED.
Configuração passo a passo: Ligar o Stripe Billing à Passinstance
Passo 1: Ligar a Stripe nas Definições do Espaço de Trabalho
-
1
Aceda a Definições -> Integrações -> Pagamentos no Painel da Passinstance.
-
2
Ligue a sua conta Stripe.
Passo 2: Registar o endpoint de webhook da Stripe
No seu Stripe Dashboard -> Developers -> Webhooks, adicione um endpoint direcionado à Passinstance:
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Selecione os seguintes eventos:
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Passo 3: Configurar as regras de expiração do passe de subscrição
Nas definições do seu Modelo de Passe:
-
1
Abra Funcionalidades -> Expiração e Validade.
-
2
Selecione Expiração Dinâmica de Subscrição.
-
3
Escolha o comportamento pós-cancelamento: Expirar Passe (mantém-se no histórico da carteira) ou Anular Passe (risca o código de barras imediatamente).
Gerir o estado da subscrição com o Passinstance Scanner
Quando o pessoal do ginásio ou os anfitriões do recinto leem o passe de um membro utilizando a Aplicação Passinstance Scanner (Passinstance Scanner):
| Estado da subscrição | Ecrã do scanner | Resposta do scanner | Resultado |
|---|---|---|---|
| Ativa e Paga | Ecrã Verde | VALID | Membro admitido. Apresenta o nome do cliente e o nível ativo. |
| Pagamento em Atraso (Período de Carência) | Ecrã Âmbar | WARNING | Equipa alertada: "Período de carência ativo. Solicite ao membro que atualize o cartão." |
| Cancelada / Expirada | Ecrã Vermelho | EXPIRED | O torniquete permanece bloqueado. Apresenta "Adesão expirada em [Data]". |
| Revogada / Anulada | Ecrã Vermelho | VOIDED | Check-in bloqueado. Apresenta "O cartão foi anulado pelo emissor". |
Documentação relacionada
-
Vender passes — Vendas pontuais de passes pagos através do PassFlow.
-
Modos de leitura e regras de validação — Configurar regras de scanner e controlo de acesso em torniquetes.
-
Métodos de pagamento — Gerir métodos de pagamento do espaço de trabalho.
-
Atualizar passes existentes — Mecânica de notificações push em direto via APNs e Google Wallet.
