Visão geral
O PassFlow (PassFlow API montado em /api/v1/pass-flows, alias /api/v1/passflows) é o motor alojado whitelabel da Passinstance para inscrição self-service e checkout (PassFlowType: REGISTRATION, CHECKOUT, RECHARGE, CLAIM, UPDATE, REDEMPTION, CUSTOM; PassFlowStatus: DRAFT, PUBLISHED, PAUSED, ARCHIVED). Os clientes acedem a /f/:url, concluem etapas configuráveis de entrada — incluindo campos de formulário personalizados, proteção contra bots (SpamProtectionMode: NONE, RECAPTCHA), verificação OTP por e-mail/SMS e pagamento opcional — e instalam imediatamente o passe na Apple Wallet ou Google Wallet.
Arquitetura do sistema: Pipeline PassFlow e gateways de pagamento
Etapas PassFlow e máquina de estados de submissão
No Passinstance Dashboard e PassFlow API (PassFlowStepType: INTRODUCTION, FORM, PASS_LOOKUP, AUTHENTICATION, PRODUCT_SELECTION, PAYMENT, REVIEW, PROCESSING, CONFIRMATION, PASS_DELIVERY, ERROR, CUSTOM):
Etapa pública (stepFlow.ts) | Nome da fase | Comportamento de execução e regras de validação |
|---|---|---|
1. FormStep | Formulário de Registo do Cliente | Apresenta propriedades visíveis do modelo com validação obrigatória/regex e caixas de consentimento RGPD. Chama GET /api/v1/pass-flows/public/:url/csrf-token antes de submeter POST /api/v1/pass-flows/public/:url/generate (userData, recaptchaToken?). |
2. EmailStep | Contacto e Desduplicação | Recolhe/confirma o e-mail ou telefone principal e aplica definições de externalId / desduplicação. |
3. OtpStep | Verificação por Código Único | (Opcional) Envia e verifica um código OTP com prazo via POST /api/v1/pass-flows/public/:url/otp/send, /otp/resend e /otp/verify. |
4. PaymentStep | Checkout de Pagamento Integrado | (Opcional) Lê GET /api/v1/pass-flows/public/:url/payment-config e processa o pagamento via Stripe, PayPal, Paystack, MTN Mobile Money ou Orange Money. |
5. PassStep | Entrega Imediata na Carteira | Apresenta botões Adicionar à Apple Wallet / Adicionar à Google Wallet, entrega por QR e Sobreposições guiadas PassTour. |
Importante: As submissões acompanham
PassFlowSubmissionStatus(STARTED,SUBMITTED,AWAITING_PAYMENT,PAYMENT_PENDING,PROCESSING,COMPLETED,FAILED,REJECTED,EXPIRED,CANCELLED). Quando a verificação OTP ou o pagamento estão ativos, a ativação do passe na carteira ocorre apenas depois da verificação bem-sucedida.
Gateways de pagamento integrados para passes pagos
O PassFlow suporta cinco processadores de pagamento regionais e globais com endpoints públicos dedicados de inicialização e webhooks:
| Fornecedor de pagamento | Endpoint público de inicialização | Métodos de pagamento e regiões suportados |
|---|---|---|
| Stripe | POST /api/v1/pass-flows/public/:url/payment-intent | Cartões de crédito/débito, Apple Pay, Google Pay, SEPA, Klarna (Global) |
| PayPal | POST /api/v1/pass-flows/public/:url/paypal-order | Carteira PayPal, Pagar Depois, Venmo (Global) |
| Paystack | POST /api/v1/pass-flows/public/:url/paystack/initialize | Cartões, Transferência Bancária, USSD, Mobile Money (Nigéria, Gana, Quénia, África do Sul) |
| MTN Mobile Money | POST /api/v1/pass-flows/public/:url/mtn-momo/request-to-pay | Aprovação push em carteira móvel via USSD (África Ocidental e Central) |
| Orange Money | POST /api/v1/pass-flows/public/:url/orange-money/initiate | Checkout web/móvel Orange Money com OTP (África Francófona e Europa) |
Exemplo: Inicializar um Payment Intent Stripe no PassFlow
/api/v1/pass-flows/public/summer-vip-festival/payment-intent
{
"email": "claire.dubois@example.com",
"userData": {
"firstName": "Claire",
"lastName": "Dubois",
"ticketTier": "VIP All-Access"
}
}
Resposta HTTP (201 Created)
{
"success": true,
"data": {
"clientSecret": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d_secret_9f8e7d6c5b4a",
"paymentIntentId": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d"
},
"statusCode": 201
}
Exemplo: Iniciar um Request-to-Pay MTN MoMo
/api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
{
"phoneNumber": "+233241234567",
"amount": 150,
"currency": "GHS"
}
Gerir PassFlows no Painel e na API
Configure PassFlows alojados no Painel em Distribuição -> Pass Flows (/pass-flows), ou gira-os programaticamente através de /api/v1/pass-flows:
-
GET /api/v1/pass-flows: Lista todos os PassFlows configurados no espaço de trabalho ativo. -
POST /api/v1/pass-flows: Cria um novo PassFlow associado a umtemplateIdpublicado, definindo slugurlpersonalizado,PassFlowType, definições OTP e configuração de pagamento. -
PATCH /api/v1/pass-flows/:id: Atualiza a visibilidade dos campos do formulário, requisitos de OTP ou configuração de gateway de pagamento.
Saiba mais sobre canais públicos de distribuição em Distribuição em autoatendimento e Links de download e PassFlow.
