Überblick
Die Erstellung Ihrer ersten Wallet-Karte umfasst das Einrichten eines wiederverwendbaren visuellen Template, das Verknüpfen interaktiver Geschäftsmechaniken, eine Risikoprüfung vor der Veröffentlichung sowie die Ausgabe eines konkreten Pass-Datensatzes zur Installation auf iOS- und Android-Geräten.
Schritt-für-Schritt-Meilensteine
Folgen Sie diesem Ablauf in Passinstance Dashboard (Vorlagen -> Vorlage erstellen unter /templates/new) oder über die Developer-API:
-
1
Layout-Geometrie wählen (pass type): Entscheiden Sie sich für eines der unterstützten Pass-Formate:
- storeCard: Treuekarten, Stempelkarten und Geschenkkarten. - coupon: Einmalige Aktionsgutscheine und Rabatt-Coupons. - eventTicket / boardingPass: Konzerte, Sportevents, Festivals, Konferenzen oder Flug-/Bahnbordkarten. - membership / generic / posterGeneric / studentId / businessCard: Mitgliedsausweise, WWDC-Poster-Karten, Mitarbeiter-/Studierendenausweise und digitale Visitenkarten.
-
2
Branding, Farben & Assets:
- Farbformatierung: Apple Wallet verlangt strikt rgb(r, g, b)-Angaben (ohne Alpha-Kanal). Google Wallet akzeptiert Hex-Werte #RRGGBB. Der Farbwähler im Dashboard konvertiert automatisch und warnt bei geringem WCAG-Kontrast. - Bild-Slots (image asset slot): Laden Sie hochauflösende Grafiken in die bis zu 13 unterstützten Slots hoch (logo, primaryLogo, secondaryLogo, icon, googlePayLogo, strip, background, thumbnail, artwork, venueMap, footer, androidBackground, androidLogo).
-
3
Interaktive Pass-Mechanik zuweisen:
- Wählen Sie eine Regel-Engine (mechanic type): STAMP_CARD_ADD, STAMP_CARD_DEDUCT, LOYALTY_PROGRAM, PREPAID_CARD, VALID_ONCE_PER_DAY oder RENEW_EXPIRATION.
-
4
Dynamische Feldzonen definieren (field placement type):
- Platzieren Sie Felder in den Zonen HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO oder FOOTER. - Verwenden Sie dynamische geschweifte Tokens wie {memberName}, {pointsBalance} oder {expirationDate}. - Hinterlegen Sie Apple-changeMessage-Texte mit dem Platzhalter %@ (z. B. "Punkte aktualisiert: %@"), um native iOS-Sperrbildschirm-Push-Benachrichtigungen auszulösen.
-
5
Risikoanalyse vor Veröffentlichung & Freigabe:
- Das Dashboard ruft GET /api/v1/templates/:id/publish-risk-check auf, um kritische Änderungen zu erkennen, die Werte auf bereits ausgegebenen Pässen überschreiben könnten. - Klicken Sie auf Speichern & veröffentlichen (POST /api/v1/templates/:id/publish), um die DRAFT-Revision in die PRODUCTION-Basiszeile zu überführen.
-
6
Testpass erzeugen & installieren:
- Klicken Sie in der Vorlagenübersicht (/templates/:id/overview) auf Pass erstellen oder senden Sie eine REST-Anfrage an POST /api/v1/passes. Die Pass-Erstellung nutzt automatisch resolvePassCreationTemplateId, um den neuen Pass an die kanonische Basisvorlage zu binden.

Programmatische Pass-Erzeugung & Verifizierung
Entwickler können das Dashboard umgehen und personalisierte Wallet-Pässe direkt aus Backend-Systemen oder CRMs über POST /api/v1/passes (request payload) ausgeben. Übergeben Sie Idempotency-Key für sichere Wiederholungen und externalId für die CRM-Zuordnung, sowie optional ?includePassSource=apple|google, um direkte Wallet-Quellartefakte inline zurückzuerhalten:
HTTP-Anfrage
/api/v1/passes?includePassSource=google
{
"templateId": "tmpl_9a8b7c6d5e4f",
"externalId": "cust_100248",
"attributes": {
"memberName": "Elena Rostova",
"memberNumber": "MB-94021",
"points": "150"
},
"barcodeValue": "PI-MB-94021-SECURE",
"barcodeAltText": "MB-94021",
"expirationDate": "2027-12-31 23:59"
}
HTTP-Antwort (201 Created)
{
"success": true,
"data": {
"id": "pass_1a2b3c4d5e6f",
"templateId": "tmpl_9a8b7c6d5e4f",
"serialNumber": "PI-789042-XY",
"externalId": "cust_100248",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "NONE",
"appleArtifactStatus": "NOT_GENERATED",
"googleArtifactStatus": "READY",
"downloadUrl": "https://app.passinstance.com/d/elena-rostova-94021",
"passAccessUrl": "https://app.passinstance.com/p/pass_1a2b3c4d5e6f",
"passSource": {
"platform": "google",
"saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"createdAt": "2026-11-15T12:00:00Z"
},
"description": "Pass created successfully",
"errors": [],
"statusCode": 201
}
Sandbox-Beispielpass testen
Während der Test- und Evaluierungsphase können Sie sofort einen Beispielpass erzeugen, ohne vollständige Kundendatensätze eingeben zu müssen:
-
1
Rufen Sie
POST /api/v1/onboarding/sample-passauf oder klicken Sie im Wizard-Schritt/onboarding/try-passauf Beispielpass testen. -
2
Der Server erstellt einen kurzlebigen Pass und stellt den öffentlichen Beispiel-Endpunkt bereit:
/api/v1/onboarding/sample-pass/public/:sessionId
-
3
Scannen Sie den angezeigten QR-Code mit einer iPhone-Kamera, um die native Apple-Wallet-Installation zu starten, oder öffnen Sie den Link unter Android zum Testen mit Google Wallet.
-
4
Öffnen Sie den Scanner (
/scanner) inPassinstance Dashboardoder koppeln Sie die mobile App Passinstance Scanner überPOST /api/v1/scanner-keys/from-linkund scannen Sie den installierten Pass, um Live-Scan-Ereignisse und sofortige Push-Benachrichtigungen zu prüfen.
Wichtig: Testen Sie Ihren neu veröffentlichten Pass vor dem Start einer Kundenkampagne immer auf iOS- (Apple Wallet) und Android-Geräten (Google Wallet), um Farbkontrast, Textumbrüche bzw. Kürzungen sowie die Zuverlässigkeit des Barcode-Scans sicherzustellen.
Bereit zum Loslegen? Starten Sie Phase 2: Pass gestalten oder entdecken Sie Wallet-Pässe mit KI erstellen.
