Vue d'ensemble
PassFlow (PassFlow API monté sur /api/v1/pass-flows, alias /api/v1/passflows) est le moteur hébergé en marque blanche d'auto-inscription et de paiement de Passinstance (PassFlowType : REGISTRATION, CHECKOUT, RECHARGE, CLAIM, UPDATE, REDEMPTION, CUSTOM ; PassFlowStatus : DRAFT, PUBLISHED, PAUSED, ARCHIVED). Les clients se rendent sur /f/:url, complètent des étapes configurables — champs de formulaire personnalisés, protection anti-bot (SpamProtectionMode : NONE, RECAPTCHA), vérification OTP par e-mail/SMS et paiement optionnel — puis installent immédiatement leur passe dans Apple Wallet ou Google Wallet.
Architecture système : pipeline PassFlow & passerelles de paiement
Étapes PassFlow & machine à états de soumission
Dans Passinstance Dashboard et PassFlow API (PassFlowStepType : INTRODUCTION, FORM, PASS_LOOKUP, AUTHENTICATION, PRODUCT_SELECTION, PAYMENT, REVIEW, PROCESSING, CONFIRMATION, PASS_DELIVERY, ERROR, CUSTOM) :
Étape publique (stepFlow.ts) | Nom de l'étape | Comportement d'exécution & règles de validation |
|---|---|---|
1. FormStep | Formulaire d'inscription client | Affiche les propriétés visibles du modèle avec validation obligatoire/regex et cases de consentement RGPD. Appelle GET /api/v1/pass-flows/public/:url/csrf-token avant de soumettre POST /api/v1/pass-flows/public/:url/generate (userData, recaptchaToken?). |
2. EmailStep | Coordonnées & déduplication | Recueille/confirme l'adresse e-mail ou le téléphone principal et applique les règles externalId / déduplication. |
3. OtpStep | Vérification par code à usage unique | (Optionnel) Envoie et vérifie un code OTP à durée limitée via POST /api/v1/pass-flows/public/:url/otp/send, /otp/resend et /otp/verify. |
4. PaymentStep | Paiement intégré | (Optionnel) Lit GET /api/v1/pass-flows/public/:url/payment-config et encaisse le règlement via Stripe, PayPal, Paystack, MTN Mobile Money ou Orange Money. |
5. PassStep | Remise immédiate dans le Wallet | Affiche les boutons Ajouter à Apple Wallet / Ajouter à Google Wallet, le QR code de relais et les écrans guidés PassTour. |
Important : Les soumissions suivent le statut
PassFlowSubmissionStatus(STARTED,SUBMITTED,AWAITING_PAYMENT,PAYMENT_PENDING,PROCESSING,COMPLETED,FAILED,REJECTED,EXPIRED,CANCELLED). Lorsque l'OTP ou le paiement est activé, l'activation du passe Wallet n'intervient qu'une fois la vérification réussie.
Passerelles de paiement intégrées pour les passes payants
PassFlow prend en charge cinq prestataires de paiement régionaux et internationaux avec endpoints publics d'initialisation et de webhook dédiés :
| Prestataire de paiement | Endpoint public d'initialisation | Moyens de paiement & zones pris en charge |
|---|---|---|
| Stripe | POST /api/v1/pass-flows/public/:url/payment-intent | Cartes bancaires, Apple Pay, Google Pay, SEPA, Klarna (Monde) |
| PayPal | POST /api/v1/pass-flows/public/:url/paypal-order | Portefeuille PayPal, Paiement en plusieurs fois, Venmo (Monde) |
| Paystack | POST /api/v1/pass-flows/public/:url/paystack/initialize | Cartes, virement bancaire, USSD, Mobile Money (Nigeria, Ghana, Kenya, Afrique du Sud) |
| MTN Mobile Money | POST /api/v1/pass-flows/public/:url/mtn-momo/request-to-pay | Validation push USSD sur portefeuille mobile (Afrique de l'Ouest et centrale) |
| Orange Money | POST /api/v1/pass-flows/public/:url/orange-money/initiate | Paiement web/mobile avec OTP Orange Money (Afrique francophone et Europe) |
Exemple : initialiser un Payment Intent Stripe dans 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"
}
}
Réponse HTTP (201 Created)
{
"success": true,
"data": {
"clientSecret": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d_secret_9f8e7d6c5b4a",
"paymentIntentId": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d"
},
"statusCode": 201
}
Exemple : initier une requête de paiement MTN MoMo
/api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
{
"phoneNumber": "+233241234567",
"amount": 150,
"currency": "GHS"
}
Gérer les PassFlows dans le tableau de bord & via l'API
Configurez vos PassFlows hébergés dans le tableau de bord sous Distribution -> Pass Flows (/pass-flows), ou pilotez-les par programmation via /api/v1/pass-flows :
-
GET /api/v1/pass-flows: liste tous les PassFlows configurés dans l'espace de travail actif. -
POST /api/v1/pass-flows: crée un nouveau PassFlow lié à untemplateIdpublié, en définissant son slug personnaliséurl, sonPassFlowType, ses réglages OTP et sa configuration de paiement. -
PATCH /api/v1/pass-flows/:id: modifie la visibilité des champs du formulaire, les exigences OTP ou la configuration des passerelles de paiement.
Pour en savoir plus sur les canaux de diffusion publics, consultez Distribution en libre-service et Liens de téléchargement & PassFlow.
