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

Testing & Debugging

Troubleshoot API payloads using webhook delivery logs, standardized API error codes, and test passes on the Free plan.

In This Guide

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 .pkpass and 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-screen changeMessage rendering.

Integration Verification & Debugging Workflow

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SANDBOX TESTING, IDEMPOTENCY & WEBHOOK DEBUGGING
PARTICIPATING SYSTEM ACTORS
P1 Developer / Bruno CLI
P2 Passinstance API (pi_test_...)
P3 Diagnostic & Audit Surface
STEP 1 REQUEST / ACTION POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
Validate DTO against Template
›
Body: externalId,
›
Sign .pkpass (bundleId) & JWT
›
idempotencyKey
›
emit pass_created webhook
STEP 2 RESPONSE 201 Created { requestId }
STEP 3 REQUEST / ACTION Replay POST/api/v1/scans
›
Header: x-idempotency-key: k_01
STEP 4 RESPONSE 200 OK (Idempotent Cache Hit)
STEP 5 REQUEST / ACTION Inspect Health & Logs
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Sandbox Keys (pi_test_), Dashboard Tools & Sample Passes

  • Sandbox API Keys (pi_test_<secret>): Provisioned via POST /api/v1/api-keys with "environment": "test" (API_KEY_ENVIRONMENT_VALUES) in sandbox workspaces. They exercise validation, bundleId signing, 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, and GET /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 AreaCovered Flows & Assertions
Auth & API KeysKey creation (pi_test_), API_KEY_SCOPE_VALUES enforcement, rotation, and usage telemetry.
Templates & MechanicsTemplate CRUD, tier asset hydration, stamp cards, and stored-value configuration.
Passes & DistributionSingle issuance (externalId, idempotencyKey), upsert-by-external-id, smart download links (/d/:slug, /s/:token), and POST /api/v1/passes/export.
Scanner RuntimePOST /api/v1/scans/prepare nonces, POST /api/v1/scans 14-rule evaluation, /api/v1/scanner-keys/verify, and offline dataset sync.
BillingSubscription preview, plan changes, Stripe SetupIntents, and PDF invoice downloads.
Webhooks InboxPush webhook registration (/api/v1/webhooks/subscriptions), HMAC verification tests, and Pull Webhook queue polling (/webhook-payload).
IntegrationsZapier/Make OAuth endpoints (/api/v1/me, /api/v1/webhook-subscriptions) and Shopware/Shopify hooks.
AnalyticsMulti-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: Supply idempotencyKey in request payload (or externalId with POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans: Send header x-idempotency-key: test-scan-retry-001 (Idempotency Engine); replay returns the identical request payload, queryable anytime at GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use: Send header Idempotency-Key (matching optional body idempotencyKey).
  • POST /v1/pos/redeem & POST /api/v1/reader/redeem: Send idempotencyKey in 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:

JSON
{
  "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.js await req.text(), FastAPI await request.body()) reads the exact raw byte stream before JSON deserialization.
  • Inspect Circuit Breaker State: Remember that 10 consecutive non-2xx responses 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 run POST /api/v1/webhooks/subscriptions/:id/test to reset the circuit.

For production code snippets across Node.js, Python, PHP, and cURL, see Integration Utilities.

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.