Understand how a terminal requests Passes

There are several ways that a merchant’s terminal requests a specific Pass.

Communication between a terminal and the Google Pay app

A terminal identifies itself with a Collector ID. It's mapped to the redemption issuer ID in the Google back-end that Pass developers interact with via Google Pay API for Passes.

When a Smart Tap occurs, the terminal transmits its collector ID to the Google Pay app. The Google Pay app examines each Pass’s redemption issuers, derives the collector ID, and, when matched, transmits those specific Passes to the terminal.

To set this up, see Set up a merchant terminal.

Here's an illustration of the process:

Setup 1

Setup 1: In the diagram above, Issuer_id: 2018 has one class and one object. This issuer account is used by the Pass developer. The Class_id: abc class has a redemptionIssuers['1990'] object. By definition, Issuer_id: '1990' is a redemption issuer ID that represents Merchant fooPizza. The terminal has a collector ID 12345678. This maps to the collector ID that's configured to the redemption issuer 1990. Any object of Class_id: abc is conveyed to the reader with collector ID 12345678.

Setup 1.1

Setup 1.1: In the example above, fooPizza and yumPie can redeem the same Pass, object_id: 123. A class can have multiple redemption issuers. The redemption issuer accounts that correspond with the issuers have their own unique collector IDs in their terminals.

Setup 2

Setup 2: The diagram above shows how the class can set its own issuer account to be a redemption issuer. Issuer_id: 2018 has one class and one object. The Class_id: abc class has a redemption issuer object called Issuer_id: 2018. By definition, Issuer_id: 2018 is a redemption issuer ID, which represents the merchant fooPizza. The terminal has collector ID 12345678. This maps to the collector ID that's configured to Issuer_id: 2018, which is also where the Class_id: abc is contained. Any object of Class_id: abc is conveyed to the terminal with collector ID 12345678.

User selection from Google Pay app

The behavior of what's transmitted to the Google Pay app depends on what the user sees on their device.

If a user views the Pass in Google Pay and then Smart Taps, that Pass is transmitted as long as its collector ID matches the terminal that requests it. It does this regardless of its validity, which is based on the properties set on the class or object.

The user might not see the Pass, such as when they're in the home tab of Google Pay, or when they see it from the unlocked screen view in the device. If the user doesn't see the Pass and only has one valid redeemable Pass based on the collector ID, the Pass is conveyed.

If the user has many Passes that are valid and redeemable based on the collector ID, Google Pay performs either of the following tasks:

  • Displays a selection carousel for the user to pick from and tap-to-convey.
  • Or if there's only one valid Pass, it will convey it.

The validity of a Pass depends on the Pass vertical. Be sure to check the properties related to the state and usage date, such as object.state or object.validTimeInterval.

Smart Tap collection example

Consider this configuration example of fake issuers and their loyalty programs:

Issuer ID123456789
Collector ID1114444444477777777
Loyalty ClassR-basicMy Rewards- none -
Loyalty ClassR-gold- none -- none -

iLuvCoffee has two different loyalty classes that are used to create Passes: the R-basic program and the R-gold program. Meanwhile, Eat-foo has its own My Rewards program, and Bacon-R-us has no loyalty programs.

Now, assume that you'd like the following configuration:

  • R-basic is redeemable at Eat-foo and Bacon-R-us.
  • My Rewards is redeemable at Eat-foo.
  • R-gold doesn't have any Smart Tap support.

For this configuration, the loyalty classes are set up with these redemption issuer IDs:

  • R-basic redemption issuer IDs: 456, 789.
  • My Rewards redemption issuer IDs: 456.
  • R-gold redemption issuer IDs: - none -.

With this configuration, the instances of these classes have these collector IDs configured:

  • R-basic collector IDs: 44444444, 77777777.
  • My Rewards collector IDs: 44444444.
  • R-gold collector IDs: - none -.

Collector authentication at time of Smart Tap

Each issuer account might have any number of public security keys associated with it. These public keys are then synced and stored in the Google Pay app, which are ready for use if the user taps on a terminal that claims to be one of the associated collector IDs.

To continue with our example, assume that our issuers also have these keys set up:

Issuer ID123456789
Collector ID111111114444444477777777
Loyalty ClassR-basicMy Rewards- none -
Public Keyaaabbb- none -

The user has iLuvCoffee’s R-basic loyalty card and an Eat-foo My Rewards loyalty card in their Google Pay account, and they try to tap different terminals.

These are the redemption issuer sets for these two loyalty card classes:

  • R-basic redemption issuer IDs: 456, 789.
  • My Rewards redemption issuer IDs: 456.

Here are three possible outcomes:

iLuvCoffee terminal: The Google Pay application could theoretically authenticate and confirm that the terminal does in fact belong to iLuvCoffee. However, iLuvCoffee isn't set up to redeem the issuer for its own loyalty class, R-basic. So, in this case, nothing is transmitted.

Eat-foo terminal: The Google Pay application authenticates the Eat-foo terminal that uses the public "bbb" key. If we assume that the detailed screen of an R-basic or My Rewards Pass isn't viewable to the user, such as when they're viewing the home tab, the application searches for Passes it has that are redeemed by Eat-foo. It finds an R-basic card and a My Rewards card, and brings up a carousel so that the user can select and tap which one to transmit.

Alternatively, if the user views R-basic and Smart Taps, only R-basic is transmitted.

Bacon-R-us terminal: There's no public key for Bacon-R-us in this platform, so even though the R-basic card has them listed as a redeemable issuer, it cannot authenticate the terminal and nothing is transmitted.

Authentication limits

When a Pass is synced to the Google Pay app, all redemption issuers of the Pass are looked up from the Google back-end. The collector ID, public keys, and key versions that correspond to each redemption issuer are stored locally in the Google Pay app for that Pass.

There can be many public keys and key versions for a single collector ID. A Pass can have many redemption issuer IDs, which have one-to-one mapping with a collector ID.

The Google Pay app won't authenticate a terminal if it doesn't have any passes that are redeemable by that terminal. This is identified by the collector ID and requested key version. To update the public keys of a Pass, the device must have an internet connection so that it can retrieve the new public keys from the Google back-end.

A pass can be associated with many public keys at once. See Enable Smart Tap for a merchant to set multiple public keys for the same Pass.

Value transmitted from the Pass

Every vertical’s object needs to set this string property: object.smartTapRedemptionValue.

Once the class that corresponds to the object is enabled for Smart Tap, this value is sent to the terminal.

Based on your integration with the POS, use this value to identify the user’s Pass, and follow with these actions after they've successfully tapped at a merchant’s terminal:

  1. Update the user’s balance or status at POS.
  2. Update your own back-end based on the transaction at POS.
  3. Issue an update to the object so that it reflects on the Google Pay Pass.

The terminal and the Google Pay app handle encryption of all the data that's transmitted over NFC. The terminal handles decryption of data after the Smart Tap takes place. Within the data, there are Service Object NDEF records that represent each Pass transmitted. The Service object’s Service number NDEF Record has a payload that contains the value that's set in the object.smartTapRedemptionValue of the Pass. This means that the Pass developer doesn't have to encrypt anything. If the Pass developer wants extra encryption for an added layer of security, set the value so that only the POS system can decrypt it. It's up to the Pass developer and POS contact to handle that encryption process.