Skip to content
REST API Reference & SDKs

Passinstance Developer Documentation

Build high-volume Apple Wallet (.pkpass) and Google Wallet integrations. Issue, update, scan, and broadcast real-time lockscreen notifications via production-grade REST APIs.

Get API Keys
All API ReferencePassesTemplatesScanner & DevicesPush & DeliveryWebhooksBatch Operations
30-Second Quickstart

Issue your first Wallet pass in 30 seconds

Create, cryptographically sign, and distribute Apple Wallet & Google Wallet passes with one API call.

Get API Key
POST/api/v1/passes
curl -X POST https://api.passinstance.com/api/v1/passes \
  -H "Authorization: Bearer $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_loyalty_artisan",
    "serialNumber": "MEMBER-88219",
    "recipient": {
      "name": "Alex Morgan",
      "email": "alex@customer.com"
    },
    "customFields": {
      "stamps": 3,
      "tier": "Silver"
    }
  }'
1. Issue
Bearer token
2. Distribute
POST /api/v1/passes
3. Update
passAccessUrl
4. Redeem
POST /api/v1/scans
Overview

Getting Started & Base URLs

The Passinstance API enables developers to dynamically issue, distribute, update, and validate digital passes for Apple Wallet (iOS) and Google Wallet (Android). All API requests must be made over HTTPS and return a standardized ApiResponseDto envelope with machine-readable status codes.

Production Base URL
https://api.passinstance.com/api/v1
Staging Sandbox Base URL
https://staging-api.passinstance.com/api/v1
Request & Response Format
application/json (UTF-8) with ApiResponseDto<T> envelope
Backend Server Timezone
Europe/Berlin (ISO 8601 timestamps)
Core Concepts

Architecture & Pass Lifecycle

Pass management follows a 5-stage lifecycle: 1. Template (visual blueprint) → 2. Pass (cryptographically signed record) → 3. Distribution (secure passAccessUrl) → 4. Wallet Registration (device enrolls with APNs / Google Push) → 5. Live Updates (real-time lockscreen notifications).

1. Template
Master layout, barcode type, branding colors, and schema fields
2. Pass Instance
Signed digital pass containing member data and unique serial number
3. Distribution (passAccessUrl)
HTTPS web landing page for adding pass into Apple or Google Wallet
4. Wallet Registration
Device registers push token; pass is actively installed on device
5. Real-Time Updates
Server broadcasts background APNs / Google push on state change
Quick Start

Quick Start: 5-Minute Pass Issuance

Create your first usable pass in under 5 minutes. Set your API key header, call POST /api/v1/passes with a valid templateId, and deliver the returned passAccessUrl to your end-user.

Step 1: Set Key
export PASSINSTANCE_API_KEY="pi_test_..."
Step 2: Issue Pass
POST /api/v1/passes with templateId and serialNumber
Step 3: Get URL
Extract response.data.passAccessUrl from 201 Created payload
Step 4: Distribute
Deliver URL via SMS/Email; user taps "Add to Apple/Google Wallet"
Platform Guides

Apple Wallet vs. Google Wallet Matrix

Passinstance automatically signs .pkpass bundles for iOS and generates signed JWT objects for Google Wallet. Assets, barcodes, and lockscreen triggers adapt seamlessly across both operating systems.

Apple Wallet Signing
Cryptographic PKCS#7 signature using Apple Pass Type ID certificate
Google Wallet Issuer
Google Cloud Service Account REST JWT payload
Hero / Strip Artwork
Apple: 375×123 px (3:1) | Google: 1032×336 px (approx 3:1)
Universal Barcodes
QR Code and PDF417 supported natively on both mobile platforms
Security

Authentication & Environment Keys

All API calls require authentication via secret API keys passed in the Authorization header. Never expose secret API keys in client-side mobile apps or browser code.

Production Keys (Live)
Authorization: Bearer pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Sandbox Keys (Test)
Authorization: Bearer pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Hardware Scanner Keys
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
Security Invariant
Server-to-server calls only. Disallow frontend bundle inclusion.
Operations

Error Handling & Rate Limits

Every API response uses the canonical ApiResponseDto envelope. Client errors (4xx) should be fixed before retrying; server errors (5xx) and rate limits (429) should be retried with exponential backoff.

200 OK / 201 Created
{ "success": true, "data": { ... }, "errors": [], "statusCode": 200 }
400 Bad Request
{ "success": false, "data": null, "errors": ["Validation failed"], "statusCode": 400 }
409 Conflict
{ "success": false, "data": null, "errors": ["Serial number already exists"], "statusCode": 409 }
429 Rate Limited
100 req/sec limit. Check Retry-After response header before retrying.
Webhooks

Webhook HMAC Signature Verification

Passinstance signs all outbound webhook deliveries using HMAC-SHA256. Verify the X-Passinstance-Signature header using your subscription secret to prevent spoofing and replay attacks.

Signature Header
X-Passinstance-Signature: t=1755811200,v1=9f8e7d6c5b4a3...
Replay Window
Reject webhook deliveries with timestamps older than 5 minutes (300s)
Supported Events
PASS_CREATED, PASS_UPDATED, PASS_SCANNED, PASS_INSTALLED, PASS_UNINSTALLED
Expected Response
Return HTTP 200 OK within 5,000ms to acknowledge receipt
Resources

Official SDKs & Client Libraries

Official thin SDKs providing end-to-end TypeScript interfaces, automatic token caching, exponential backoff retries, and cryptographic webhook signature validation.

Node.js / TypeScript
npm install @passinstance/node
Python (3.9+)
pip install passinstance
PHP (8.1+)
composer require passinstance/passinstance-php