Skip to content
Help Center Guide · Pass Issuance
4 min readVerified 2026-11-16

Registration Forms & PassFlow

Configure PassFlow intake steps (form fields, email collection, optional OTP verification) for automated pass onboarding.

In This Guide

Overview

PassFlow (PassFlow API mounted at /api/v1/pass-flows, alias /api/v1/passflows) is Passinstance's hosted, white-label self-service enrollment and checkout engine (PassFlowType: REGISTRATION, CHECKOUT, RECHARGE, CLAIM, UPDATE, REDEMPTION, CUSTOM; PassFlowStatus: DRAFT, PUBLISHED, PAUSED, ARCHIVED). Customers visit /f/:url, complete configurable intake steps—including custom form fields, bot protection (SpamProtectionMode: NONE, RECAPTCHA), email/SMS OTP verification, and optional payment checkout—and install their Apple Wallet or Google Wallet pass immediately.

System Architecture: PassFlow Pipeline & Payment Gateways

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PASSFLOW ENROLLMENT, OTP & PAYMENT ENGINE
STAGE 01 PUBLIC PASSFLOW CLIENT (/f/:url)
1
FormStep
Custom Props
& Validation
2
EmailStep
Identity &
GDPR Consent
3
OtpStep
6-Digit SMS/
Email Code
4
PaymentStep (Optional Paid
Pass Checkout)
5
PassStep
Apple .pkpass &
Google Save JWT
STAGE 02 PASSFLOW BACKEND & PAYMENT GATEWAY ORCHESTRATOR
Generate Pass: POST/api/v1/pass-flows/public/:url/generate
OTP Send/Verify: 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

PassFlow Steps & Submission State Machine

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

Public Step (stepFlow.ts)Stage NameExecution Behavior & Validation Rules
1. FormStepCustomer Registration FormRenders visible template properties with required/regex validation and GDPR consent checkboxes. Calls GET /api/v1/pass-flows/public/:url/csrf-token before submitting POST /api/v1/pass-flows/public/:url/generate (userData, recaptchaToken?).
2. EmailStepContact & DeduplicationCaptures/confirms primary email or phone and enforces externalId / deduplication settings.
3. OtpStepOne-Time Passcode Verification(Optional) Dispatches/verifies a time-bound OTP via POST /api/v1/pass-flows/public/:url/otp/send, /otp/resend, and /otp/verify.
4. PaymentStepEmbedded Payment Checkout(Optional) Reads GET /api/v1/pass-flows/public/:url/payment-config and collects payment via Stripe, PayPal, Paystack, MTN Mobile Money, or Orange Money.
5. PassStepInstant Wallet DeliveryRenders Add to Apple Wallet / Add to Google Wallet buttons, QR handoff, and PassTour Guided Overlays.

Important: Submissions track PassFlowSubmissionStatus (STARTED, SUBMITTED, AWAITING_PAYMENT, PAYMENT_PENDING, PROCESSING, COMPLETED, FAILED, REJECTED, EXPIRED, CANCELLED). When OTP or payment is enabled, wallet pass activation occurs only once verification succeeds.


Embedded Payment Gateways for Paid Passes

PassFlow supports five regional and global payment processors with dedicated public initialization and webhook endpoints:

Payment ProviderPublic Initialization EndpointSupported Payment Methods & Regions
StripePOST /api/v1/pass-flows/public/:url/payment-intentCredit/debit cards, Apple Pay, Google Pay, SEPA, Klarna (Global)
PayPalPOST /api/v1/pass-flows/public/:url/paypal-orderPayPal Wallet, Pay Later, Venmo (Global)
PaystackPOST /api/v1/pass-flows/public/:url/paystack/initializeCards, Bank Transfer, USSD, Mobile Money (Nigeria, Ghana, Kenya, South Africa)
MTN Mobile MoneyPOST /api/v1/pass-flows/public/:url/mtn-momo/request-to-payPush USSD mobile wallet approval (West & Central Africa)
Orange MoneyPOST /api/v1/pass-flows/public/:url/orange-money/initiateOrange Money web/mobile OTP checkout (Francophone Africa & Europe)

Troubleshooting: "My form is inactive even though I turned it on"

A common issue encountered when launching a public registration page is seeing an "Inactive", "Registration Closed", or "Not Open Yet" screen despite having toggled the form switch to active.

The public runtime (LivePassFlow.tsx lines 200–285) evaluates five distinct operational boundaries before accepting customer registrations:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SYSTEM ARCHITECTURE FLOW
STAGE 01 PASSFLOW AVAILABILITY EVALUATION IN LIVEPASSFLOW
1
Status & Active Flag? ---- [ active === true && status === 'PUBLISHED' ]
NoRenders: "Form Inactive (Draft Mode)" v Yes
2
Start Date Window? ------- [ now() >= activeFrom ]
NoRenders: "Registration Not Open Yet (Scheduled)" v Yes
3
End Date Window? --------- [ now() <= activeUntil ]
NoRenders: "Registration Closed (Ended)" v Yes
4
Capacity Cap? ------------ [ totalIssuedPasses < maxPasses ]
NoRenders: "Sold Out (Capacity Limit Reached)" v Yes
5
Workspace & Template Ready? [ Template PUBLISHED & Workspace Quota OK ]
NoRenders: "Registration Unavailable" v Yes =FORM ACTIVE: Renders FormStep input fields

The 5 Root Causes & Step-by-Step Fixes

1. Form Is Still in Draft Status (status: 'DRAFT')

  • Root Cause: In the PassFlow editor, flipping the "Accept submissions" toggle to active merely updates the working draft in memory. The public URL will not accept submissions until the form is officially published.
  • Resolution: Click the Publish Form button in the top right corner of the PassFlow builder (usePublishPassFlowMutation), which sets { active: true, status: 'PUBLISHED' }.

2. Scheduled Time Window Boundaries (activeFrom / activeUntil)

  • Root Cause:

- If activeFrom is set to a future date/time, LivePassFlow computes availabilityStatus: 'SCHEDULED' and displays "Registration Not Open Yet". - If activeUntil has passed, LivePassFlow computes availabilityStatus: 'ENDED' and displays "Registration Closed".

  • Resolution: Open PassFlow Settings -> Schedule & Availability. Clear the start/end dates or expand the window to include the current date and time.

3. Underlying Template Is Unready or in Draft

  • Root Cause: PassFlow cannot issue signed passes if the bound template is still in status: 'DRAFT' or has no active Apple Pass Type Certificate assigned.
  • Resolution: Navigate to Templates, open the associated template, and ensure it is published with a valid Apple certificate.

4. Submission Capacity Cap Reached (maxPasses)

  • Root Cause: If the form configured a maxPasses cap (for example, limiting registration to 500 attendees) and the count has been reached, LivePassFlow returns availabilityStatus: 'SOLD_OUT'.
  • Resolution: Increase or clear the Max Passes cap under PassFlow Settings.

5. Workspace Active Pass Quota Reached

  • Root Cause: Your workspace subscription plan enforces a monthly active pass quota. If your account reaches 100% of its quota limit, public enrollment endpoints reject new pass creation.
  • Resolution: Check Company Settings -> Usage & Billing to upgrade your plan tier or archive inactive passes.

Managing PassFlows in the Dashboard & API

Configure hosted PassFlows in the Dashboard under Distribution -> Pass Flows (/pass-flows), or manage them programmatically via /api/v1/pass-flows:

  • GET /api/v1/pass-flows: List all configured PassFlows in the active workspace.
  • POST /api/v1/pass-flows: Create a new PassFlow bound to a published templateId, defining custom url slug, PassFlowType, OTP settings, and payment configuration.
  • PATCH /api/v1/pass-flows/:id: Update form field visibility, schedule windows, OTP requirements, or payment gateway configuration.

Learn more about public distribution channels in Self-Service Distribution and Download Links & PassFlow.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.