PassNinja - API Documentation / SDKs

Overview

Getting started
SDKs / Libraries
Authentication

Passes

Templates
Create a new pass
List passes
Get a pass
Decrypt a pass
Update a pass
Delete a pass

Custom Callback URL

Webhook payload
Retries

Errors

Standard codes

Scan terminals

Simple readers

Getting started

PassNinja is a turn-key service for creating and validating NFC enabled digital passes. NFC is a contactless technology that allows phones to authenticate themselves when they get near a terminal. Our RESTful API lets developers easily integrate NFC passes into their solutions.

The PassNinja API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.

Before using the PassNinja REST API, it is important that you understand the basics of RESTful web services and JSON representations.

Throughout these docs, you'll find helpful code samples to the right of each section explanation. All code samples use our python SDK, but other SDKs exist as outlined below.

// Code Samples Appear Here

SDKs / Libraries

We maintain libraries in popular scripting languages to make it easy to build on top of PassNinja. You can find the source code for these here:

You can find the installation commands for each of these to the right.

# for python
pip install passninja

# for ruby
gem install passninja

# for node js
npm install @passninja/passninja-js

# for swift see github

# via gradle for Java
compile 'com.github.javadev:passninja:1.2'

# for c#
Install-Package passninja.dll -Version 1.0.0

# for php
composer require passninja/sdk

Authentication

Every API request must be authenticated. We use two custom HTTP headers for authentication. The first is an API key, the second is an account ID - both of these can be found in your account dashboard under pass template "send" page for a given pass in the Pass Templates tab. The API takes the format of ak_85b4d0f5f58706 and should be sent in the X-API-KEY header. The Account ID takes the format of aid_999 and should be sent in the X-ACCOUNT-ID header.

Note:
You should only send traffic over HTTPs and do your best to keep your authentication credentials private.

If you use one of our ready-made SDKs, then you only need to set your keys during initialization.


import passninja

account_id = '**your-account-id**'
api_key = '**your-api-key**'

pass_ninja_client = passninja.PassNinjaClient(
    account_id,
    api_key
)

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 key that is present in the getting started tab for a given pass template, it takes the form of ptk_0x14 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.

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.

Note:
For self-serve customers, if you send text messages you will be rate limited to a maximum of 10 requests per second. For enterprise customers, this rate limit is 100 requests per second when sending passes via text message.

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

passType^* string
This is the pass type key, it is present in the getting started tab for a given pass template. It looks like this: ptk_0x14
pass^* object
The keys for this object are defined in the pass ninja console, and can be found in the getting started tab for a given pass template.
recipient ^(optional) object
The name, reason 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:
- full_name^* string
  The name of the person receiving the pass.
- reason^* string
  The reason the person is receiving the pass. Never sent to user, only for compliance purposes.
- phone_number ^(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

simple_pass_object = pass_ninja_client.passes.create(
    'ptk_0x14', # passType
    {
        'discount': '50%',
        'memberName': 'John'
    }
)

print(simple_pass_object.id)

List passes

Allows you to retrieve a list of passes using it's pass template id.

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

passType (aka pass template id)^* string
This is the pass type key, it is present in the getting started tab for a given pass template. It looks like this: ptk_0x14

passes_for_template = pass_ninja_client.passes.find(
    'ptk_0x14', # passType aka pass template id
)

print(passes_for_template)

Get a pass

Allows you to retrieve a pass using it's pass type and pass id, also known as it's serial number.

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

passType^* string
This is the pass type key, it is present in the getting started tab for a given pass template. It looks like this: ptk_0x14
passId^* string
PassId also known as a serial number. Takes on a namespaced format which looks like pid_MzQzNDM0MQ==

detailed_pass_object = pass_ninja_client.passes.get(
    'ptk_0x14', # passType
    'pid_NDQzXzQzMzQzMw==' # serialNumber aka pass id
)

print(detailed_pass_object)

Decrypt a pass

Allows you to decrypt a pass payload using it's pass type and encrypted payload.

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

passType^* string
This is the pass type key, it is present in the getting started tab for a given pass template. It looks like this: ptk_0x14
payload^* string
Payload is a hex encoded APDUs with no spaces. It looks like this (abbreviated for presentation): 55166a97002...1ea070f0d4fe88887

decrypted_pass_object = pass_ninja_client.passes.decrypt(
    'ptk_0x14', # passType
    '55166a9700250a8c51382dd16822b0c763136090b91099c16385f2961b7d9392d31b386cae133dca1b2faf10e93a1f8f26343ef56c4b35d5bf6cb8cd9ff45177e1ea070f0d4fe88887' # payload
)

print(decrypted_pass_object)

Update a pass

Allows you to update a pass using it's pass type, pass id and new information. 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:

passType^* string
This is the pass type key, it is present in the getting started tab for a given pass template. It looks like this: ptk_0x14
passId^* string
PassId also known as a serial number. Takes on a namespaced format which looks like pid_MzQzNDM0MQ==
pass^* object
The keys for this object are defined in the pass ninja console, and can be found in the getting started tab for a given pass template.

detailed_pass_object = pass_ninja_client.passes.put(
    'ptk_0x14', # passType
    'pid_NDQzXzQzMzQzMw==', # passId aka serialNumber
    {
        'discount': '100%',
        'memberName': 'Ted'
    } # pass object
)
print(detailed_pass_object)

Delete a pass

An irreversible action to destroy a pass using it's pass type and pass id, also known as it's 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:

passType^* string
This is the pass type key, it is present in the getting started tab for a given pass template. It looks like this: ptk_0x14
passId^* string
PassId also known as a serial number. Takes on a namespaced format which looks like pid_MzQzNDM0MQ==

deleted_pass_id = pass_ninja_client.passes.delete(
    'ptk_0x14', # passType
    'pid_NDQzXzQzMzQzMw==' # passId
)
print('Pass deleted. Serial_number: ', deleted_pass_id)

Webhook payload

If you have webhooks enabled, you we will send you a JSON payload like the one on the right whenever the user completes any of the following actions:

Installs a pass
Uninstalls a pass

We will automatically retry delivery until your server responds with an HTTP status code in the 200 range for up to 24 hours. At that point, no further attempts will be conducted.

{
  "passType": "ptk_0x14",
  "passId": "pid_NDQzXzQzMzQzMw==",
  "event": "install",
  "eventDate": "2024-04-23T18:25:43.511Z",
  "attempt": 1
}

Errors: Standard codes

We return a standard set of error codes, in addition to standard HTTP status codes. You can find the full list below:

Error code	HTTP Status	Meaning
UA1	401	Unauthorized request - you are missing a required header. Please review the Authentication section.
MP1	402	Missing credits - you are missing credits to use the API.
UA2	403	Forbidden - you are attempting to access someone elses passes - please stop.
RL1	429	Rate limit exceeded - you are sending too many requests, perhaps you are being throttled by adding recipients to pass creation. You may want to upgrade to an enterprise plan.
MR1	404	Pass template does not exist - you are attempting to use a pass template that does not exist.
MR2	404	Pass does not exist - you are attempting to access a pass that does not exist - it may have been destroyed.
MI1	400	Invalid pass body - The keys you are using for this pass template or pass do not fit the schema you defined in the PassNinja developer console.
IP1	400	Incompatible platform - The payload you are trying to decrypt is not decryptable because the pass is not for Apple.
GE77	500	Generic Error - Sometimes things go wrong, we're sorry and we will investigate.

Terminal: Simple readers

If you're using one of our developer 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.