Mit nativen Apple Wallet-Pässen (.pkpass-Dateien) stellen Unternehmen Treuekarten, Eintrittskarten, Bordkarten, Gutscheine und Mitgliedsausweise direkt auf dem Sperrbildschirm von iPhone und Apple Watch bereit – ohne dass Kundinnen und Kunden eine eigene App herunterladen müssen.
Dieser technische Leitfaden für 2026 erläutert alles Wesentliche zu Apples PassKit-Architektur, kryptografischer Signierung, Verteilung und laufenden Push-Aktualisierungen über APNs.
1. Aufbau eines Apple Wallet-Passes (.pkpass)
Ein Apple Wallet-Pass ist ein komprimiertes ZIP-Archiv mit der Dateiendung .pkpass, das strukturiertes JSON, lokalisierte Bilddateien und kryptografische Prüfsummen sowie Signaturen für Apple enthält.
Erforderliche Bundle-Struktur
mein-pass.pkpass
├── pass.json # Layout-Typ, Felddefinitionen und Metadaten
├── logo.png # Markenlogo oben links (160x160 @2x)
├── logo@2x.png
├── icon.png # Symbol für Sperrbildschirm-Hinweise (58x58 @2x)
├── icon@2x.png
├── strip.png # Bannergrafik für Tickets und Gutscheine (375x144 @2x)
├── strip@2x.png
├── manifest.json # SHA-1-Prüfsummen aller Dateien im Archiv
└── signature # Kryptografische PKCS#7-Signatur mit Ihrem Pass Type ID-Zertifikat
2. Apple Developer-Einrichtung & Zertifikats-Signierung
Für das native Signieren von Apple Wallet-Pässen verlangt Apple PKCS#12-Signaturzertifikate aus einem aktiven Apple Developer-Konto.
Schritt-für-Schritt-Signierung:
-
1
Pass Type ID: Registrieren Sie eine eindeutige Kennung (z. B.
pass.com.ihrunternehmen.loyalty) im Apple Developer Portal. -
2
Certificate Signing Request (CSR): Erzeugen Sie einen 2048-Bit-RSA-Privatschlüssel und eine CSR-Datei über OpenSSL oder die Schlüsselbundverwaltung.
-
3
Pass Type-Zertifikat: Laden Sie die ausgestellte
.cer-Datei herunter und exportieren Sie sie zusammen mit dem privaten Schlüssel als.p12-Container. -
4
WWDR-Zwischenzertifikat: Binden Sie das Apple Worldwide Developer Relations G6-Zwischenzertifikat in Ihre Vertrauenskette ein.
[!NOTE]
Verwaltete Signierung in Passinstance: Hinterlegen Sie Ihr Apple Developer Pass Type ID-Zertifikat einfach in Ihrem Workspace – Passinstance übernimmt die kryptografische PKCS#7-Signierung, die WWDR-Zertifikatskette und die
.pkpass-Erstellung automatisch.
3. pass.json-Felder konfigurieren
Die Datei pass.json legt den Pass-Typ (storeCard, coupon, eventTicket, boardingPass, generic) sowie alle dynamischen Felder fest:
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.passinstance.loyalty",
"serialNumber": "PASS-8842-2026",
"teamIdentifier": "ABC123XYZ",
"organizationName": "Artisan Rösterei",
"description": "Artisan Treuekarte",
"logoText": "Artisan Rösterei",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(10, 90, 84)",
"labelColor": "rgb(164, 243, 222)",
"storeCard": {
"primaryFields": [
{
"key": "stamps",
"label": "PRÄMIENFORTSCHRITT",
"value": "8 von 10 Stempeln"
}
],
"secondaryFields": [
{
"key": "holder",
"label": "MITGLIED",
"value": "Jane Doe"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PASS-LOYALTY-8842",
"messageEncoding": "iso-8859-1"
}
],
"webServiceURL": "https://api.passinstance.com/v1/apple",
"authenticationToken": "auth_tok_beispiel_99182348"
}

4. Standortbezogene Sperrbildschirm-Hinweise (locations)
Apple Wallet-Pässe unterstützen bis zu 10 Standortkoordinaten (locations), die passive Hinweise auf dem Sperrbildschirm einblenden können, sobald sich ein iPhone in der Nähe Ihrer Filiale oder Ihres Veranstaltungsorts befindet:
"locations": [
{
"latitude": 37.774929,
"longitude": -122.419416,
"relevantText": "Willkommen zurück! Scannen Sie Ihre Karte an der Kasse für 10 % Rabatt."
}
]
5. Pass-Aktualisierungen über APNs ausspielen
Ändern sich Punktestand, Mitgliedsstufe oder Gültigkeitsdatum, aktualisiert Apple Wallet den gespeicherten Pass über den Apple Push Notification Service (APNs):
-
1
Nach der Installation sendet iOS eine POST-Anfrage mit dem Geräte-Token (
pushToken) an IhrewebServiceURL. -
2
Zur Aktualisierung sendet Ihr Server ein leeres APNs-Wecksignal an die Push-Server von Apple für das jeweilige
pushToken. -
3
iOS ruft daraufhin die aktualisierte
pass.jsonvon Ihrem Server ab, aktualisiert die Darstellung und zeigt eine Sperrbildschirm-Mitteilung an, sofern sich ein Feld mit konfiguriertemchangeMessagegeändert hat.
6. Apple Wallet-Pässe per API mit Passinstance erstellen
Statt eigene OpenSSL-Signatur-Pipelines, APNs-Worker und Endpunkte zur Geräteregistrierung selbst zu betreiben, steuern Sie den gesamten Ablauf über Passinstance:
import { Passinstance } from "@passinstance/sdk";
const client = new Passinstance({ apiKey: process.env.PASSINSTANCE_API_KEY });
// Apple Wallet-Pass signiert ausstellen
const pass = await client.passes.create({
templateId: "tpl_coffee_loyalty",
data: {
holderName: "Jane Doe",
stamps: "8 von 10 Stempeln",
},
});
console.log("Link für Apple Wallet:", pass.appleWalletUrl);
Wichtigste Vorteile
-
Keine eigene App nötig: Kundinnen und Kunden fügen Pässe direkt über Safari, QR-Code, E-Mail oder Weblink hinzu.
-
Synchronisierter Status: Punkte- und Statusänderungen aktualisieren sich auf iPhone und Apple Watch.
-
Standortrelevanz: Konfigurierte Koordinaten bringen den Pass in Filialnähe gezielt auf den Sperrbildschirm.






