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
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 fase | Comportamento di esecuzione e regole di validazione |
|---|---|---|
1. FormStep | Modulo di registrazione cliente | Mostra 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. EmailStep | Contatto e deduplicazione | Acquisisce/conferma e-mail o numero di telefono principale e applica le impostazioni externalId / deduplicazione. |
3. OtpStep | Verifica 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. PaymentStep | Checkout 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. PassStep | Consegna istantanea al Wallet | Visualizza 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 pagamento | Endpoint pubblico di inizializzazione | Metodi di pagamento e aree geografiche supportate |
|---|---|---|
| Stripe | POST /api/v1/pass-flows/public/:url/payment-intent | Carte di credito/debito, Apple Pay, Google Pay, SEPA, Klarna (Globale) |
| PayPal | POST /api/v1/pass-flows/public/:url/paypal-order | PayPal Wallet, Pay Later, Venmo (Globale) |
| Paystack | POST /api/v1/pass-flows/public/:url/paystack/initialize | Carte, bonifico bancario, USSD, Mobile Money (Nigeria, Ghana, Kenya, Sudafrica) |
| MTN Mobile Money | POST /api/v1/pass-flows/public/:url/mtn-momo/request-to-pay | Approvazione mobile wallet push USSD (Africa occidentale e centrale) |
| Orange Money | POST /api/v1/pass-flows/public/:url/orange-money/initiate | Checkout OTP web/mobile Orange Money (Africa francofona ed Europa) |
Esempio: inizializzare un Payment Intent Stripe in 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"
}
}
Risposta HTTP (201 Created)
{
"success": true,
"data": {
"clientSecret": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d_secret_9f8e7d6c5b4a",
"paymentIntentId": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d"
},
"statusCode": 201
}
Esempio: avviare una richiesta Request-to-Pay MTN MoMo
/api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
{
"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 untemplateIdpubblicato, definendo lo slugurlpersonalizzato,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.
