Back to top

PassNinja API

PassNinja is a turn-key service for creating, distributing, and validating NFC enabled digital passes. We expose a RESTful API for each of these features to allow developers to programmatically access our service. Apple and Google took different approaches in designing their wallet solutions, though the end result for users is pretty much the same. For instance, Apple passes are bundled into securely signed pkpass files that need to be hosted by issuers whereas Google hosts pass content themselves. Due to these differences it can be challenging for brands to setup the infrastructure to manage NFC pass campaigns.

Passes

Our API centers around 📱NFC passes. These are designed to align with Apple Wallet and Google Wallet rendering specifications. We have chosen the overlapping features of both mobile wallets in order to provide developers with a common approach to managing their pass campaigns.

Make Pass

In order to make passes, you will first need to choose a PassNinja template for your campaign. Templates establish the look and feel of your passes while making passes personalizes them to a target user. Currently, PassNinja offers 5 sample templates for developers to test with. They include: event ticket, boarding pass, loyalty card, gift card, and coupon. If you’re interested in defining your own branded templates, please schedule a time to chat with us.

PassNinja templates outline the fields which you can modify. These are determined based on the use case in which the passes will be used. For instance, the passNinjaLoylaty.pass template contains fields like:

  • Apple: applePass:storeCard:auxiliaryFields:key:credit

  • Google: googlePass:secondaryLoyaltyPoints:balance:money

Below we present a standard set of json keys for 5 sample templates we’ve designed. Setting these keys when working with the Make Pass API will allow for custom passes to be created and updated programmatically.

Create New Pass
POST/make-pass

Create a new NFC pass based on the Apple and Google json keys defined in your PassNinja template and send them to a given email address.

Caution

All json keys need to be defined. If you omit any json keys in your API requests, no response will returned.

Example URI

POST https://dev-api.passninja.com/public/demo/make-pass
Request  with body
HideShow
Headers
Content-Type: application/json
Body
{
  "contact": {
    "email": "richard.grundy@gmail.com"
  },
  "appleTemplateBaseUrl": "https://passninja.com/assets/apple-pass/template/passes/passNinjaLoyalty.pass",
  "applePass": {
    "formatVersion": 1,
    "passTypeIdentifier": "pass.com.ndudfield.nfc",
    "teamIdentifier": "Q338UYGFZ8",
    "serialNumber": "nmyuxofgnaasdasdfasdf",
    "organizationName": "PassNinja",
    "description": "Ninja Fashionista",
    "foregroundColor": "rgb(255,255,255)",
    "backgroundColor": "rgb(87,22,22)",
    "labelColor": "rgb(198,130,0)",
    "logoText": "Ninja Fashionista",
    "barcodes": [
      {
        "message": "Ninja Fashionista, for stealth fashion",
        "format": "PKBarcodeFormatPDF417",
        "messageEncoding": "iso-8859-1"
      }
    ],
    "locations": [
      {
        "latitude": 37.3229,
        "longitude": -122.0323
      },
      {
        "latitude": 37.3286,
        "longitude": -122.0143
      },
      {
        "altitude": 10,
        "latitude": 37.331,
        "longitude": -122.029,
        "relevantText": "Store nearby on 3rd and Main."
      }
    ],
    "storeCard": {
      "headerFields": [
        {
          "key": "expires",
          "label": "Expires",
          "dateStyle": "PKDateStyleShort",
          "timeStyle": "PKDateStyleNone",
          "value": "2019-02-14T19:30+07:00"
        }
      ],
      "primaryFields": [
        {
          "key": "store",
          "label": "713 Points",
          "value": "Ninja Fashionista Loyalty Card"
        }
      ],
      "secondaryFields": [
        {
          "key": "member",
          "label": "Member",
          "value": "Auston B"
        }
      ],
      "auxiliaryFields": [
        {
          "key": "stores",
          "label": "Stores valid",
          "value": "All Stores"
        },
        {
          "key": "credit",
          "label": "Credit",
          "value": "11:11"
        }
      ],
      "backFields": [
        {
          "key": "notTransferable",
          "label": "Please note",
          "value": "This loyalty card is not transferable."
        },
        {
          "key": "purchases",
          "label": "Valid purchases",
          "value": "This loyalty card is valid for any purchases at any Ninja Fashionista store."
        }
      ]
    }
  },
  "googlePass": {
    "kind": "walletobjects#loyaltyObject",
    "id": "3175895186863635130.PassNinjaDemoLoyaltyClass.TODO",
    "classId": "3175895186863635130.PassNinjaDemoLoyaltyClass",
    "version": "1",
    "state": "active",
    "hasUsers": false,
    "smartTapRedemptionValue": "3175895186863635130.PassNinjaDemoLoyaltyClass.TODO",
    "classReference": {
      "kind": "walletobjects#loyaltyClass",
      "id": "3175895186863635130.PassNinjaDemoLoyaltyClass",
      "version": "1",
      "issuerName": "Ninja Fashionista",
      "messages": [
        {
          "kind": "walletobjects#walletObjectMessage",
          "header": "Stores Valid",
          "body": "All Stores",
          "displayInterval": {
            "kind": "walletobjects#timeInterval",
            "start": {
              "date": "2018-05-03T12:10:00.000Z"
            }
          },
          "messageType": "text"
        }
      ],
      "allowMultipleUsersPerObject": true,
      "locations": [
        {
          "kind": "walletobjects#latLongPoint",
          "latitude": 37.424354,
          "longitude": -122.09508869999999
        },
        {
          "kind": "walletobjects#latLongPoint",
          "latitude": 37.424015499999996,
          "longitude": -122.09259560000001
        },
        {
          "kind": "walletobjects#latLongPoint",
          "latitude": 40.7406578,
          "longitude": -74.00208940000002
        },
        {
          "kind": "walletobjects#latLongPoint",
          "latitude": 37.7901435,
          "longitude": -122.39026709999997
        }
      ],
      "reviewStatus": "approved",
      "imageModulesData": [
        {
          "mainImage": {
            "kind": "walletobjects#image",
            "sourceUri": {
              "kind": "walletobjects#uri",
              "uri": "https://image.ibb.co/gSd7dp/ninja_fashion2.png"
            }
          }
        }
      ],
      "textModulesData": [
        {
          "header": "Rewards details",
          "body": "This loyalty card is valid for any purchases at any Ninja Fashionista store."
        }
      ],
      "linksModuleData": {
        "uris": [
          {
            "kind": "walletobjects#uri",
            "uri": "http://maps.google.com/?q=google",
            "description": "Nearby Locations"
          },
          {
            "kind": "walletobjects#uri",
            "uri": "tel:6505555555",
            "description": "Call Customer Service"
          }
        ]
      },
      "redemptionIssuers": [
        "3175895186863635130"
      ],
      "heroImage": {
        "kind": "walletobjects#image",
        "sourceUri": {
          "kind": "walletobjects#uri",
          "uri": "https://image.ibb.co/iVVTJp/ninja_fashion.png"
        }
      },
      "enableSmartTap": true,
      "hexBackgroundColor": "#571616",
      "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
      "programName": "Ninja Fashionista Loyalty Card",
      "programLogo": {
        "kind": "walletobjects#image",
        "sourceUri": {
          "kind": "walletobjects#uri",
          "uri": "https://image.ibb.co/j2OD3d/ninji.png"
        }
      },
      "accountNameLabel": "Member Name",
      "accountIdLabel": "Member Id",
      "rewardsTierLabel": "Level",
      "rewardsTier": "Platinum"
    },
    "accountName": "Richard G ",
    "accountId": "123423133",
    "loyaltyPoints": {
      "label": "Points",
      "balance": {
        "string": "713"
      }
    },
    "secondaryLoyaltyPoints": {
      "label": "Credit",
      "balance": {
        "money": {
          "kind": "walletobjects#money",
          "micros": "1111000000",
          "currencyCode": "USD"
        }
      }
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "htmlLink": "https://demo-passes.passninja.com/nfc-passes-e3ee1e59-e0b4-49af-b6c1-8f72e3975b81.html",
  "appleLink": "https://demo-passes.passninja.com/pass.com.ndudfield.nfc-e3ee1e59-e0b4-49af-b6c1-8f72e3975b81.pkpass",
  "googleLink": "https://www.android.com/payapp/savetoandroidpay/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhZG1pbi0zNDFAcGFzcy1uaW5qYS5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIsImF1ZCI6Imdvb2dsZSIsInR5cCI6InNhdmV0b2FuZHJvaWRwYXkiLCJpYXQiOjE1NTc5NDcxNjQsInBheWxvYWQiOnsibG95YWx0eU9iamVjdHMiOlt7ImtpbmQiOiJ3YWxsZXRvYmplY3RzI2xveWFsdHlPYmplY3QiLCJzdGF0ZSI6ImFjdGl2ZSIsImlkIjoiMzE3NTg5NTE4Njg2MzYzNTEzMC5QYXNzTmluamFEZW1vTG95YWx0eUNsYXNzLmUzZWUxZTU5LWUwYjQtNDlhZi1iNmMxLThmNzJlMzk3NWI4MSIsImNsYXNzSWQiOiIzMTc1ODk1MTg2ODYzNjM1MTMwLlBhc3NOaW5qYURlbW9Mb3lhbHR5Q2xhc3MifV19LCJvcmlnaW5zIjpbImh0dHBzOi8vcGFzc25pbmphLmNvbSIsImh0dHBzOi8vbmluamlwYXNzLmNvbSJdfQ.IXXbkF6BJyKbBMzvSrAO5eGLKWy1wYpafIeXojodatXznwytK3tA3jAeUwk5bo3deoUMzFkZHDdgQHAh_U5OKIkuXAZ2cqsjfWdpDPvtgAXCzqGfMyBdb36UFydx_TCqaq9DurpKxX9CtcvOVzjfx-KgAbcWV_jqVkVNQe6428ry-IBBFnBCTO0VZDJOn7wqFUS-hixg6A4n7aExxjuZPA5ScDPtIoY2MSYKR1-7Kxqa-VvSfaR9eLEAIaeU5Rle3kqWs8eC8ozZuvK0jXlgA2ZYuVec20oa95nRR3X6Q8AMap5sm8uZVEeuWmPQUk6DSqN2NPc-nXciYTIeE8q6Pw",
  "ok": true
}

Update Existing Pass
PUT/make-pass

Update an existing NFC pass by referencing it’s serial number and passing in new key-value data. For instances where the pass has been installed on a mobile device, updates will be pushed out to them. Only certian key-value fields will trigger a push notification on the mobile device where the pass has been installed, otherwise a silent update will occur.

Example URI

PUT https://dev-api.passninja.com/public/demo/make-pass
Request  with body
HideShow
Headers
Content-Type: application/json
Body
{
    "serialNumber": "nmyuxofgnaasdasdfasdf",
    "applePass": {
        "storeCard": {
            "auxiliaryFields": [
                {
                "key": "credit",
                "label": "Credit",
                "value": "6:11"
                }
            ],
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "appleLink": "https://demo-passes.passninja.com/pass.com.ndudfield.nfc-e3ee1e59-e0b4-49af-b6c1-8f72e3975b81.pkpass",
  "ok": true
}

Generated by aglio on 31 May 2019