Pass Templates

Pass Templates are created from your account and customized with the pass template editor. They represent a template to create a pass from. Pass Templates have a pass template identifier that is present in the Get Passes tab for a given pass template, it takes the form of <YOUR_TEMPLATE_ID> and is required to be passed in when creating a pass.

Furthermore, pass templates allow you to define the JSON keys you will use to populate your pass upon creation.

List pass templates

Retrieves a list of all pass templates for your account, including metadata about each template such as the number of issued and installed passes.

This endpoint requires no parameters and returns an array of pass template objects.

You will get a response with an array of pass template objects. Example response:

Get a pass template

Retrieves details about a specific pass template using its template ID.

Below is the required parameter for retrieving a pass template:

• id^* string

  The pass template identifier, present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

You will get a response with a pass template object. Example response:

Create a pass template Enterprise

Programmatically provision a new pass template under your account. The created template starts empty — define its visible fields, art, and styling through the pass template editor in the dashboard before issuing passes against it.

Below is the list of acceptable params for creating a pass template. * denotes a required parameter:

• name^* string

  Human label for the template, ≤ 120 characters.

• platform^* string

  One of apple, google, or both.

• style^* string

  Pass style identifier (e.g. storeCard, eventTicket, coupon, boardingPass, generic). Must be valid for the chosen platform — when platform is both, the style must exist in the Apple and Google catalogs. See Platform Parameters for the full list.

You will get a 201 response with the created pass template object — note the id, which is the ptk_0x... identifier you will use for every subsequent pass operation:

Delete a pass template Enterprise

Permanently removes a pass template from your account. This is destructive and irreversible — issued passes attached to the template are deleted along with it, installed wallet copies stop receiving updates, and the ptk_0x... identifier becomes invalid for all future API calls.

Below is the required parameter for deleting a pass template:

• id^* string

  The pass template identifier — looks like <YOUR_TEMPLATE_ID>. Must belong to the calling account; otherwise 404 is returned.

Returns 204 No Content on success.

Create a new pass

Creating a pass allows you to create a new pass for a given pass template with given values. In addition to issuance, for an additional $0.05 you can send the pass via text message. Returns pass id (also known as a serial number), and when applicable message_status.

This creates an "Active pass" which incurs a monthly cost. Please see pricing for more info.

Below is a list of acceptable params for creating a pass. * denotes a required parameter:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• pass^* object

  The keys you have set as Visible on the Edit Pass Template page. Use the API mapping field names, not the Apple or Google property names.

• recipient ^(optional) object

  The name, message and phone number or email of the person you wish to issue this pass. The parameters here are not used to create passes, only to send them. Acceptable params are as follows:

  • name^* string

    The name of the person receiving the pass.

  • message^(optional) string

    The message sent with the pass. Use @name, @account or @url to customize the message. For example: "Hi @name, @account sent you this pass @url"

  • sms ^(optional) string

    Internationally formatted phone number to send message to, with a + in front. For example: +15613437899

  • email ^(optional) string

    RFC compliant email address to send message to. For example: support@passninja.com

You will get a response with the created pass object. Example response:

List passes

Allows you to retrieve a list of passes using its pass template identifier. This is useful for understanding the issued and installed dates as well as the current status of your pass inventory. Supports pagination and search.

Below is a list of params:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• page integer (optional)

  Page number for pagination. When provided, the response includes a meta object with pagination details. Without this parameter, all passes are returned.

• per_page integer (optional)

  Number of passes per page. Defaults to 10. Only applies when page is provided.

• search string (optional)

  Search passes by serial number. Performs a case-insensitive partial match.

You will get a response with an array of pass objects. Example response:

Get a pass

Allows you to retrieve a pass using its pass template identifier and serial number. The response uses the API mapping field names that have been defined and set to Visible in your pass template, matching the field names used by the Create, Patch, and Update methods. Note that pass status and install date information is only available in the List passes response, not in the individual Get a pass response.

Below is a list of required params for retrieving a pass:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• passId^* string

  PassId also known as a serial number. Takes on a namespaced format which looks like <SERIAL_NUMBER>

You will get a response with the pass object including all field values. Example response:

Decrypt a pass

Allows you to decrypt a pass payload using its pass template identifier and encrypted payload. This is useful when you're working with an APDU-based reader that doesn't have an onboard hardware secure module (HSM) for decryption. Contact us via the website chat if you have questions about using this.

Below is a list of required params for decrypting a pass:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• payload^* string

  Payload is a hex encoded APDUs with no spaces. It looks like this (abbreviated for presentation): 55166a97002...1ea070f0d4fe88887

Patch a pass

Allows you to partially update a pass using its pass template identifier, serial number, and new information. Unlike PUT, fields that are not provided will retain their existing values. This update will occur as soon as possible, but may not be instant - it will depend on the service of the users device.

Below is a list of required params for patching a pass:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• passId^* string

  PassId also known as a serial number. Takes on a namespaced format which looks like <SERIAL_NUMBER>

• pass^* object

  The keys you have set as visible for this template on the Edit Pass Template page. These are the API mapping field names, which do not match the property names returned by the Get a pass response. Only include the fields you want to update.

You will get a response with the updated pass object including all field values. Example response:

Note: In the example above, only member.name was updated. All other fields retained their previous values.

Update a pass

Allows you to update a pass using its pass template identifier, serial number, and new information. Fields that are not provided will revert to their pass template default values. This update will occur as soon as possible, but may not be instant - it will depend on the service of the users device.

Below is a list of required params for updating a pass:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• passId^* string

  PassId also known as a serial number. Takes on a namespaced format which looks like <SERIAL_NUMBER>

• pass^* object

  The keys you have set as visible for this template on the Edit Pass Template page. These are the API mapping field names, which do not match the property names returned by the Get a pass response.

You will get a response with the updated pass object including all field values. Example response:

Delete a pass

An irreversible action to destroy a pass using its pass template identifier and serial number. Will not remove the pass from users device, but will void the pass at the earliest possible moment and prevent additional billing events immediately.

Below is a list of required params for deleting a pass:

• passTemplate^* string

  This is the pass template identifier, it is present in the Get Passes tab for a given pass template. It looks like this: <YOUR_TEMPLATE_ID>

• passId^* string

  PassId also known as a serial number. Takes on a namespaced format which looks like <SERIAL_NUMBER>

You will get a response with the deleted pass serial number. Example response:

Webhooks Enterprise

Webhooks let your server react to pass-lifecycle events in near real time. PassNinja delivers each event as a CloudEvents 1.0 JSON envelope over HTTPS, signed with a per-subscription bearer token. Subscriptions, including their bearer secrets, are managed through the endpoints below; the entire /v1/webhooks resource requires an enterprise account with an active subscription.

• One subscription = one HTTPS endpoint + one bearer token + one event filter.
• Subscriptions can be account-wide or scoped to a single pass template.
• Deliveries retry with exponential backoff for ~24h; every attempt is recorded and queryable.
• Bearer secrets are returned once on creation and stored AES-256-GCM encrypted at rest — there is no read-back endpoint.

Event types

Event types follow the CloudEvents convention of reverse-DNS-ish dotted names. The pn.* namespace is reserved by PassNinja; do not subscribe to types outside the catalog below — subscriptions to unrecognized types are accepted but will never receive deliveries, and PassNinja may add new pn.* types in the future without prior notice.

Type names are validated against ^pn\.[a-z][a-z_]*\.[a-z][a-z_]*$ on subscription create. Anything outside the pn.* namespace is rejected with HTTP 400.

Webhook payload (CloudEvents 1.0)

Each delivery is an HTTP POST to your subscription's url with Content-Type: application/json, an Authorization: Bearer <token> header, and a JSON body in CloudEvents 1.0 structured-mode.

Envelope attributes

PassNinja sets the CloudEvents 1.0 attributes listed below. Other CE-spec attributes (subject, dataschema, data_base64) are reserved by the spec and may be added in future versions; receivers should ignore unknown top-level attributes rather than failing.

data payload (pass events)

Receiver expectations

• Verify the Authorization header matches the bearer token returned at subscription creation. Reject anything else with HTTP 401.
• Respond with any 2xx status to acknowledge. Anything else is treated as failure and triggers a retry.
• Aim to ack within 10 seconds — deliveries time out after that and are retried.
• Treat the id attribute as the dedupe key. Retries (and rare delivery duplicates) reuse the same id; pnattempt changes per attempt.
• Ignore unknown top-level attributes — the CloudEvents spec reserves room for future ones.

Create a webhook subscription

POST /v1/webhooks

Creates a subscription and returns a freshly generated bearer token. The plaintext token is included in the response only on creation; subsequent reads omit it (it's stored AES-256-GCM encrypted at rest, with no decryption endpoint exposed). Persist it on your side at this moment.

Request body

Example 201 response — note that bearer_token appears here and nowhere else:

List webhook subscriptions

GET /v1/webhooks

Returns subscriptions in the calling account, newest first. Supports query params page (default 1), per_page (default 50, max 100), and pass_template=ptk_0x... to filter by scope.

Get a webhook subscription

GET /v1/webhooks/<ID>

Same row shape as the list response. The bearer token is never included. Returns 404 if the id doesn't belong to the calling account.

Delete a webhook subscription

DELETE /v1/webhooks/<ID>

Removes the subscription and its delivery history in a single transaction. Returns 204 No Content. To pause without losing history, build subscription rotation (delete + recreate) into your tooling — there is no soft-disable endpoint today.

Inspect delivery history

GET /v1/webhooks/<ID>/results

Every delivery attempt — successful or not — writes a webhook_results row. Useful for diagnosing receiver-side outages without grepping your own logs. Same pagination params as the list endpoint.

Retry policy

• Attempts: up to 15 per delivery.
• Backoff: exponential starting at 10 seconds, capped so the full sequence spans roughly 24 hours.
• Success: any HTTP 2xx response from your endpoint.
• Timeout: requests time out after 10 seconds and count as a failure.
• Stable identity: retries reuse the same CloudEvents id and data payload; only pnattempt increments.
• After 15: the delivery is dropped and a final failure row is written. PassNinja does not auto-disable the subscription — but a chronically failing endpoint will accumulate noise in /v1/webhooks/<id>/results.

Legacy subscriptions Deprecated

Webhook subscriptions created before the CloudEvents rollout continue to receive deliveries in their original wire format — no Authorization header, no envelope, original field names — so existing receivers do not need changes:

No new legacy-format subscriptions can be created — the POST /v1/webhooks endpoint always issues bearer-authenticated CloudEvents subscriptions. To migrate an existing receiver: provision a new CloudEvents subscription pointed at your endpoint, switch the receiver to verify the bearer and parse the envelope, then delete the legacy row. The two formats can coexist during cutover.

Terminal: Simple readers

If you're using one of our reader terminals, then you may be wondering what the output stream from the terminal is. Our readers emulate a keyboard device and stream the NFC data to stdin, encoded in ASCII format.