Skip to content
REST API-referentie & SDK's

Passinstance Documentatie voor Ontwikkelaars

Bouw grootschalige Apple Wallet (.pkpass) en Google Wallet integraties. Uitgeven, bijwerken, scannen en realtime meldingen versturen via productieklare REST-API's.

API-sleutels ophalen
5-minuten snelstartAPI-sleutel ophalen

Maak uw eerste Wallet-pas binnen 5 minuten

Geef Apple Wallet- (.pkpass) en Google Wallet-passen uit, onderteken ze cryptografisch en distribueer ze met één REST-aanroep.

Live Pass Studio — bewerk velden om code & kaart direct bij te werken
Levert Apple Wallet (.pkpass) & Google Wallet
Uitvoervoorbeeld
ARAcme Rewards
Punten
450
Lid
Jane Doe
Gold VIP
MEMBER-2024-8891
PKCS#7 · .pkpassHTTP 201
POST/api/v1/passes
curl --max-time 30 -X POST https://api.passinstance.com/api/v1/passes \
  -H "X-API-Key: $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "externalId": "CRM-CUST-99201",
    "name": "Acme VIP Customer Pass",
    "attributes": {
      "guestName": "Jane Doe",
      "tier": "Gold VIP",
      "points": "450"
    },
    "storedValue": "50.00",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'
Overzicht

Introductie — API-overzicht

Met de Passinstance API kunnen ontwikkelaars dynamisch digitale passen uitgeven, distribueren, bijwerken en valideren voor Apple Wallet (iOS) en Google Wallet (Android). Alle API-verzoeken verlopen via HTTPS en retourneren een gestandaardiseerde API-responsenvelop met machineleesbare statuscodes.

Productie Basis-URL
Actief
https://api.passinstance.com/api/v1
Staging Sandbox Basis-URL
https://staging-api.passinstance.com/api/v1
Aanvraag- & responsformaatapplication/json (UTF-8) met standaard responsenvelop
Tijdzone backendserverEurope/Berlin (ISO 8601-tijdstempels)
Beveiliging

Authenticatie — API-sleutels & autorisatie

Gebruik X-API-Key: <key> of Authorization: ApiKey <key> voor endpoints die API-sleutels ondersteunen. Bearer is bedoeld voor toegangs-JWT's. Bewaar inloggegevens op de server.

Productiesleutels (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Sandbox-sleutels (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Hardware-scannersleutels
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
Beveiligingsinvariant:Alleen server-naar-server. Sluit nooit geheime sleutels in frontend-bundles in.
Snelstart

Snelstart — Eerste API-verzoek

Maak uw eerste bruikbare pas in minder dan 5 minuten. Stel uw API-sleutelheader in, roep POST /api/v1/passes aan met een geldige templateId en stuur de ontvangen passAccessUrl naar uw eindgebruiker.

Stap 1: Sleutel instellen
export PASSINSTANCE_API_KEY="pi_test_..."
Stap 2: Pas uitgeven

POST /api/v1/passes met templateId en serialNumber

Stap 3: URL ophalen

Haal response.data.passAccessUrl uit de 201 Created-respons

Stap 4: Distribueren

Stuur URL via sms/e-mail; gebruiker tikt op "Toevoegen aan Apple/Google Wallet"

Bronnen

Postman-collectie — API-verzoeken importeren & testen

Importeer de Passinstance OpenAPI 3.0-specificatie (/api/docs/openapi.json) rechtstreeks in Postman, Insomnia of Bruno om eindpunten te testen, schema's te inspecteren en getypeerde HTTP-clients te genereren.

OpenAPI 3.0 JSON-specificatie openen
1. OpenAPI 3.0-specificatie-URL
https://passinstance.com/api/docs/openapi.json
2. Importeren in Postman / Bruno

Klik op Import in Postman, Insomnia of Bruno en plak /api/docs/openapi.json om alle routes te laden

3. Omgeving configureren

Stel baseUrl = https://api.passinstance.com en PASSINSTANCE_API_KEY = pi_test_... in

4. Verbinding controleren

Voer GET /api/v1/templates uit met X-API-Key: om uw workspace te testen

Operaties & FAQ

FAQ — Veelgestelde vragen & foutafhandeling

Elke respons gebruikt de standaard API-responsenvelop. Los 4xx-fouten op voordat u het opnieuw probeert; wacht bij 5xx en 429 op basis van Retry-After.

200 OK / 201 CreatedGeslaagd
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Kernbegrippen

Architectuur & Levenscyclus van passen

Pasbeheer volgt een levenscyclus in 6 fasen: 1. Sjabloon (visuele blauwdruk) → 2. Pas (cryptografisch ondertekend record) → 3. Distributie (beveiligde passAccessUrl) → 4. Wallet-registratie (apparaat meldt zich aan bij APNs / Google Push) → 5. Live updates (realtime meldingen) → 6. Scan- & inwisseltelemetrie (validatie & webhook-stream).

1. SjabloonPOST /api/v1/templates

Hoofdlay-out, streepjescodetype, merkkleuren en schemavelden

Platformgidsen

Apple Wallet vs. Google Wallet matrix

Passinstance ondertekent automatisch .pkpass-pakketten voor iOS en genereert ondertekende JWT-objecten voor Google Wallet. Afbeeldingen, streepjescodes en triggers passen zich automatisch aan beide besturingssystemen aan.

Apple WalletiOS · .pkpass
Apple Wallet-ondertekening

Cryptografische PKCS#7-handtekening met Apple Pass Type ID-certificaat

Google WalletAndroid · JWT
Google Wallet-uitgever

Google Cloud Service Account REST JWT-payload

Cross-platform pariteit (één REST-aanroep)iOS + Android
Hero- / Strip-afbeeldingenApple: 375×123 px (3:1) | Google: 1032×336 px (circa 3:1)
Universele streepjescodesQR-code en PDF417 standaard ondersteund op beide mobiele platformen
Kernbegrippen

Pasmechanica & Loyaliteitsoplossingen

Koppel stateful bedrijfsmechanica aan sjablonen voor 8 kant-en-klare oplossingen (Loyaliteit, Stempelkaarten, Coupons, Cadeau-/Prepaidkaarten, Evenementtickets, Lidmaatschappen, Personeelspassen, VIP-kaarten). Regels worden atomair uitgevoerd bij een scan of API-aanroep.

LOYALTY_PROGRAM

LOYALTY_PROGRAM & Niveaus

Puntenopbouw per scan (defaultChangeValue) met automatische niveauverhoging

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Houdt stempelposities bij (0..maximumValue) met onCap ('noop' | 'reset') en rewardClaimBehavior

PREPAID_CARD

PREPAID_CARD Grootboek

ISO 4217-grootboekadministratie voor prepaid in kleinste eenheden met disallowNegativeBalance-handhaving

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY & RENEW

Tijdzonebewuste dagelijkse inchecklimieten en automatische verlenging van expirationDate bij scan

Sjabloonbeheer

7 eindpunten
GEThttps://api.passinstance.com/api/v1/templatesAPI-sleutel
Sjabloonbeheer

Alle sjablonen weergeven

Haal een gepagineerde lijst met passjablonen op die behoren tot de geauthenticeerde klantwerkruimte.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters3 optioneel

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/templates/{id}API-sleutel
Sjabloonbeheer

Sjabloongegevens ophalen

Haal volledige gegevens van een passjabloon op inclusief kleuren, streepjescode-instellingen, lay-outvelden en mechanicaregels.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idUUID
Vereist

Unieke sjabloonidentificatie.

Voorbeeld: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/templates/{id}/fieldsAPI-sleutel
Sjabloonbeheer

Sjabloonvelden ophalen

Haal de berekende dynamische velddefinities en aangepaste eigenschapssleutels op die per pas voor een sjabloon kunnen worden ingevuld.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Unieke sjabloon-UUID.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Queryparameters1 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/templatesAPI-sleutel
Sjabloonbeheer

Passjabloon aanmaken

Ontwerp en registreer een herbruikbaar passjabloon met visuele branding, streepjescodetype, NFC-configuratie en lay-outvelden.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Sjabloonconfiguratie volgens het OpenAPI JSON-schema.

Aanvraagtekst6 vereist • 4 optioneel
namestring
Vereist

Weergavenaam van het sjabloon.

Voorbeeld: VIP Loyalty Card Template
descriptionstring
Vereist

Gedetailleerde beschrijving van het doel van de pas en niveauvoordelen.

Voorbeeld: Exclusive loyalty and rewards card for VIP customers
organizationNamestring
Vereist

Organisatie- / merknaam weergegeven in de kaartkop.

Voorbeeld: Acme Rewards
kindstring (enum)
Vereist

storeCard, coupon, eventTicket, generic, boardingPass of membership.

Voorbeeld: storeCard
statusstring (enum)
Vereist

DRAFT, PUBLISHED, ARCHIVED, DEPRECATED of UNDER_REVIEW.

Voorbeeld: PUBLISHED
preferredStyleSchemestring (enum)
Vereist

DARK, posterGeneric, posterEventTicket, bannerEventTicket of semanticBoardingPass.

Voorbeeld: DARK

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/templates/{id}/publishAPI-sleutel
Sjabloonbeheer

Sjabloonconcept publiceren

Promoveer een conceptrevisie (rowKind: DRAFT) naar PUBLISHED, markeer changesToPush: true en zet APNs- en Google Wallet-updates in de wachtrij voor alle actieve passen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Sjabloon-UUID om te publiceren.

Voorbeeld: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Verzoekpayload voor directe versus geplande publicatie en wallet-pushverspreiding.

Aanvraagtekst4 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/templates/{id}/copyAPI-sleutel
Sjabloonbeheer

Sjabloon dupliceren

Kloon een bestaand passjabloon inclusief lay-out, kleuren, afbeeldingen en mechanieken binnen dezelfde klant-workspace.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Bron-sjabloon-UUID om te dupliceren.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Optional name, description, and ISO 4217 currency override for the duplicated template.

Aanvraagtekst3 optioneel

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/templates/{id}API-sleutel
Sjabloonbeheer

Sjabloon verwijderen

Verwijder een passjabloon en start een asynchrone achtergrondtaak om gekoppelde passen in Apple Wallet en Google Wallet in te trekken.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Te verwijderen sjabloon-UUID.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwoordstatuscodes

Sjabloonmeldingen

3 eindpunten
POSThttps://api.passinstance.com/api/v1/push-notifications/templates/{id}/sendAPI-sleutel
Sjabloonmeldingen

Push verzenden naar alle passen van sjabloon

Verzend direct een pushmelding op het vergrendelscherm naar alle actieve Apple Wallet- en Google Wallet-passen onder een sjabloon.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Sjabloon-UUID waarvan de geregistreerde apparaten de melding ontvangen.

Voorbeeld: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Verzoekpayload met pushNotificationText (max. 85 tekens) en optionele koptekst.

Aanvraagtekst1 vereist • 1 optioneel
pushNotificationTextstring
Vereist

Vergrendelschermmelding verzonden naar actieve passen (max. 85 tekens; ondersteunt variabelen).

Voorbeeld: Flash Sale starts now! Show your VIP pass at checkout for 2x points.

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/templates/{id}/notificationAPI-sleutel
Sjabloonmeldingen

Geplande meldingen weergeven

Toon alle geplande en recent uitgevoerde pushmeldingscampagnes voor een specifiek passjabloon.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Template UUID.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/templates/notification/{notificationId}API-sleutel
Sjabloonmeldingen

Geplande melding annuleren

Annuleer een openstaande geplande sjabloon-pushmelding voordat deze naar geregistreerde apparaten wordt verzonden.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
notificationIdstring (UUID)
Vereist

UUID van de geplande melding geretourneerd bij het plannen of ophalen.

Voorbeeld: f1e2d3c4-b5a6-4987-8765-43210fedcba9

Antwoordstatuscodes

Sjabloonintegraties

2 eindpunten
POSThttps://api.passinstance.com/api/v1/integration-connections/embed-widgetsAPI-sleutel
Sjabloonintegraties

Embed-integratie aanmaken (iFrame)

Maak een insluitbare iFrame-widgetconfiguratie voor een gepubliceerd sjabloon om pasregistratie op uw website in te sluiten.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Configuration for the embedded download widget including templateId and allowed host domains.

Aanvraagtekst3 vereist • 1 optioneel
namestring
Vereist

Weergavenaam voor de embed-widgetintegratie.

Voorbeeld: Checkout Loyalty Embed Widget
templateIdstring (UUID)
Vereist

UUID van het doel-passjabloon.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
allowedDomainsstring[]
Vereist

Lijst van toegestane origins (domeinen) die de widget mogen insluiten.

Voorbeeld: ["shop.yourbrand.com", "app.yourbrand.com"]

Antwoordstatuscodes

Pasbeheer

11 eindpunten
POSThttps://api.passinstance.com/api/v1/passesAPI-sleutel
Pasbeheer

Nieuwe pas uitgeven

Maak een nieuwe Apple Wallet- (.pkpass) en Google Wallet-pas aan op basis van een sjabloon met klantvelden, streepjescode en dynamische waarden.

Headers (kopteksten)2 vereist • 1 optioneel
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json
Queryparameters2 optioneel

Verzoekpayload met sjabloon-ID, uniek serienummer, klantveldwaarden en optionele streepjescodeconfiguratie.

Aanvraagtekst1 vereist • 15 optioneel
templateIdstring (UUID)
Vereist

Sjabloon-ID voor de pas.

Voorbeeld: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idAPI-sleutel
Pasbeheer

Pas synchroniseren via externe ID (Upsert)

Maak of update op idempotente wijze een pas op basis van (customerId, externalId) voor naadloze CRM-, kassa- en e-commercesynchronisatie.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met templateId, externalId en dynamische pasattributen.

Aanvraagtekst2 vereist • 3 optioneel
templateIdstring (UUID)
Vereist

UUID van het doelsjabloon.

Voorbeeld: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Vereist

Stabiele externe CRM/POS-identificatie uniek binnen uw werkruimte.

Voorbeeld: CRM-CUST-99201

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createAPI-sleutel
Pasbeheer

Passen in bulk uitgeven

Geef meerdere wallet-passen uit in één atomaire batchbewerking met validatie en foutrapportage.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met een array van pasconfiguraties.

Aanvraagtekst1 vereist
passesarray of objects
Vereist

Array van pasitems met templateId, barcodeValue en additionalData.

Voorbeeld: [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passesAPI-sleutel
Pasbeheer

Alle passen weergeven

Haal een gepagineerde lijst met passen op voor de geauthenticeerde klantwerkruimte met zoek- en statusfilters.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters13 optioneel

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}API-sleutel
Pasbeheer

Pas ophalen

Haal volledige details, installatiestatus en downloadlinks op voor één pas via de unieke ID.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

De unieke UUID-identificatie van de pas.

Voorbeeld: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Antwoordstatuscodes

PATCHhttps://api.passinstance.com/api/v1/passes/{id}API-sleutel
Pasbeheer

Pas bijwerken & pushmelding sturen

Werk dynamische velden, kleuren of streepjescode van een pas bij en verstuur automatisch APNs- en Google Wallet-pushmeldingen naar geïnstalleerde apparaten.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

De unieke UUID van de bij te werken pas.

Voorbeeld: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Verzoekpayload-velden om op de pas te wijzigen. Geïnstalleerde apparaten ontvangen directe achtergrondupdates.

Aanvraagtekst13 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidAPI-sleutel
Pasbeheer

Pas deactiveren

Markeer een pas als ongeldig of opnieuw geactiveerd in Apple Wallet en Google Wallet met directe pushsynchronisatie.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idUUID
Vereist

Unieke pasinstantie-ID om ongeldig te maken of te reactiveren.

Voorbeeld: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Verzoekpayload voor het instellen van de status, auditreden en wallet-distributieopties.

Aanvraagtekst1 vereist • 1 optioneel
voidedboolean
Vereist

Stel in op true om de pas ongeldig te maken, of false om deze opnieuw te activeren.

Voorbeeld: true

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/passes/{id}API-sleutel
Pasbeheer

Pas verwijderen

Verwijder een pas definitief uit uw workspace en trek actieve Apple Wallet- en Google Wallet-installaties in.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Unieke UUID van de te verwijderen pas.

Voorbeeld: b1d972dc-eccf-4f87-ab21-25939d9213d8

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/useAPI-sleutel
Pasbeheer

Mechanica-actie uitvoeren

Voer een atomaire pasmechanica-operatie uit: INCREMENT (stempelkaart), DECREMENT, DEBIT (prepaid-tegoed), CREDIT of VALIDATE (eenmalige coupon).

Headers (kopteksten)3 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json
Idempotency-Keystring
Vereist

Verplichte UUID om atomaire uitvoering te garanderen en dubbele tegoed- of stempelafschrijvingen te voorkomen.

Voorbeeld: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Padparameters1 vereist
idstring (UUID)
Vereist

De unieke UUID van de te bewerken pas.

Voorbeeld: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Verzoekpayload met de mechanica-actie, optioneel decimaal bedrag, operator-ID en locatie.

Aanvraagtekst1 vereist • 4 optioneel
actionstring (enum)
Vereist

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE of NOOP.

Voorbeeld: INCREMENT

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueAPI-sleutel
Pasbeheer

Passaldo aanpassen

Schrijf saldo of spaarpunten handmatig bij (CREDIT) of af (DEBIT) op een pas met transactie-auditlogboek.

Headers (kopteksten)3 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json
Idempotency-Keystring
Vereist

Verplichte UUID om atomaire aanpassing te waarborgen en dubbel bijschrijven te voorkomen.

Voorbeeld: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Padparameters1 vereist
idUUID
Vereist

Doel-pasinstantie-ID.

Voorbeeld: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Aanpassingspayload die CREDIT- of DEBIT-operatie, bedrag en reden specificeert.

Aanvraagtekst2 vereist • 2 optioneel
actionstring
Vereist

Transactieactie: 'CREDIT' om waarde toe te voegen, of 'DEBIT' om af te schrijven.

Voorbeeld: CREDIT
amountstring
Vereist

Numeriek bedrag om bij te schrijven of af te schrijven als tekenreeks.

Voorbeeld: 25.00

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/mechanics/redeemAPI-sleutel
Pasbeheer

Beloning van pasmechanica inwisselen

Wissel een verdiende loyaliteits- of stempelkaartbeloning op een pas in via de geconfigureerde pasmechaniek met idempotentiebescherming.

Headers (kopteksten)1 vereist • 1 optioneel
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Inwisselverzoek met passId, mechanicId en optioneel idempotencyKey.

Aanvraagtekst2 vereist • 3 optioneel
passIdstring (UUID)
Vereist

UUID van de pas waarmee de beloning wordt ingewisseld.

Voorbeeld: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Vereist

UUID van de pasmechaniekregel gekoppeld aan het sjabloon.

Voorbeeld: mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Antwoordstatuscodes

Zoeken & analyse

4 eindpunten
GEThttps://api.passinstance.com/api/v1/passes/searchAPI-sleutel
Zoeken & analyse

Passen doorzoeken

Voer een full-text zoekopdracht uit op uitgegeven passen op serienummer, externe ID, e-mailadres, houdernaam of attributen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters1 vereist
querystring
Vereist

Zoekopdracht (maximaal 500 tekens).

Voorbeeld: Jane Doe

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}API-sleutel
Zoeken & analyse

Passtatistieken ophalen

Haal geaggregeerde uitgifte-, activatie-, wallet-installatie- en verzilveringsstatistieken op voor een specifiek passjabloon.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
templateIdstring (UUID)
Vereist

UUID van het doelsjabloon.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Queryparameters2 optioneel

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyAPI-sleutel
Zoeken & analyse

Passtatusgeschiedenis ophalen

Haal de chronologische auditgeschiedenis op van statuswijzigingen, punt-/saldoupdates, scans en ongeldigverklaringen van een pas.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Pass UUID.

Voorbeeld: b1d972dc-eccf-4f87-ab21-25939d9213d8
Queryparameters1 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/exportAPI-sleutel
Zoeken & analyse

Passen exporteren naar CSV

Stream een UTF-8 CSV-export (text/csv; charset=utf-8) van geselecteerde pasinstanties op basis van pas-ID.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met 1 tot 2.000 pas-UUID's en het exportformaat.

Aanvraagtekst2 vereist
passIdsstring[] (UUID v4)
Vereist

Array van 1 tot 2.000 pas-UUID's om op te nemen in de CSV-export.

Voorbeeld: ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Vereist

Uitvoerformaat voor export ('csv').

Voorbeeld: csv

Antwoordstatuscodes

Pasdistributie

4 eindpunten
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisAPI-sleutel
Pasdistributie

Pasbron-URL's ophalen

Haal directe download- en distributie-URL's op voor een pas, inclusief gehoste PassFlow-pagina, .pkpass, Google Wallet-JWT en QR-code.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Pass UUID.

Voorbeeld: b1d972dc-eccf-4f87-ab21-25939d9213d8

Antwoordstatuscodes

GEThttps://api.passinstance.com/d/{slug}/infoOpenbaar
Pasdistributie

Gebrandete downloadpagina ophalen

Haal een openbare gebrandete pas-downloadpagina op via slug (zonder prefix GET /d/{slug}/info). Gebruik voor geauthenticeerd beheer GET /api/v1/download-pages/slug/{slug}.

Padparameters1 vereist
slugstring
Vereist

Unieke vanity-slug van de gehoste downloadpagina.

Voorbeeld: acme-vip-2026
Queryparameters2 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadAPI-sleutel
Pasdistributie

Pasdownload inschakelen

Heractiveer of ontgrendel de downloadlink van een pas wanneer het sjabloon herhaalde downloads blokkeert.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de pas waarvan de download moet worden ontgrendeld.

Voorbeeld: b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Aanvraagtekst1 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailAPI-sleutel
Pasdistributie

Pas per e-mail verzenden

Stuur een transactionele e-mail naar de pashouder met de directe installatielink voor Apple Wallet en Google Wallet.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de pas die per e-mail moet worden verzonden.

Voorbeeld: b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Aanvraagtekst4 optioneel

Antwoordstatuscodes

Pushmeldingen

2 eindpunten
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsAPI-sleutel
Pushmeldingen

Vergrendelscherm-melding verzenden

Stuur direct een pushmelding op het vergrendelscherm naar een geïnstalleerde Apple Wallet- (.pkpass) of Google Wallet-pas. Gebruik voor geplande verzendingen of koptekstaanpassing POST /api/v1/push-notifications/passes/{id}.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idUUID
Vereist

Unieke pasinstantie-UUID die de melding moet ontvangen.

Voorbeeld: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Verzoekpayload met berichttekst en optionele kopteksttitel.

Aanvraagtekst1 vereist • 1 optioneel
messagestring
Vereist

Tekstbericht dat op het vergrendelscherm van de gebruiker wordt weergegeven.

Voorbeeld: Your reward points have been updated! You now have 250 points.

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsAPI-sleutel
Pushmeldingen

Bulk-pushmeldingen verzenden

Stuur gelijktijdig een vergrendelscherm-pushmelding naar een geselecteerde lijst van pas-ID's via APNs en Google Wallet.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Aanvraagtekst2 vereist
listOfPassesstring[] (UUID)
Vereist

Array van 1 tot 500 pas-UUID's.

Voorbeeld: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Vereist

Vergrendelscherm-meldingstekst (ondersteunt dynamische variabelen zoals {holderName}).

Voorbeeld: Hi {holderName}, you unlocked a new reward!

Antwoordstatuscodes

Bundelbeheer

4 eindpunten
POSThttps://api.passinstance.com/api/v1/bundles/upsertAPI-sleutel
Bundelbeheer

Pasbundel aanmaken of bijwerken

Maak een multi-pasbundel (.pkpasses) aan of werk deze bij waarmee gebruikers meerdere gerelateerde passen in één tik installeren.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Array of pass UUIDs (up to 10) and optional existing bundleId.

Aanvraagtekst1 vereist • 1 optioneel
passesstring[] (UUID)
Vereist

Array van 1 tot 10 pas-UUID's om te bundelen.

Voorbeeld: ["b1d972dc-eccf-4f87-ab21-25939d9213d8", "c2e083ed-fddf-4a98-bc32-36040e0324e9"]

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/bundles/{id}/passesAPI-sleutel
Bundelbeheer

Passen in bundel weergeven

Toon alle afzonderlijke passen die momenteel aan een pasbundel zijn gekoppeld, inclusief status en serienummers.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de pasbundel.

Voorbeeld: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
Queryparameters3 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/bundles/{id}/voidAPI-sleutel
Bundelbeheer

Bundelpassen ongeldig maken

Maak alle passen in een pasbundel in één enkele bewerking ongeldig of heractiveer ze.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de pasbundel.

Voorbeeld: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Confirmation flag and optional audit reason for voiding all passes in the bundle.

Aanvraagtekst1 vereist • 1 optioneel
voidedboolean
Vereist

Moet op true worden ingesteld om alle passen in de bundel ongeldig te maken.

Voorbeeld: true

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/bundles/{id}API-sleutel
Bundelbeheer

Pasbundel verwijderen

Verwijder een pasbundelgroepering uit uw workspace.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de te verwijderen pasbundel.

Voorbeeld: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Antwoordstatuscodes

Beveiliging

Overzicht — Hoe pasvalidatie werkt

Elke barcode- of NFC-scan doorloopt een deterministische validatiepijplijn van 14 regels (status, vervaldatum, tijdvensters, geofencing, mechanica, snelheidslimieten, anti-replay) met optionele cryptografische nonces en offline datasetsynchronisatie.

Anti-replay Nonce

POST /api/v1/scans/prepare geeft een kortlevende cryptografische anti-replay nonce uit gekoppeld aan de barcode

14-regels pijplijn

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Offline dataset-sync

GET /api/v1/scans/offline-dataset biedt cursor-gepagineerde snapshots voor offline terminals

Scannersleutel koppelen

POST /api/v1/scanner-keys/from-link wisselt een koppelingstoken + pincode in voor een x-scanner-key

Scannerconfiguratie

3 eindpunten
GEThttps://api.passinstance.com/api/v1/validation/configsAPI-sleutel
Scannerconfiguratie

Scannerconfiguraties weergeven

Toon alle geconfigureerde scannerprofielen (mobiele app, webscanner, kassa) en hun sjabloonmachtigingen in uw workspace.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters2 optioneel

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}API-sleutel
Scannerconfiguratie

Scannerconfiguratie ophalen

Haal de details op van één scannerconfiguratie, inclusief toegestane sjablonen, bericht na scan en validatieregels.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de scannerconfiguratie.

Voorbeeld: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/validation/configsAPI-sleutel
Scannerconfiguratie

Scannerconfiguratie aanmaken

Maak een nieuw scannerconfiguratieprofiel aan met gekoppelde sjablonen, standaard scanactie en bevestigingsbericht.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Aanvraagtekst2 vereist • 2 optioneel
namestring
Vereist

Leesbare naam voor de scannerconfiguratie.

Voorbeeld: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Vereist

Sjabloon-UUID's die onder dit profiel mogen worden gevalideerd.

Voorbeeld: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Antwoordstatuscodes

Scanoperaties

4 eindpunten
GEThttps://api.passinstance.com/api/v1/validation/scansAPI-sleutel
Scanoperaties

Scanrecords weergeven

Haal het gepagineerde auditlogboek van passcans op, gefilterd op sjabloon, pas-ID, scannerconfiguratie, beslissing en datumbereik.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters3 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/scansScannersleutel
Scanoperaties

Barcode- / NFC-scan verwerken

Valideer een optische streepjescode, QR-code of Apple VAS / Google Smart Tap NFC-scan vanaf een terminal of mobiele scanner via de 14-regels validatie-engine.

Headers (kopteksten)2 vereist • 2 optioneel
x-scanner-keystring
Vereist

Gekoppelde scannerconfiguratiesleutel aangemaakt in het Dashboard of via een koppelingslink.

Voorbeeld: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json

Verzoekpayload met gescande streepjescode, optionele anti-replay nonce, kanaal-/protocolmetadata en operatorcontext.

Aanvraagtekst1 vereist • 8 optioneel
scannedBarcodeValuestring
Vereist

De ruwe tekenreeks gelezen van QR-code, PDF417, CODE128, AZTEC of NFC-tap.

Voorbeeld: PI-8891-JD-VIP

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/scans/prepareScannersleutel
Scanoperaties

Anti-replay scan-nonce voorbereiden

Geef een kortlevende cryptografische anti-replay nonce gebonden aan een streepjescode uit vóór het uitvoeren van POST /api/v1/scans.

Headers (kopteksten)1 vereist
x-scanner-keystring
Vereist

Gekoppelde scannerconfiguratiesleutel aangemaakt in het Dashboard of via een koppelingslink.

Voorbeeld: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Verzoekpayload met de gescande streepjescodewaarde om de cryptografische nonce aan te koppelen.

Aanvraagtekst1 vereist
scannedBarcodeValuestring
Vereist

Streepjescode- of NFC-tokenreeks waaraan de anti-replay nonce wordt gekoppeld.

Voorbeeld: PI-8891-JD-VIP

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetScannersleutel
Scanoperaties

Offline scannerdataset ophalen

Download een cursor-gepagineerde pas-snapshotdataset binnen het bereik van de x-scanner-key voor lokale offline validatie wanneer de netwerkverbinding wegvalt.

Headers (kopteksten)1 vereist
x-scanner-keystring
Vereist

Gekoppelde scannerconfiguratiesleutel aangemaakt in het Dashboard of via een koppelingslink.

Voorbeeld: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Queryparameters3 optioneel

Antwoordstatuscodes

Overzicht & eindpunten

4 eindpunten
Webhooks

Webhooks-overzicht & handtekeningverificatie

Verifieer X-Webhook-Signature als HMAC-SHA256 van de exacte onbewerkte aanvraaginhoud met uw abonnementsgeheim. Vergelijk in constante tijd en verwerk gebeurtenissen idempotent.

Handtekening-header
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Tijdstempel-header
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Replaybescherming

Controleer of X-Webhook-Id overeenkomt met de ondertekende eventId, dedupliceer gebeurtenissen en valideer de ondertekende tijdstempel volgens uw replaybeleid.

Ondersteunde gebeurtenissen

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Verwacht antwoord

Retourneer HTTP 200 OK binnen 5.000 ms om ontvangst te bevestigen

Openbare verificatiesleutel

GET /api/v1/webhooks/public-key retourneert de actieve openbare sleutel voor handtekeningverificatie

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-sleutel
Overzicht & eindpunten

Webhook-abonnement aanmaken

Registreer een HTTPS-eindpunt om HMAC-ondertekende realtime gebeurtenismeldingen te ontvangen voor pasuitgifte, updates, scans en verwijderingen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met doel-HTTPS-URL en lijst met webhook-gebeurtenistypen-items.

Aanvraagtekst2 vereist • 5 optioneel
urlstring (HTTPS URL)
Vereist

Uw servereindpunt-URL (moet beginnen met https://, max. 2048 tekens).

Voorbeeld: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Vereist

webhook-gebeurtenistypen-waarden: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Voorbeeld: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}API-sleutel
Overzicht & eindpunten

Afmelden voor Webhook

Verwijder een actief webhook-abonnement op basis van ID en stop toekomstige gebeurtenisafleveringen naar dat eindpunt.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van het te verwijderen webhook-abonnement.

Voorbeeld: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-sleutel
Overzicht & eindpunten

Webhook-abonnementen weergeven

Haal alle actieve webhook-abonnementen op die voor uw klantwerkruimte zijn geregistreerd.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyOpenbaar
Overzicht & eindpunten

Openbare Webhook-handtekeningsleutel ophalen

Haal de actieve openbare PEM-sleutel van Passinstance op om uitgaande webhook-handtekeningen cryptografisch te verifiëren.

Antwoordstatuscodes

Pull-gebaseerde webhooks

2 eindpunten
Webhooks

Hoe Pull-webhooks werken & beperkingen

Ontvang realtime pas- en scangebeurtenissen via uitgaande HMAC-SHA256 Push-webhooks (met exponentiële backoff en circuit breakers) of inkomende Pull-webhookpolling voor afgeschermde netwerken, plus no-code Workflows.

Push-webhook veerkracht

5 pogingen met jittered exponentiële backoff; circuit breaker opent na 10 opeenvolgende fouten

Pull-webhook polling

GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge voor privénetwerken

Workflow-triggers

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Workflow-acties

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadAPI-sleutel
Pull-gebaseerde webhooks

Wachtende pull-webhookgebeurtenissen ophalen

Haal openstaande webhook-payloads op via uitgaande HTTPS GET voor door firewall afgeschermde of privénetwerken zonder inkomende poorten te openen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters3 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeAPI-sleutel
Pull-gebaseerde webhooks

Pull-webhookgebeurtenissen bevestigen

Bevestig verwerkte pull-webhookpayloads tot een opgegeven payload-ID zodat ze als afgeleverd worden gemarkeerd en uit de wachtrij worden verwijderd.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met de laatst verwerkte payload-ID (upTo).

Aanvraagtekst1 vereist • 1 optioneel
upTostring (UUID)
Vereist

Laatst verwerkte webhook-payload-ID; alle gebeurtenissen tot en met deze ID worden bevestigd.

Voorbeeld: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Antwoordstatuscodes

Webhook-gebeurtenissen

4 gidsen
Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Sjabloongebeurtenissen (Template Events)

Uitgaande HTTP POST-webhookmeldingen wanneer een passjabloon wordt aangemaakt, bijgewerkt, gepubliceerd of verwijderd.

Sjabloon aangemaakt
POST
TEMPLATE_CREATED

Verzonden wanneer een nieuw passjabloon wordt aangemaakt

Sjabloon bijgewerkt
POST
TEMPLATE_UPDATED

Verzonden wanneer sjabloonvelden, lay-out of mechanieken worden gewijzigd

Sjabloon gepubliceerd
POST
TEMPLATE_PUBLISHED

Verzonden wanneer een concept wordt gepubliceerd naar actieve passen

Sjabloon verwijderd
POST
TEMPLATE_DELETED

Verzonden wanneer sjabloonverwijdering en wallet-intrekking starten

Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Pasgebeurtenissen (Pass Events)

Uitgaande HTTP POST-webhookmeldingen voor elke fase van de paslevenscyclus, van uitgifte tot verwijdering van het apparaat.

Pas aangemaakt
POST
PASS_CREATED

Direct verzonden wanneer een nieuwe pas wordt uitgegeven via de REST API of PassFlow

Pas bijgewerkt
POST
PASS_UPDATED

Verzonden wanneer pasattributen, spaarpunten, niveau of saldo wijzigen

Pas ongeldig verklaard
POST
PASS_VOIDED

Verzonden wanneer een pas ongeldig wordt gemaakt in Apple Wallet & Google Wallet

Eerste pasdownload
POST
PASS_FIRST_DOWNLOAD

Verzonden de eerste keer dat een klant de pas claimt of downloadt

Pas gedownload
POST
PASS_DOWNLOADED

Verzonden bij elke volgende download van het paspakket of Google Wallet-link

Pas verwijderd van apparaat
POST
PASS_REMOVED

Verzonden wanneer de klant de pas verwijdert uit Apple Wallet of Google Wallet

Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Scangebeurtenissen (Scan Events)

Uitgaande HTTP POST-webhookmeldingen in realtime telkens wanneer een pasbarcode of NFC-pas wordt gescand en gevalideerd.

Passcan aangemaakt
POST
APP_SCAN_CREATED

Verzonden wanneer POST /api/v1/scans of een scanner een scan registreert

Scanresultaat-metadata

Bevat passId, serialNumber, templateId, configId, validatiebeslissing en saldowijziging

Aflevergarantie

At-least-once HTTPS POST-aflevering met X-Webhook-Id en X-Webhook-Signature headers

Pull-wachtrijcompatibiliteit

Ook beschikbaar via GET /api/v1/webhook-payload voor kassasystemen achter een firewall

Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Berichtgebeurtenissen & statusreferentie (Message Events)

Uitgaande HTTP POST-webhookmeldingen en afleverstatuscodes voor wallet-pushmeldingen, e-mails en sms-berichten.

Bericht verzonden
POST
MESSAGE_SENTNOTIFICATION_SENT

Verzonden wanneer een pasbericht of pushmelding wordt verstuurd

Aflevering mislukt
POST
MESSAGE_FAILED

Verzonden wanneer een uitgaande e-mail, sms of pushmelding mislukt

Berichtstatusreferentie

QUEUED -> SENT -> DELIVERED (of FAILED / BOUNCED met diagnostische code)

Idempotente correlatie

Koppel eventId en passId in uw webhook-consumer om herhaalde afleveringen te ontdubbelen

End-to-end Platform- & API-documentatie

Passinstance Helpcentrum: Bekijk alle 10 onderwerpen & 94 gidsen

Verken stapsgewijze handleidingen, workflow-architectuurdiagrammen, JSON-payloadschema's en probleemoplossing voor elk domein.

Helpcentrum openen

Alles wat u nodig hebt om vlot te starten met Passinstance.