Die Integration digitaler Wallet-Pässe in Ihre Produktarchitektur ermöglicht eine automatisierte Ausstellung, laufende Sperrbildschirm-Aktualisierungen und durchgängiges Lifecycle-Management direkt aus Ihrem Backend, CRM oder Kassensystem.
Dieser Leitfaden bietet eine kompakte technische Übersicht zur Anbindung der Passinstance REST-API, offizieller SDKs, Authentifizierung, Idempotenz und Webhook-Verarbeitung.
1. Systemarchitektur & Datenfluss
2. Authentifizierung & Umgebungs-Schlüssel
Passinstance unterstützt für Server-to-Server-Anfragen über HTTPS/TLS die API-Key-Authentifizierung per X-API-Key-Header (ergänzend zu Bearer-JWT-Sitzungstokens). API-Schlüssel werden im Dashboard mit klar getrennten Umgebungen erzeugt:
-
pi_test_...— Sandbox-Umgebung zum Testen von Vorlagen, Testpässen und Webhook-Auslösern. -
pi_live_...— Produktionsumgebung für live signierte Apple Wallet- und Google Wallet-Pässe.
curl -X GET https://api.passinstance.com/api/v1/templates \
-H "X-API-Key: pi_live_99481203948123"
3. Pässe programmatisch erstellen und ausstellen
Verwenden Sie das offizielle @passinstance/sdk (Node.js / TypeScript) oder direkte HTTP-REST-Aufrufe aus Ihrem Backend:
import { Passinstance } from "@passinstance/sdk";
const client = new Passinstance({
apiKey: process.env.PASSINSTANCE_API_KEY!,
});
export async function handleCustomerSignup(user: { id: string; email: string; name: string }) {
const pass = await client.passes.create({
templateId: "tpl_membership_gold",
externalId: user.id, // Idempotenz & Datenbank-Referenz
data: {
memberName: user.name,
memberId: `MEM-${user.id.slice(0, 8)}`,
joinDate: new Date().toISOString().split("T")[0],
status: "Active",
},
});
return {
appleUrl: pass.appleWalletUrl,
googleUrl: pass.googleWalletUrl,
qrCodeImageUrl: pass.qrCodeUrl,
};
}
4. Laufende Pass-Updates & Hinweise versenden
Um Passdaten anzupassen (z. B. neuer Punktestand, Stufenaufstieg oder geändertes Einlass-Gate), senden Sie eine Aktualisierungsanfrage:
await client.passes.update("pass_9842011", {
data: {
pointsBalance: 2500,
tier: "Platinum",
},
pushNotification: {
message: "Glückwunsch! Sie haben den Platinum-Status erreicht.",
},
});
Dieser einzelne API-Aufruf stößt gleichzeitig APNs-Updates für Apple Wallet sowie Google Wallet REST-Statusaktualisierungen für Android an.
5. Webhook-Ereignisse empfangen und verifizieren
Passinstance liefert Ereignis-Webhooks für zentrale Lebenszyklus-Schritte, damit Ihre Datenbank ohne Polling synchron bleibt.
Unterstützte Ereignistypen:
-
pass.created— Pass-Payload wurde erstellt. -
pass.installed— Nutzer hat den Pass zu Apple Wallet oder Google Wallet hinzugefügt. -
pass.updated— Passfelder wurden aktualisiert. -
pass.scanned— Der Pass-Barcode wurde am POS oder Einlass gescannt. -
pass.removed— Nutzer hat den Pass aus der Wallet entfernt.
Webhook-Signaturen prüfen:
import { verifyWebhookSignature } from "@passinstance/sdk/crypto";
export async function handleWebhookRequest(req: Request) {
const signature = req.headers.get("x-passinstance-signature")!;
const payload = await req.text();
const isValid = verifyWebhookSignature({
payload,
signature,
secret: process.env.PASSINSTANCE_WEBHOOK_SECRET!,
});
if (!isValid) {
return new Response("Ungültige Signatur", { status: 401 });
}
const event = JSON.parse(payload);
if (event.type === "pass.installed") {
console.log(`Pass ${event.data.passId} auf ${event.data.platform} installiert`);
}
return new Response("OK", { status: 200 });
}
6. Mandantenfähigkeit & eigene Domains
Für SaaS-Plattformen, die Pass-Ausstellung direkt in eigene Kundenkonten einbetten:
-
Nutzen Sie
/api/v1/admin/tenants, um Unterorganisationen sauber anzulegen. -
Hinterlegen Sie einen CNAME-Eintrag für eine eigene Auslieferungs-Domain (z. B.
wallet.ihre-saas.de). -
Trennen Sie Webhooks und API-Schlüssel strikt nach Mandanten-Workspace.





