Descripción general
PassFlow (PassFlow API montado en /api/v1/pass-flows, alias /api/v1/passflows) es el motor de registro y pago autoservicio de marca blanca alojado por Passinstance (PassFlowType: REGISTRATION, CHECKOUT, RECHARGE, CLAIM, UPDATE, REDEMPTION, CUSTOM; PassFlowStatus: DRAFT, PUBLISHED, PAUSED, ARCHIVED). Los clientes visitan /f/:url, completan pasos configurables de captura —incluidos campos de formulario personalizados, protección anti-bots (SpamProtectionMode: NONE, RECAPTCHA), verificación OTP por correo/SMS y pasarela de pago opcional— e instalan de inmediato su pase en Apple Wallet o Google Wallet.
Arquitectura del sistema: flujo PassFlow y pasarelas de pago
Pasos de PassFlow y máquina de estados de envíos
En Passinstance Dashboard y PassFlow API (PassFlowStepType: INTRODUCTION, FORM, PASS_LOOKUP, AUTHENTICATION, PRODUCT_SELECTION, PAYMENT, REVIEW, PROCESSING, CONFIRMATION, PASS_DELIVERY, ERROR, CUSTOM):
Paso público (stepFlow.ts) | Nombre de etapa | Comportamiento de ejecución y reglas de validación |
|---|---|---|
1. FormStep | Formulario de registro de cliente | Muestra las propiedades visibles de la plantilla con validación de obligatoriedad/regex y casillas de consentimiento RGPD. Llama a GET /api/v1/pass-flows/public/:url/csrf-token antes de enviar POST /api/v1/pass-flows/public/:url/generate (userData, recaptchaToken?). |
2. EmailStep | Contacto y deduplicación | Captura o confirma el correo electrónico o teléfono principal y aplica los ajustes de externalId / deduplicación. |
3. OtpStep | Verificación mediante código de un solo uso | (Opcional) Envía y verifica un OTP con validez temporal mediante POST /api/v1/pass-flows/public/:url/otp/send, /otp/resend y /otp/verify. |
4. PaymentStep | Pasarela de pago integrada | (Opcional) Lee GET /api/v1/pass-flows/public/:url/payment-config y cobra mediante Stripe, PayPal, Paystack, MTN Mobile Money u Orange Money. |
5. PassStep | Entrega instantánea al monedero | Muestra los botones Añadir a Apple Wallet / Añadir a Google Wallet, entrega mediante código QR y superposiciones guiadas PassTour. |
Importante: Los envíos registran
PassFlowSubmissionStatus(STARTED,SUBMITTED,AWAITING_PAYMENT,PAYMENT_PENDING,PROCESSING,COMPLETED,FAILED,REJECTED,EXPIRED,CANCELLED). Cuando la verificación OTP o el pago están activados, la activación del pase en el monedero se produce únicamente tras confirmarse correctamente la verificación.
Pasarelas de pago integradas para pases de pago
PassFlow admite cinco procesadores de pago regionales y globales con endpoints públicos dedicados de inicialización y webhooks:
| Proveedor de pagos | Endpoint público de inicialización | Métodos de pago y regiones admitidos |
|---|---|---|
| Stripe | POST /api/v1/pass-flows/public/:url/payment-intent | Tarjetas de crédito/débito, Apple Pay, Google Pay, SEPA, Klarna (Global) |
| PayPal | POST /api/v1/pass-flows/public/:url/paypal-order | PayPal Wallet, Pay Later, Venmo (Global) |
| Paystack | POST /api/v1/pass-flows/public/:url/paystack/initialize | Tarjetas, transferencia bancaria, USSD, Mobile Money (Nigeria, Ghana, Kenia, Sudáfrica) |
| MTN Mobile Money | POST /api/v1/pass-flows/public/:url/mtn-momo/request-to-pay | Aprobación push USSD en monedero móvil (África Occidental y Central) |
| Orange Money | POST /api/v1/pass-flows/public/:url/orange-money/initiate | Pago web/móvil OTP con Orange Money (África francófona y Europa) |
Ejemplo: inicializar un Payment Intent de Stripe en 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"
}
}
Respuesta HTTP (201 Created)
{
"success": true,
"data": {
"clientSecret": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d_secret_9f8e7d6c5b4a",
"paymentIntentId": "pi_3Q9xYz2eZvKYlo2C1a2b3c4d"
},
"statusCode": 201
}
Ejemplo: iniciar un Request-to-Pay con MTN MoMo
/api/v1/pass-flows/public/accra-vip-lounge/mtn-momo/request-to-pay
{
"phoneNumber": "+233241234567",
"amount": 150,
"currency": "GHS"
}
Gestión de PassFlows en el panel y la API
Configure PassFlows alojados en el panel bajo Distribución -> Pass Flows (/pass-flows) o gestiónelos de forma programática mediante /api/v1/pass-flows:
-
GET /api/v1/pass-flows: Lista todos los PassFlows configurados en el espacio de trabajo activo. -
POST /api/v1/pass-flows: Crea un nuevo PassFlow vinculado a unatemplateIdpublicada, definiendo el slugurl,PassFlowType, ajustes OTP y configuración de pago. -
PATCH /api/v1/pass-flows/:id: Actualiza la visibilidad de los campos del formulario, requisitos OTP o configuración de pasarela de pago.
Obtenga más información sobre los canales públicos de distribución en Distribución en autoservicio y Enlaces de descarga y PassFlow.
