Skip to content
Guida del Centro assistenza · Emissione pass
3 min di letturaVerificato 2026-11-16

Moduli di registrazione e PassFlow

Imposta gli step PassFlow (campi modulo, raccolta email, verifica OTP opzionale) per l'iscrizione automatica.

In questa guida

Panoramica

PassFlow (PassFlow API su /api/v1/pass-flows, alias /api/v1/passflows) è il motore ospitato white-label di iscrizione self-service e checkout di Passinstance (PassFlowType: REGISTRATION, CHECKOUT, RECHARGE, CLAIM, UPDATE, REDEMPTION, CUSTOM; PassFlowStatus: DRAFT, PUBLISHED, PAUSED, ARCHIVED). I clienti visitano /f/:url, completano i passaggi configurabili — tra cui campi personalizzati del modulo, protezione anti-bot (SpamProtectionMode: NONE, RECAPTCHA), verifica OTP via e-mail/SMS ed eventuale checkout con pagamento — e installano subito il proprio pass in Apple Wallet o Google Wallet.

Architettura di sistema: pipeline PassFlow e gateway di pagamento

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ISCRIZIONE PASSFLOW, OTP E MOTORE PAGAMENTI
FASE 01 CLIENT PUBBLICO PASSFLOW (/f/:url)
1
FormStep
Proprietà e validazione
2
EmailStep
Identità e consenso GDPR
3
OtpStep
Codice OTP 6 cifre SMS/ml
4
PaymentStep (Checkout opzionale pass a pagamento)
5
PassStep
Apple .pkpass e
Google Save JWT
FASE 02 BACKEND PASSFLOW E ORCHESTRATORE GATEWAY DI PAGAMENTO
Genera pass: POST/api/v1/pass-flows/public/:url/generate
Invio/Verifica 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

Passaggi PassFlow e macchina a stati degli invii

In Passinstance Dashboard e PassFlow API (PassFlowStepType: INTRODUCTION, FORM, PASS_LOOKUP, AUTHENTICATION, PRODUCT_SELECTION, PAYMENT, REVIEW, PROCESSING, CONFIRMATION, PASS_DELIVERY, ERROR, CUSTOM):

Passaggio pubblico (stepFlow.ts)Nome faseComportamento di esecuzione e regole di validazione
1. FormStepModulo di registrazione clienteMostra le proprietà visibili del modello con validazione obbligatorietà/regex e caselle di consenso GDPR. Richiama GET /api/v1/pass-flows/public/:url/csrf-token prima di inviare POST /api/v1/pass-flows/public/:url/generate (userData, recaptchaToken?).
2. EmailStepContatto e deduplicazioneAcquisisce/conferma e-mail o numero di telefono principale e applica le impostazioni externalId / deduplicazione.
3. OtpStepVerifica codice monouso OTP(Opzionale) Invia/verifica un OTP a scadenza temporale tramite POST /api/v1/pass-flows/public/:url/otp/send, /otp/resend e /otp/verify.
4. PaymentStepCheckout pagamento integrato(Opzionale) Legge GET /api/v1/pass-flows/public/:url/payment-config e riscuote il pagamento tramite Stripe, PayPal, Paystack, MTN Mobile Money oppure Orange Money.
5. PassStepConsegna istantanea al WalletVisualizza i pulsanti Aggiungi ad Apple Wallet / Aggiungi a Google Wallet, handover tramite codice QR e Overlay guidati PassTour.

Importante: Gli invii tracciano PassFlowSubmissionStatus (STARTED, SUBMITTED, AWAITING_PAYMENT, PAYMENT_PENDING, PROCESSING, COMPLETED, FAILED, REJECTED, EXPIRED, CANCELLED). Quando OTP o pagamento sono abilitati, l'attivazione del pass Wallet avviene solo al buon esito della verifica.

Gateway di pagamento integrati per pass a pagamento

PassFlow supporta cinque processori di pagamento regionali e globali con endpoint pubblici dedicati di inizializzazione e webhook:

Provider pagamentoEndpoint pubblico di inizializzazioneMetodi di pagamento e aree geografiche supportate
StripePOST /api/v1/pass-flows/public/:url/payment-intentCarte di credito/debito, Apple Pay, Google Pay, SEPA, Klarna (Globale)
PayPalPOST /api/v1/pass-flows/public/:url/paypal-orderPayPal Wallet, Pay Later, Venmo (Globale)
PaystackPOST /api/v1/pass-flows/public/:url/paystack/initializeCarte, bonifico bancario, USSD, Mobile Money (Nigeria, Ghana, Kenya, Sudafrica)
MTN Mobile MoneyPOST /api/v1/pass-flows/public/:url/mtn-momo/request-to-payApprovazione mobile wallet push USSD (Africa occidentale e centrale)
Orange MoneyPOST /api/v1/pass-flows/public/:url/orange-money/initiateCheckout OTP web/mobile Orange Money (Africa francofona ed Europa)

Esempio: inizializzare un Payment Intent Stripe in PassFlow

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

Risposta HTTP (201 Created)

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

Esempio: avviare una richiesta Request-to-Pay MTN MoMo

POST /api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
Header
Content-Type application/json
JSON
{
  "phoneNumber": "+233241234567",
  "amount": 150,
  "currency": "GHS"
}

Gestione dei PassFlow nella Dashboard e via API

Configuri i PassFlow ospitati nella Dashboard sotto Distribuzione -> Pass Flow (/pass-flows), oppure li gestisca in modo programmatico tramite /api/v1/pass-flows:

  • GET /api/v1/pass-flows: Elenca tutti i PassFlow configurati nel workspace attivo.
  • POST /api/v1/pass-flows: Crea un nuovo PassFlow associato a un templateId pubblicato, definendo lo slug url personalizzato, PassFlowType, impostazioni OTP e configurazione di pagamento.
  • PATCH /api/v1/pass-flows/:id: Aggiorna visibilità dei campi del modulo, requisiti OTP o configurazione del gateway di pagamento.

Approfondisca i canali di distribuzione pubblici in Distribuzione self-service e Link di download e PassFlow.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.