Met native Apple Wallet-passen (.pkpass-bestanden) kunnen bedrijven klantenkaarten, evenemententickets, instapkaarten, kortingsbonnen en lidmaatschapspassen direct op iPhone en Apple Watch aanbieden, zonder dat gebruikers een aparte app hoeven te downloaden.
Deze technische gids legt uit hoe de Apple PassKit-architectuur, cryptografische ondertekening, verspreiding en realtime updates via APNs werken.
1. Opbouw van een Apple Wallet-pas (.pkpass)
Een Apple Wallet-pas is een gecomprimeerd ZIP-archief met de extensie .pkpass, voorzien van gestructureerde JSON, afbeeldingen op retina-formaat en cryptografische handtekeningbestanden.
Vereiste bestandsstructuur
mijn-pas.pkpass
├── pass.json # Lay-out, velddefinities en metagegevens
├── logo.png # Merklogo linksboven (160x160 @2x)
├── logo@2x.png
├── icon.png # Meldingsicoon op toegangsscherm (58x58 @2x)
├── icon@2x.png
├── strip.png # Bannerafbeelding voor tickets en coupons (375x144 @2x)
├── strip@2x.png
├── manifest.json # SHA-1/SHA-256-hashes van alle bestanden in de bundel
└── signature # Cryptografische PKCS#7-handtekening met uw Pass Type ID-certificaat
2. Apple Developer-configuratie en certificaatondertekening
Om Apple Wallet-passen voor productie te ondertekenen, vereist Apple een actief Apple Developer-account en een geldig Pass Type ID-certificaat (.p12).
Stappenplan voor ondertekening:
-
1
Pass Type ID: Registreer een unieke identifier (bijv.
pass.com.uwbedrijf.loyalty) in het Apple Developer Portal. -
2
Certificate Signing Request (CSR): Genereer een 2048-bits RSA-privésleutel en CSR via OpenSSL of Sleutelhangertoegang.
-
3
Pass Type-certificaat: Download het uitgegeven
.cer-bestand en exporteer het samen met de privésleutel als.p12-bestand. -
4
WWDR-tussencertificaat: Voeg het Apple Worldwide Developer Relations G6-tussencertificaat toe aan de vertrouwensketen.
[!NOTE]
Geautomatiseerde ondertekening in Passinstance: Zodra u uw eigen Apple Developer Pass Type ID-certificaat in uw werkruimte uploadt, handelt Passinstance de PKCS#7-ondertekening, het WWDR-beheer en de
.pkpass-bundeling automatisch af.
3. Velden configureren in pass.json
Het bestand pass.json bepaalt het pasformaat (storeCard, coupon, eventTicket, boardingPass, generic) en de dynamische velden:
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.passinstance.loyalty",
"serialNumber": "PASS-8842-2026",
"teamIdentifier": "ABC123XYZ",
"organizationName": "Artisan Coffee",
"description": "Artisan Coffee Klantenkaart",
"logoText": "Artisan Coffee",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(10, 90, 84)",
"labelColor": "rgb(164, 243, 222)",
"storeCard": {
"primaryFields": [
{
"key": "stamps",
"label": "SPAARTEGOED",
"value": "8 van 10 stempels"
}
],
"secondaryFields": [
{
"key": "holder",
"label": "LID",
"value": "Jane Doe"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PASS-LOYALTY-8842",
"messageEncoding": "iso-8859-1"
}
],
"webServiceURL": "https://api.passinstance.com/v1/apple",
"authenticationToken": "auth_tok_99182348"
}

4. Locatietriggers op het toegangsscherm
Apple Wallet-passen ondersteunen maximaal 10 GPS-coördinaten (locations / relevantLocations) die passieve meldingen op het toegangsscherm kunnen weergeven wanneer een klant uw winkel nadert.
"locations": [
{
"latitude": 52.367573,
"longitude": 4.904139,
"relevantText": "Welkom terug! Scan uw klantenkaart bij de kassa voor 10% korting."
}
]
5. Realtime updates versturen via APNs
Wanneer een saldo, niveau of vervaldatum verandert, werkt Apple Wallet de pas bij via Apple Push Notification service (APNs):
-
1
Na installatie stuurt iOS een POST-verzoek naar uw
webServiceURLmet het apparaattoken (pushToken). -
2
Om de pas bij te werken, verstuurt uw backend een leeg APNs-pushsignaal naar de pushservers van Apple voor dat
pushToken. -
3
iOS haalt vervolgens stilletjes de nieuwste
pass.jsonop, werkt de weergave bij en toont een melding als een veld metchangeMessageis gewijzigd.
6. Apple Wallet-passen uitgeven via Passinstance
In plaats van zelf OpenSSL-ondertekening, APNs-pushservers en apparaatregistratie te onderhouden, regelt Passinstance de volledige pijplijn via één API-aanroep:
import { Passinstance } from "@passinstance/sdk";
const client = new Passinstance({ apiKey: process.env.PASSINSTANCE_API_KEY });
// Geef een ondertekende Apple Wallet-pas uit
const pass = await client.passes.create({
templateId: "tpl_coffee_loyalty",
data: {
holderName: "Jane Doe",
stamps: "8 van 10 stempels",
},
});
console.log("Link voor Apple Wallet:", pass.appleWalletUrl);

Belangrijkste voordelen
-
Geen app nodig: Klanten voegen de pas met één tik toe via Safari, een QR-code, e-mail of een gehoste link.
-
Altijd actueel: Saldowijzigingen worden automatisch gesynchroniseerd op iPhone en Apple Watch.
-
Locatierelevant: Ingestelde coördinaten tonen de pas automatisch wanneer klanten in de buurt zijn.





