Door digitale wallet-passen op te nemen in uw applicatiearchitectuur automatiseert u de uitgifte, verstuurt u directe pasupdates naar het toegangsscherm en beheert u de volledige levenscyclus van passen vanuit uw backend, CRM of kassasysteem.
Deze gids biedt een technisch overzicht van de Passinstance REST API, de TypeScript SDK, authenticatie, idempotentie en webhookverwerking.
1. Systeemarchitectuur en gegevensstroom
2. Authenticatie en omgevingssleutels
Passinstance gebruikt API-sleutelauthenticatie (X-API-Key) voor server-to-serververzoeken (naast Bearer JWT-sessietokens) via HTTPS/TLS. API-sleutels worden in het dashboard aangemaakt met gescheiden omgevingsscopes:
-
pi_test_...— Testomgeving voor sjabloonontwerp, proefpassen en webhooktests. -
pi_live_...— Productieomgeving voor live ondertekende Apple Wallet- en Google Wallet-passen.
curl -X GET https://api.passinstance.com/api/v1/templates \
-H "X-API-Key: pi_live_99481203948123"
3. Passen programmatisch aanmaken en uitgeven
Gebruik de officiële @passinstance/sdk (Node.js / TypeScript) of directe REST-aanroepen om passen vanuit uw backend uit te geven:
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, // Idempotentie en koppeling met uw database
data: {
memberName: user.name,
memberId: `MEM-${user.id.slice(0, 8)}`,
joinDate: new Date().toISOString().split("T")[0],
status: "Actief",
},
});
return {
appleUrl: pass.appleWalletUrl,
googleUrl: pass.googleWalletUrl,
qrCodeImageUrl: pass.qrCodeUrl,
};
}
4. Realtime pasupdates versturen
Om pasgegevens bij te werken (zoals een nieuw puntensaldo, een niveauverhoging of een gewijzigde toegangspoort), stuurt u een updateverzoek:
await client.passes.update("pass_9842011", {
data: {
pointsBalance: 2500,
tier: "Platinum",
},
pushNotification: {
message: "Gefeliciteerd! U bent gepromoveerd naar het Platinum-niveau.",
},
});
Eén enkele API-aanroep werkt zowel de Apple Wallet-pas via APNs als het Google Wallet-object via de Google Wallet API tegelijkertijd bij.
5. Webhook-gebeurtenissen ontvangen
Passinstance verstuurt realtime webhooks bij belangrijke pasgebeurtenissen zodat uw eigen database gesynchroniseerd blijft zonder periodiek te hoeven pollen.
Ondersteunde gebeurtenissen:
-
pass.created— Pas-payload is aangemaakt. -
pass.installed— Gebruiker heeft de pas toegevoegd aan Apple Wallet of Google Wallet. -
pass.updated— Pasvelden zijn bijgewerkt. -
pass.scanned— De 2D-barcodescanner of scanner-app heeft de pas gevalideerd. -
pass.removed— Gebruiker heeft de pas uit de wallet verwijderd.
Webhook-handtekeningen verifiëren:
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("Ongeldige handtekening", { status: 401 });
}
const event = JSON.parse(payload);
if (event.type === "pass.installed") {
console.log(`Pas ${event.data.passId} geïnstalleerd op ${event.data.platform}`);
}
return new Response("OK", { status: 200 });
}
6. Multi-tenancy en aangepaste domeinen
Voor SaaS-platformen en bureaus die pasuitgifte integreren voor hun klanten:
-
Beheer klantwerkruimtes afzonderlijk met gescheiden API-sleutels, certificaten en webhook-instellingen.
-
Configureer optioneel een eigen downloaddomein (CNAME zoals
wallet.uw-platform.nl) voor gehoste deel- en installatielinks. -
Gebruik HMAC-SHA256-verificatie om alle webhookverkeer per werkruimte te beveiligen.





