Enable NFC Support for your Passes

You can add NFC settings at the project level to support both your Apple and Google passes.

While Airship combines most of your NFC-enablement settings into a single object at the project level, you must make sure that your Google/Apple accounts are set up to use NFC, and make sure that your terminals are set up with appropriate private keys to decode NFC communications from your Airship-generated passes.

Airship supports NFC communications for:

• Apple: All pass types
• Google: All pass types

Apple Wallet NFC requirements

You enable NFC support by requesting an NFC-enabled certificate from Apple. Providing your NFC-enabled certificate to Airship automatically enables NFC support for your iOS passes.

You set your private key on your terminal and provide your public key to Airship. You can provide your public key with NFC messages, and your terminal will decode the message using the private key.

Because iOS supports NFC at the certificate level, and iOS provides your public/private keys, you can only have one active NFC merchant configuration for your project. Airship will let you add multiple NFC merchants for Apple but will only use the most recently added NFC merchant configuration.

However, you can provide the public key your terminal uses at the pass/message level to override your project’s global public NFC encryption key. You may want to do this if you support multiple vendors from a single Loyalty pass.

{
    "fields" : {},
    "nfc": {
        "message": "<nfcMessage/smartTapValue>",
        "encryptionPublicKey":"<iOSpublicKeyOverride>"
    }
}

Google Wallet NFC requirements

To enable NFC support for Google passes, you must send a POST to /v1/project/{projectId}/nfcMerchants or /v1/projects/id/{projectExternalId}/nfcMerchants with your merchant information. When you set up your account with Google, Google assigns you an Issuer ID and a Collector ID. As long as you have a valid Google Pay certificate, Airship will return the correct issuer and collector identifiers.

You can also use your own public/private encryption key pair or have Airship generate a key pair for you. If you already have a key pair, and your private key is already set up at your terminals, provide your public key when you set up NFC information. If you have not set up a key pair yet, do not provide a publicKeyPem in your /nfcMerchants payload, and Airship will generate both keys for you.

POST /v1/project/13137/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "vendor": "GOOGLE",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "keyVersion": 1,
  "publicKeyPem": "<public-encryption-key>"
}

Unlike iOS, you can have multiple NFC merchant configurations per project. You may want to do this if your pass supports terminals in different businesses — like a loyalty program that supports multiple stores under the same parent organization.

If merchant terminal is already configured and there is a pre-existing smartTapIssuerId (also known as a redemption issuerId), it can be shared across clients, which can use the existing smartTapIssuerId to configure other projects using the following API call:

POST /v1/project/{secondProjectId}/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "vendor": "GOOGLE",
  "smartTapIssuerId": "1234567890"
}

Adding NFC support to your project

These examples use standard project IDs. If your project has an external ID, use the corresponding /v1/project/id/{projectExternalId}/ endpoints.

For Apple, before you begin, make sure that you have requested certificate(s) supporting NFC and uploaded those certificates to Airship.

1. Make a call to the /v1/project/{projectId}/nfcMerchants API to add NFC information to your project.

2. Go to your Wallet dashboard and click Templates.

3. Select your template, click Edit Design, and then click Save. Despite making no changes, your template will now support NFC.

4. Update passes with NFC messages. The nfc.message contains values that your terminals and backend systems will use to identify and take actions against the pass, like a loyalty or coupon number.

   Update pass with NFC message

   PUT /v1/pass/123 HTTP/1.1
   Content-Type: application/json
   Authorization: Basic <Base64 key>
   Api-Revision: 1.2
   
   {
     "fields" : {},
   	"nfc": {
   		"message": "<nfcMessage/smartTapValue>"
   	}
   }

Terminals and Encryption keys

NFC uses SSL to authenticate transactions. You provide Airship your public key, and your terminals must have the private key.

You can provide your public key to Airship when you create an NFC merchant using publicKeyPem. If you exclude publicKeyPem from the payload, Airship will generate public and private SSL keys for you. If you let Airship generate keys for you, you must copy your private key from the response; Airship will not return your private key in any other payload.

For Google, you can add an NFC merchant for each key pair that you have. So, if you have a single pass that works at different merchants belonging to the same company, your project can contain all the different keys that you use across different NFC terminals.

For Apple, your project can contain a single NFC merchant. You should expect to use the same key pair across your terminals. Or, when you add an NFC message to a pass, you can override your publicKeyPem with an encryptionPublicKey whenever you set an NFC message on your pass.

PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "fields": {},
  "nfc": {
    "message": "125855|8BD29F182DE29848E5A02FAE749DA545",
    "encryptionPublicKey": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgAD0TDG7WzxFXJc9FZ0rE8qG5n6Z5voU5axJYDV5nViYEM="
 }   
}

The NFC message

After you set up NFC merchants in Airship and your terminals, you can assign a message to your passes. The message conveys information that your terminal and/or backend systems use to identify and take advantage of the pass.

While the message takes a string, this can be any kind of delimited string or JSON string and may contain multiple values that are relevant to you.

For example, if you have a loyalty program, you may want the message to contain a value with the pass ID, loyalty points, and/or the loyalty ID for the pass. When a user taps their device to the appropriate terminal, the terminal gets this message and decodes it to perform actions with or against the pass.

You can apply NFC messages to passes using the /pass APIs.

PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "fields": {},
  "nfc": {
    "message": "<passId>,<loyaltyBarcodeValue>,<points>",
 }   
}