Skip to content
Help Center Guide · Developer Tools
2 min readVerified 2026-11-16

Integration Utilities

Use SDK tokens, parameter-driven Dynamic Wallet URLs, AI .pkpass prompt workflows, and OpenAPI schema discovery.

In This Guide

Overview

To accelerate backend integration across Node.js/TypeScript, Python, PHP, and shell environments — alongside Dashboard developer utilities at /settings/workspace/integrations/link-generator, /settings/workspace/developer/embed-sdk, /settings/workspace/developer/sdks, /settings/workspace/developer/query-helper, and /settings/workspace/developer/qr-generator — this guide provides production patterns for idempotent pass upserts (POST /api/v1/passes/upsert-by-external-id), parameterized download links (PARAMETERIZED_PASS_LINK / CREATE_PASS_URL), cursor-based pagination, and constant-time HMAC-SHA256 webhook verification.

Important: Upsert by (templateId, externalId) to synchronize a business record. Read the returned pass from data.pass and the outcome from data.action (CREATED or UPDATED). For POST /api/v1/passes, send an Idempotency-Key header when retries must reuse the same creation request. Upsert does not consume that header.

Idempotent Upsert & Cursor Pagination Flow

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
IDEMPOTENT UPSERT & CURSOR PAGINATION PATTERN
PARTICIPATING SYSTEM ACTORS
P1 Your Backend Application
P2 Passinstance REST API (/api/v1)
STEP 1 REQUEST / ACTION POST/passes/upsert-by-external-id
›
{ templateId, externalId, attributes }
›
Match (templateId + externalId)
›
Create if new OR Patch & Push if existing
STEP 2 RESPONSE 200 OK data: { pass, action }
STEP 3 REQUEST / ACTION GET/scans/offline-dataset
›
?limit=250
STEP 4 RESPONSE 200 OK { data: { passes, nextCursor: "c_1" } }
STEP 5 REQUEST / ACTION GET/scans/offline-dataset
›
?limit=250&cursor=c_1&snapshotAt=...
STEP 6 RESPONSE 200 OK { data: { passes, hasMore: false } }

Multi-Language Production Code Patterns

1. Node.js / TypeScript: Idempotent Pass Upsert Helper

TYPESCRIPT
interface IUpsertPassPayload {
  templateId: string;
  externalId: string;
  attributes: Record<string, string | number | boolean>;
  expirationDate?: string;
}

export async function upsertWalletPass(payload: IUpsertPassPayload) {
  const response = await fetch('https://api.passinstance.com/api/v1/passes/upsert-by-external-id', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.PASSINSTANCE_API_KEY ?? '',
    },
    body: JSON.stringify(payload),
  });

  const body = await response.json();
  if (!response.ok || !body.success) {
    throw new Error(`Passinstance API error [${body.errorCode ?? response.status}]: ${body.message}`);
  }
  return body.data.pass as { id: string; serialNumber: string; externalId?: string; passAccessUrl: string };
}

2. Python: Idempotent Upsert & HMAC Webhook Verifier

PYTHON
import hmac
import hashlib
import os
import requests

API_BASE_URL = "https://api.passinstance.com/api/v1"
API_KEY = os.environ["PASSINSTANCE_API_KEY"]

def upsert_pass_by_external_id(template_id: str, external_id: str, attributes: dict) -> dict:
    response = requests.post(
        f"{API_BASE_URL}/passes/upsert-by-external-id",
        headers={
            "x-api-key": API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "templateId": template_id,
            "externalId": external_id,
            "attributes": attributes,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()["data"]["pass"]

def verify_webhook_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False
    digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"
    return hmac.compare_digest(signature_header, expected)

3. PHP: Issuing & Updating a Pass + Verifying Webhooks

PHP
<?php
function upsertPassinstancePass(string $templateId, string $externalId, array $attributes): array {
    $payload = json_encode([
        'templateId' => $templateId,
        'externalId' => $externalId,
        'attributes' => $attributes,
    ], JSON_THROW_ON_ERROR);

    $ch = curl_init('https://api.passinstance.com/api/v1/passes/upsert-by-external-id');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . getenv('PASSINSTANCE_API_KEY'),
        ],
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    return json_decode($raw, true, 512, JSON_THROW_ON_ERROR)['data']['pass'];
}

function verifyPassinstanceWebhook(string $rawBody, string $signatureHeader, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

4. cURL: Quick CLI Reference

BASH
curl -X POST "https://api.passinstance.com/api/v1/passes/upsert-by-external-id" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1" \
  -d '{
    "templateId": "6f2c5130-2f2a-4f40-8c68-f7192c5b4f43",
    "externalId": "cust_9012",
    "attributes": {
      "memberName": "Clara Oswald",
      "points": 1250,
      "tier": "GOLD"
    }
  }'

Offline Scanner Snapshot Pagination

GET /api/v1/scans/offline-dataset requires x-scanner-key and returns the scanner snapshot inside a success / data / metadata response. Keep the same snapshotAt across all pages.

Parameter / Response FieldTypeDescription
limitnumberNumber of passes per page (default 500, maximum 1000).
cursorstringUse the previous response's data.nextCursor; omit on the first request.
snapshotAtstring (ISO 8601)Reuse data.snapshotAt from the first response as the snapshot upper bound for later pages.
data.passesArrayPass snapshots scoped to the scanner configuration.
data.hasMorebooleanContinue fetching pages while this value is true.
data.nextCursorstringUse as cursor when data.hasMore is true; omitted on the final page.

Explore live OpenAPI schemas at /docs, test with our Bruno collection in Testing & Debugging, or design pass templates with AI in Create Your First Wallet Pass.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.