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:

  1. PassNinja Python library
  2. PassNinja Ruby gem
  3. PassNinja NPM package
  4. PassNinja Swift library
  5. PassNinja Java package
  6. PassNinja C# package
  7. PassNinja PHP Composer package

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.

simple_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:

  1. Installs a pass
  2. 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.