Skip to content
Zurück zum Blog

Entwickler-Leitfaden: REST-API-Integration für Wallet-Pässe

Pass-Templates erstellen, Pässe programmatisch via REST-API ausstellen und per Webhook sowie Update-Calls aktuell halten.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-08-162 Min. Lesezeit
Titelbild für Entwickler-Leitfaden: REST-API-Integration für Wallet-Pässe

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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
SYSTEMARCHITEKTUR-ABLAUF
STUFE 01 Ihre Anwendung / Backend
STUFE 02 Passinstance API-Engine
Erstellt PKCS#7-signiertes .pkpass für Apple Wallet
Erzeugt signierten JWT-Speicherlink für Google Wallet
STUFE 03 Kundengerät (iOS / Android)
STUFE 04 Passinstance Webhook-Gateway
4. POST/webhooks/pass-installedIhr Backend

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.
BASH
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:

TS
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:

TS
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:

TS
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.
Interaktive Live-Demo
Apple Wallet & Google Wallet

Echten Wallet-Pass auf Ihrem Smartphone testen

Erleben Sie digitale Pässe aus erster Hand. Scannen Sie mit Ihrer Smartphone-Kamera oder tippen Sie unten, um diesen Pass direkt zu Apple Wallet oder Google Wallet hinzuzufügen.

Artisan RoastersCafé & F&B
Test QR code for Artisan Roasters

Mit Smartphone-Kamera scannen

Verwandte Themen zu diesem Thema

Entwickler-API & Integrationen

Themen-Hub öffnen

Bereit, Ihr Wallet-Karten-Programm zu starten?

Erstellen Sie Ihr Konto, gestalten Sie Ihre Kartenvorlage und testen Sie echte Karten direkt in Apple Wallet und Google Wallet.