Skip to main content
Use this checklist to test your TapAce Node.js integration in small steps. Record the SDK version and request ID when investigating an API response.

​
Installation or import fails

Check Node.js is version 20 or newer and your application supports ES modules. For a JavaScript entry file, use .mjs or an appropriate "type": "module" package setting. The package name is @tapace/node, and version 0.1.0 is available from the public npm registry. If a lookup returns 404 immediately after a release, npm may still be processing it or updating package metadata. Wait briefly, then retry with npm view @tapace/node@0.1.0 version --registry=https://registry.npmjs.org/ --prefer-online. A registry 404 is separate from a TapAce API authentication error. See installation instructions. CommonJS applications can load the ES module with dynamic import() inside an async function. Use the TypeScript NodeNext module and resolution settings when checking a Node ESM application.

​
Webhook verification fails

Verify the exact raw bytes before JSON middleware changes them. Check the signing secret separately from the API key, use decimal integer timestamp seconds and keep the server clock synchronized. Malformed base64, extra padding, modified bytes and out-of-window timestamps are rejected. The default tolerance is 300 seconds. See Webhook verification.

​
The constructor rejects my key

The SDK accepts tapace_test_ and tapace_live_ prefixes. Check the server environment variable exists. A key with a valid prefix can still be invalid or revoked; use tapace.me.retrieve() to verify it. Do not include API keys or webhook signing secrets in screenshots, logs or support messages.

​
Issuance returns 400 or 422

Retrieve the template and inspect requiredFields and requiredActions. Match the actual per-pass keys, rather than the labels shown on the pass. A 400 can indicate missing fields, unsupported wallets, archived templates or invalid values. A 422 can indicate signing setup is incomplete. Check Test and live and the error’s code, issues and requestId. appleDownloadUrl or googleSaveUrl may be null when that wallet is unavailable, not enabled for the pass, cannot be signed or the pass is voided. Inspect tapace.passes.retrieve(id) for wallet readiness, and use the hosted distributionUrl when appropriate.

​
The API succeeded but the phone has not changed

Issuance requires the holder to add the pass. Updates and notifications involve asynchronous delivery. Retrieve the returned update, notification or deployment and inspect its progress rather than repeatedly creating a new operation. For a pass update, update can be null when only metadata changed or no wallet-visible change occurred. See Update passes. A silent update has no alert banner. For a message, inspect Message for you on the pass’s details/back. A successful Apple delivery status confirms the push signal was accepted; confirm the changed field or message separately on the device. Check that Automatic Updates is enabled, and try refreshing the pass. If an older installation remains stale while a newly downloaded pass has the correct values, collect the pass ID, update ID and approximate update time for support. A known recovery issue can affect older Apple installations after service data is reset. Re-adding a pass can refresh its installation state, but is not a permanent fix for that issue. Do not issue duplicate passes or loyalty credits to work around a display problem.

​
A webhook arrives more than once

Repeated deliveries are expected, including when you click Resend in the dashboard. Verify every delivery, then deduplicate with the event’s id in persistent storage. The SDK does not store processed event IDs. Installing the same pass again creates a new lifecycle event and must not be discarded simply because its pass ID matches a previous event.

​
A retry keeps returning a conflict

Handle TapAceIdempotencyError.reason:
  • in_flight: retry the original request later, with the same key and body.
  • key_reused: investigate why the same operation key now has different request details.
A general TapAceConflictError can also indicate a stale template revision or another conflict. The SDK does not automatically retry every 409 response. Retrieve current state before deciding what to do.

​
A template update fails

Always send the current expectedRevision; the SDK type requires it. When sending issuePlatforms, include both apple and google booleans. See Resource methods.

​
SDK and API compatibility

Use the documented SDK build and check the following behavior when upgrading an integration:

​
Suggested test order

  1. Verify installation/import and check a test key with me.retrieve().
  2. List and retrieve a template; inspect required fields.
  3. Issue a pass with a stable key; repeat the exact call and compare IDs.
  4. Open its hosted delivery page and add the pass on a test phone.
  5. Update a per-pass field and inspect its update record.
  6. Test stamps or points with a new saved operation ID for each intended change.
  7. Test notification scheduling and cancellation with test passes.
  8. Verify a signed webhook and reject a changed body.
  9. Test deployments, event changes and lifecycle operations after their compatibility checks.
Template and event changes can affect shared resources across environments. Use a dedicated test template, and review its use before changing it. See Errors and retries for recovery patterns.