Überblick
PassFlow (PassFlow API unter /api/v1/pass-flows, Alias /api/v1/passflows) ist die gehostete, Whitelabel-fähige Self-Service-Registrierungs- und Checkout-Engine von Passinstance (PassFlowType: REGISTRATION, CHECKOUT, RECHARGE, CLAIM, UPDATE, REDEMPTION, CUSTOM; PassFlowStatus: DRAFT, PUBLISHED, PAUSED, ARCHIVED). Kundinnen und Kunden rufen /f/:url auf, durchlaufen konfigurierbare Eingabeschritte — darunter eigene Formularfelder, Bot-Schutz (SpamProtectionMode: NONE, RECAPTCHA), E-Mail-/SMS-OTP-Verifizierung sowie optional einen Bezahl-Checkout — und installieren ihren Apple-Wallet- oder Google-Wallet-Pass sofort.
Systemarchitektur: PassFlow-Pipeline & Zahlungs-Gateways
PassFlow-Schritte & Einreichungs-Zustandsautomat
In Passinstance Dashboard und dem PassFlow API (PassFlowStepType: INTRODUCTION, FORM, PASS_LOOKUP, AUTHENTICATION, PRODUCT_SELECTION, PAYMENT, REVIEW, PROCESSING, CONFIRMATION, PASS_DELIVERY, ERROR, CUSTOM):
Öffentlicher Schritt (stepFlow.ts) | Phasenname | Ausführungsverhalten & Validierungsregeln |
|---|---|---|
1. FormStep | Kunden-Registrierungsformular | Rendert sichtbare Vorlageneigenschaften mit Pflichtfeld-/Regex-Validierung und DSGVO-Einwilligungs-Checkboxen. Ruft vor POST /api/v1/pass-flows/public/:url/generate (userData, recaptchaToken?) den Endpunkt GET /api/v1/pass-flows/public/:url/csrf-token auf. |
2. EmailStep | Kontakt & Deduplizierung | Erfasst/bestätigt die primäre E-Mail-Adresse oder Telefonnummer und prüft externalId- / Deduplizierungseinstellungen. |
3. OtpStep | Einmalpasswort-Verifizierung | (Optional) Versendet und verifiziert ein zeitlich begrenztes OTP über POST /api/v1/pass-flows/public/:url/otp/send, /otp/resend und /otp/verify. |
4. PaymentStep | Integrierter Payment-Checkout | (Optional) Lädt GET /api/v1/pass-flows/public/:url/payment-config und zieht Zahlungen über Stripe, PayPal, Paystack, MTN Mobile Money oder Orange Money ein. |
5. PassStep | Sofortige Wallet-Auslieferung | Zeigt Schaltflächen für Zu Apple Wallet hinzufügen / Zu Google Wallet hinzufügen, QR-Übergabe sowie geführte PassTour-Overlays. |
Wichtig: Einreichungen verfolgen den Status
PassFlowSubmissionStatus(STARTED,SUBMITTED,AWAITING_PAYMENT,PAYMENT_PENDING,PROCESSING,COMPLETED,FAILED,REJECTED,EXPIRED,CANCELLED). Ist OTP oder eine Zahlung aktiviert, erfolgt die Aktivierung des Wallet-Passes erst nach erfolgreicher Verifizierung.
Eingebettete Zahlungs-Gateways für kostenpflichtige Pässe
PassFlow unterstützt fünf regionale und globale Zahlungsanbieter mit eigenen öffentlichen Initialisierungs- und Webhook-Endpunkten:
| Zahlungsanbieter | Öffentlicher Initialisierungs-Endpunkt | Unterstützte Zahlungsmethoden & Regionen |
|---|---|---|
| Stripe | POST /api/v1/pass-flows/public/:url/payment-intent | Kredit-/Debitkarten, Apple Pay, Google Pay, SEPA, Klarna (Global) |
| PayPal | POST /api/v1/pass-flows/public/:url/paypal-order | PayPal Wallet, Später bezahlen, Venmo (Global) |
| Paystack | POST /api/v1/pass-flows/public/:url/paystack/initialize | Karten, Banküberweisung, USSD, Mobile Money (Nigeria, Ghana, Kenia, Südafrika) |
| MTN Mobile Money | POST /api/v1/pass-flows/public/:url/mtn-momo/request-to-pay | Push-USSD-Freigabe über Mobile Wallet (West- & Zentralafrika) |
| Orange Money | POST /api/v1/pass-flows/public/:url/orange-money/initiate | Orange-Money-Web-/Mobile-OTP-Checkout (Frankophones Afrika & Europa) |
Beispiel: Stripe Payment Intent in PassFlow initialisieren
/api/v1/pass-flows/public/summer-vip-festival/payment-intent
{
"email": "claire.dubois@example.com",
"userData": {
"firstName": "Claire",
"lastName": "Dubois",
"ticketTier": "VIP All-Access"
}
}
HTTP-Antwort (201 Created)
{
"success": true,
"data": {
"clientSecret": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d_secret_9f8e7d6c5b4a",
"paymentIntentId": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d"
},
"statusCode": 201
}
Beispiel: MTN-MoMo-Zahlungsaufforderung (Request-to-Pay) starten
/api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
{
"phoneNumber": "+233241234567",
"amount": 150,
"currency": "GHS"
}
PassFlows im Dashboard & per API verwalten
Konfigurieren Sie gehostete PassFlows im Dashboard unter Verteilung -> PassFlows (/pass-flows) oder verwalten Sie sie programmatisch über /api/v1/pass-flows:
-
GET /api/v1/pass-flows: Listet alle konfigurierten PassFlows im aktiven Workspace auf. -
POST /api/v1/pass-flows: Erstellt einen neuen PassFlow für eine veröffentlichtetemplateIdinklusive eigenemurl-Slug,PassFlowType, OTP-Regeln und Zahlungskonfiguration. -
PATCH /api/v1/pass-flows/:id: Aktualisiert Sichtbarkeit von Formularfeldern, OTP-Anforderungen oder Zahlungs-Gateway-Einstellungen.
Erfahren Sie mehr über öffentliche Distributionskanäle in Self-Service-Verteilung und Download-Links & PassFlow.
