Skip to content
Guia da Central de Ajuda · Emissão de passes
3 min de leituraVerificado 2026-11-16

Formulários de registo e PassFlow

Configure etapas de admissão PassFlow (campos, captura de e-mail, verificação OTP opcional) para auto-registo.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
MOTOR DE INSCRIÇÃO PASSFLOW, OTP E PAGAMENTO
ETAPA 01 CLIENTE PÚBLICO PASSFLOW (/f/:url)
1
FormStep
Props Pers. e Validação
2
EmailStep
Identidade e
Consent. RGPD
3
OtpStep
Código SMS/
E-mail 6 Díg.
4
PaymentStep (Checkout Opcional de Passe Pago)
5
PassStep
Apple .pkpass e
Google Save JWT
ETAPA 02 ORQUESTRADOR BACKEND PASSFLOW E GATEWAYS DE PAGAMENTO
Gerar Passe: POST/api/v1/pass-flows/public/:url/generate
OTP: POST.../otp/send, POST.../otp/resend, POST.../otp/verify
Stripe: POST/api/v1/pass-flows/public/:url/payment-intent
PayPal: POST/api/v1/pass-flows/public/:url/paypal-order
Paystack: POST/api/v1/pass-flows/public/:url/paystack/initialize
MTN MoMo: POST/api/v1/pass-flows/public/:url/mtn-momo/request-to-pay
Orange Money: POST/api/v1/pass-flows/public/:url/orange-money/initiate

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 faseComportamento de execução e regras de validação
1. FormStepFormulário de Registo do ClienteApresenta 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. EmailStepContacto e DesduplicaçãoRecolhe/confirma o e-mail ou telefone principal e aplica definições de externalId / desduplicação.
3. OtpStepVerificaçã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. PaymentStepCheckout 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. PassStepEntrega Imediata na CarteiraApresenta 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 pagamentoEndpoint público de inicializaçãoMétodos de pagamento e regiões suportados
StripePOST /api/v1/pass-flows/public/:url/payment-intentCartões de crédito/débito, Apple Pay, Google Pay, SEPA, Klarna (Global)
PayPalPOST /api/v1/pass-flows/public/:url/paypal-orderCarteira PayPal, Pagar Depois, Venmo (Global)
PaystackPOST /api/v1/pass-flows/public/:url/paystack/initializeCartões, Transferência Bancária, USSD, Mobile Money (Nigéria, Gana, Quénia, África do Sul)
MTN Mobile MoneyPOST /api/v1/pass-flows/public/:url/mtn-momo/request-to-payAprovação push em carteira móvel via USSD (África Ocidental e Central)
Orange MoneyPOST /api/v1/pass-flows/public/:url/orange-money/initiateCheckout web/móvel Orange Money com OTP (África Francófona e Europa)

Exemplo: Inicializar um Payment Intent Stripe no PassFlow

POST /api/v1/pass-flows/public/summer-vip-festival/payment-intent
Cabeçalhos
Content-Type application/json
JSON
{
  "email": "claire.dubois@example.com",
  "userData": {
    "firstName": "Claire",
    "lastName": "Dubois",
    "ticketTier": "VIP All-Access"
  }
}

Resposta HTTP (201 Created)

JSON
{
  "success": true,
  "data": {
    "clientSecret": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d_secret_9f8e7d6c5b4a",
    "paymentIntentId": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d"
  },
  "statusCode": 201
}

Exemplo: Iniciar um Request-to-Pay MTN MoMo

POST /api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
Cabeçalhos
Content-Type application/json
JSON
{
  "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 um templateId publicado, definindo slug url personalizado, 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.

Documentação de produto e API 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.