Overview
Before rolling out a wallet pass integration to production traffic, you can verify every API call, scan rule, idempotency lock, and webhook signature using Passinstance sandbox keys (pi_test_...), the Dashboard Developer Console (/settings/workspace/developer/*), and our pre-built Bruno API Collection (under docs/bruno/).
Important: Always test pass issuance (
bundleId-signed.pkpassand Google Wallet Save link) and dynamic updates on at least one physical iOS device (Apple Wallet) and one Android device (Google Wallet) before launch. Desktop previews validate layout structure, but physical device installation verifies real APNs push latency and lock-screenchangeMessagerendering.
Integration Verification & Debugging Workflow
1. Sandbox Keys (pi_test_), Dashboard Tools & Sample Passes
-
Sandbox API Keys (
pi_test_<secret>): Provisioned viaPOST /api/v1/api-keyswith"environment": "test"(API_KEY_ENVIRONMENT_VALUES) in sandbox workspaces. They exercise validation,bundleIdsigning, and push queues without consuming production quotas. -
Dashboard Developer Diagnostics: Inspect real-time request logs, Bull background queues, system health, and API payloads directly inside
/settings/workspace/developer/logs,/settings/workspace/developer/jobs,/settings/workspace/developer/system-health, and/settings/workspace/developer/query-helper. -
Health Endpoints (Prefix-Free): Poll
GET /health,GET /health/liveness,GET /health/readiness,GET /health/detailed, andGET /health/circuit-breakers(all mounted without/api/v1).
2. Bruno API Collection
Passinstance maintains an official Bruno API Collection in docs/bruno/ with pre-configured requests across domain folders, including:
| Bruno Domain Area | Covered Flows & Assertions |
|---|---|
Auth & API Keys | Key creation (pi_test_), API_KEY_SCOPE_VALUES enforcement, rotation, and usage telemetry. |
Templates & Mechanics | Template CRUD, tier asset hydration, stamp cards, and stored-value configuration. |
Passes & Distribution | Single issuance (externalId, idempotencyKey), upsert-by-external-id, smart download links (/d/:slug, /s/:token), and POST /api/v1/passes/export. |
Scanner Runtime | POST /api/v1/scans/prepare nonces, POST /api/v1/scans 14-rule evaluation, /api/v1/scanner-keys/verify, and offline dataset sync. |
Billing | Subscription preview, plan changes, Stripe SetupIntents, and PDF invoice downloads. |
Webhooks Inbox | Push webhook registration (/api/v1/webhooks/subscriptions), HMAC verification tests, and Pull Webhook queue polling (/webhook-payload). |
Integrations | Zapier/Make OAuth endpoints (/api/v1/me, /api/v1/webhook-subscriptions) and Shopware/Shopify hooks. |
Analytics | Multi-series time-range queries (passes/overview, wallet-installations), and CSV exports. |
3. Testing Idempotency (x-idempotency-key, Idempotency-Key & idempotencyKey)
Mutating endpoints protect against network retries through explicit idempotency contracts:
-
POST /api/v1/passes: SupplyidempotencyKeyinrequest payload(orexternalIdwithPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Send headerx-idempotency-key: test-scan-retry-001(Idempotency Engine); replay returns the identicalrequest payload, queryable anytime atGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Send headerIdempotency-Key(matching optional bodyidempotencyKey). -
POST /v1/pos/redeem&POST /api/v1/reader/redeem: SendidempotencyKeyin the JSON request body (request payload/request payload).
4. Standard Error Envelope
When a request fails validation or rate limiting, API Error Handler returns a structured error payload with a correlation requestId and machine-readable errorCode:
{
"success": false,
"error": "BAD_REQUEST",
"messageKey": "api.errors.invalidInput",
"message": "Invalid input provided: attribute 'memberName' is required by template",
"statusCode": 400,
"timestamp": "2026-11-16T10:20:00.000Z",
"path": "/api/v1/passes",
"requestId": "req_8f192b0e4c1a",
"code": "VALIDATION_ERROR",
"errorCode": "MISSING_REQUIRED_TEMPLATE_ATTRIBUTE",
"details": [
{
"field": "attributes.memberName",
"issue": "Required string attribute is missing"
}
]
}
5. Debugging Webhook Signatures & Circuit Breakers
If your webhook endpoint is not receiving events or fails HMAC validation:
-
Check Raw Body Parsing: Ensure your web framework (Express
express.raw({ type: 'application/json' }), Next.jsawait req.text(), FastAPIawait request.body()) reads the exact raw byte stream before JSON deserialization. -
Inspect Circuit Breaker State: Remember that 10 consecutive non-
2xxresponses or timeouts (10s) trip the endpoint circuit breaker (CIRCUIT_BREAKER_THRESHOLD = 10) for a 30-minute cooldown (CIRCUIT_BREAKER_COOLDOWN_MS). Fix the receiver bug and runPOST /api/v1/webhooks/subscriptions/:id/testto reset the circuit.
For production code snippets across Node.js, Python, PHP, and cURL, see Integration Utilities.
