Skip to content
Guia da Central de Ajuda · Distribuição de passes
5 min de leituraVerificado 2026-11-16

Vender assinaturas

Venda assinaturas digitais recorrentes, sincronizando Stripe Billing ou PayPal Subscriptions com datas de expiração e alterações de status dos passes.

Neste guia

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:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
SINCRONIZAÇÃO DE CICLO DE VIDA DE SUBSCRIÇÕES
ETAPA 01 MOTOR DE FATURAÇÃO DE SUBSCRIÇÕES DO CLIENTE
Stripe Billing | PayPal Subscriptions | Motor Recorrente Próprio
ETAPA 02 RECETOR DE WEBHOOKS PASSINSTANCE (/webhooks/billing)
Associa o ID de subscrição ou o e-mail recebido ao campo Pass.externalId
ETAPA 03 (Renovação com Sucesso) | (Falha de Pagamento) | (Cancelada)
1
PROLONGAR VALIDADE
Atualiza expiration para novo fim ciclo
Push APNs silencioso
Atualização Google
2
ALERTA DE CARÊNCIA
Atualiza campo:
"Pagamento em Atraso"
Alerta ecrã bloqueado
Permite tolerância
3
EXPIRAR OU ANULAR
Estado: EXPIRED ou voided: true
Cód. barras riscado
Scanner rejeita

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. 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. 2
    Vinculação a externalId: A Passinstance armazena este ID em Pass.externalId.
  3. 3
    Definição da Expiração Inicial: A expirationDate inicial do passe é definida para o carimbo temporal Unix de current_period_end proveniente 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 externalId e prolonga pass.expirationDate para 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 EXPIRED ou define pass.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 EXPIRED ou VOIDED.

Configuração passo a passo: Ligar o Stripe Billing à Passinstance

Passo 1: Ligar a Stripe nas Definições do Espaço de Trabalho

  1. 1
    Aceda a Definições -> Integrações -> Pagamentos no Painel da Passinstance.
  2. 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:

TEXT
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. 1
    Abra Funcionalidades -> Expiração e Validade.
  2. 2
    Selecione Expiração Dinâmica de Subscrição.
  3. 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çãoEcrã do scannerResposta do scannerResultado
Ativa e PagaEcrã VerdeVALIDMembro admitido. Apresenta o nome do cliente e o nível ativo.
Pagamento em Atraso (Período de Carência)Ecrã ÂmbarWARNINGEquipa alertada: "Período de carência ativo. Solicite ao membro que atualize o cartão."
Cancelada / ExpiradaEcrã VermelhoEXPIREDO torniquete permanece bloqueado. Apresenta "Adesão expirada em [Data]".
Revogada / AnuladaEcrã VermelhoVOIDEDCheck-in bloqueado. Apresenta "O cartão foi anulado pelo emissor".

Documentação relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.