Skip to content
Terug naar blog

Ontwikkelaarsgids: REST API-integratie voor wallet-passen

Pas-sjablonen ontwerpen, dynamisch passen uitgeven via de API en gebeurtenissen synchroniseren via ondertekende webhooks.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-08-162 min leestijd
Omslagafbeelding voor Ontwikkelaarsgids: REST API-integratie voor wallet-passen

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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUUR
FASE 01 Uw applicatie / backend
FASE 02 Passinstance API-engine
Bouwt PKCS#7-ondertekende .pkpass voor Apple Wallet
Genereert ondertekende JWT-opslaglink voor Google Wallet
FASE 03 Toestel van klant (iOS / Android)
FASE 04 Passinstance Webhook Gateway
4. POST/webhooks/pass-installedUw backend

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

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, // 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:

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

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("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.
Interactieve live demo
Apple Wallet & Google Wallet

Test een echte walletpas op uw telefoon

Ervaar zelf hoe digitale passen werken. Scan met uw camera of tik hieronder om deze pas direct toe te voegen aan Apple Wallet of Google Wallet.

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

Scan met smartphonecamera

Gerelateerd in dit onderwerp

Ontwikkelaars-API & integraties

Open topic-hub

Klaar om uw Wallet-kaart-programma te lanceren?

Maak uw account aan, ontwerp uw passjabloon en test echte passen direct in Apple Wallet en Google Wallet.