Skip to content
Hilfecenter-Anleitung · Pass-Verteilung
3 Min. LesezeitGeprüft 2026-11-16

Self-Service-Verteilung

Veröffentlichen Sie öffentliche PassFlow-URLs, Embed-Widgets, dynamische Wallet-URLs und NDEF-NFC-Tags für Walk-ins.

In dieser Anleitung

Kundinnen und Kunden rund um die Uhr selbst registrieren lassen

Neben dem Hochladen von CSV-Listen oder Backend-API-Aufrufen ermöglicht Passinstance die Veröffentlichung unauthentifizierter Self-Service-Kontaktpunkte am stationären Point of Sale, auf Bestellabschlussseiten im E-Commerce, auf Kassenbons und auf Produktverpackungen:

KanalIdeal geeignet fürFunktionsweise
Öffentliches PassFlow-FormularAufsteller am Tresen, E-Mail-Signaturen, QR-FlyerKundinnen und Kunden füllen ein mobil optimiertes Registrierungsformular (/p/:url) aus, bestätigen bei Aktivierung ein E-Mail-/SMS-OTP, schließen optional eine Zahlung ab und speichern den Pass direkt.
Eingebetteter Wallet-Button / WidgetKundenkonten, BestellbestätigungsseitenEinbetten eines interaktiven iFrames oder eines Add-to-Wallet-Script-Widgets direkt im HTML Ihrer Website.
Dynamische Wallet-URLTransaktions-E-Mails, SaaS-Dashboards, KundenportaleÜbergeben Sie parametrisierte Kundenattribute oder nutzen Sie upsert-by-external-id, sodass angemeldete Nutzende mit einem Tippen ihre vorausgefüllte Karte abrufen.
NDEF NFC-Smart-Tag / StickerTischaufsteller, Kassenbereiche, Smart-PosterBeschreiben Sie einen Standard-NDEF-NFC-Tag (NTAG213/215) mit Ihrer öffentlichen PassFlow-URL — ein Antippen mit iPhone oder Android öffnet das Formular ganz ohne QR-Scan.

Öffentliche PassFlow-Self-Enrollment-Architektur

Die PassFlow-Engine (PassFlow API unter /api/v1/pass-flows/public/:url, mit Alias /api/v1/passflows/public/:url und UI-Route /f/:url) orchestriert mehrstufige öffentliche Registrierungsstrecken (PassFlowType, PassFlowSubmissionStatus) mit integriertem Bot-Schutz (SpamProtectionMode), OTP-Verifizierung, Duplikatschutz (externalId) und direkter Wallet-Übergabe:

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
ÖFFENTLICHE PASSFLOW-SELBSTREGISTRIERUNG
STUFE 01 KUNDEN-EINSTIEGSPUNKT (QR / URL / NDEF-TAP)
GET/api/v1/pass-flows/public/:url (Lädt Flow-Schema)
STUFE 02 SCHRITT 1: FormStep (Kundenattribute & Einwilligungsprüfung)
Lädt CSRF-Token (/csrf-token) & validiert request payload
STUFE 03 SCHRITT 2 & 3: EmailStep / OtpStep (Optionale Identitätsprüfung)
Sendet Prüfcode über POST/api/v1/pass-flows/public/:url/otp/send
Verifiziert OTP-Token über POST/api/v1/pass-flows/public/:url/otp/verify
STUFE 04 SCHRITT 4: PaymentStep (Optional bezahlte Mitgliedschaften, Gutscheine, Tickets)
Unterstützt Stripe PaymentIntent, PayPal Orders, Paystack, MTN MoMo, Orange
STUFE 05 SCHRITT 5: PassStep (Idempotenter Upsert & sofortige Wallet-Übergabe)
Dedupliziert über E-Mail/Telefon/externalId (upsert-by-external-id-Logik)
Rendert Apple-Wallet-.pkpass-Button, Google-Save-JWT und QR-Code

Wichtig: Um doppelte Pass-Erstellungen zu verhindern, falls ein bestehendes Mitglied ein Self-Service-Formular erneut absendet, konfigurieren Sie Deduplizierungs- / External-ID-Regeln auf Ihrer Vorlage bzw. Ihrem PassFlow (email, phone oder externalId). Eigene Portale können außerdem direkt POST /api/v1/passes/upsert-by-external-id aufrufen, um den bereits existierenden aktiven Pass statt eines Duplikats zurückzugeben.

Öffentliche PassFlow- & Self-Service-API-Referenz

MethodeEndpunkt-PfadAuthentifizierungBeschreibung
GET/api/v1/pass-flows/public/:urlÖffentlichRuft die öffentliche PassFlow-Schrittkonfiguration (PassFlowStepType), das Formularschema, das Theme (page theme: `LIGHT \DARK \CUSTOM`) und Vorlagenvorschaudaten ab.
GET/api/v1/pass-flows/public/:url/csrf-tokenÖffentlichStellt das Anti-CSRF-Token aus, das vor dem Absenden einer öffentlichen Pass-Generierung erforderlich ist.
POST/api/v1/pass-flows/public/:url/generateÖffentlichÜbermittelt die Registrierungsdaten (request payload: userData, recaptchaToken?, botProtectionToken?), um den Pass zu erstellen bzw. abzurufen.
POST/api/v1/pass-flows/public/:url/otp/sendÖffentlich (Rate-Limited)Sendet während OtpStep ein Einmalpasswort (POST .../otp/resend zum erneuten Versand).
POST/api/v1/pass-flows/public/:url/otp/verifyÖffentlich (Rate-Limited)Prüft den eingegebenen OTP-Code und schaltet die Pass-Generierung frei.
POST/api/v1/pass-flows/public/:url/payment-intentÖffentlichInitialisiert einen Stripe PaymentIntent (GET .../payment-config, /paypal-order, /paystack/initialize, /mtn-momo/request-to-pay, /orange-money/initiate).
POST/api/v1/passes/upsert-by-external-idAPI Key (passes)request payload — erstellt (CREATED) oder aktualisiert (UPDATED) idempotent den Pass einer Kundin/eines Kunden anhand von externalId.

Beispiel: Idempotentes Portal-Onboarding via upsert-by-external-id

Wenn Sie einen Button Zu Wallet hinzufügen in Ihr eigenes authentifiziertes Kundenportal oder Ihre Web-App einbetten, rufen Sie serverseitig POST /api/v1/passes/upsert-by-external-id auf und leiten Nutzende auf passAccessUrl weiter:

JSON
POST /api/v1/passes/upsert-by-external-id
{
  "templateId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
  "externalId": "USR-90214",
  "status": "ACTIVE",
  "attributes": {
    "firstName": "Elena",
    "lastName": "Rostova",
    "email": "elena.rostova@example.com",
    "tier": "Gold",
    "points": 1250
  }
}

Antwort (200 OK):

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
      "serialNumber": "PI-8849-2026-X9",
      "externalId": "USR-90214",
      "bundleId": null,
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED",
      "passAccessUrl": "https://app.passinstance.com/p/c41a8d20-6e11-4f3b-9a81-0029d81a4f10"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

NDEF-NFC-Aufsteller für den Kassenbereich kodieren

Um physische Tap-to-Enroll-Aufsteller an der Kasse ohne Apple-VAS- oder Google-Smart-Tap-Lesegeräte bereitzustellen:

  1. 1
    Kopieren Sie Ihre öffentliche PassFlow-URL (z. B. https://app.passinstance.com/f/coffee-club-vip).
  2. 2
    Schreiben Sie mithilfe einer Standard-NFC-App (wie NFC Tools) einen NDEF-URI-Eintrag auf einen NTAG213-, NTAG215- oder NTAG216-Sticker und aktivieren Sie Tag sperren (Schreibschutz / Read-Only), damit niemand die URL überschreiben kann.
  3. 3
    Sobald Kundinnen oder Kunden ihr entsperrtes iPhone oder Android-Smartphone an den Aufsteller halten, öffnet das Betriebssystem die PassFlow-Registrierungsseite direkt in Safari oder Chrome.

Für Einbettungsparameter und Webhook-Trigger lesen Sie den Leitfaden Registrierungsformulare & PassFlow sowie den Integrations-Leitfaden.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.