Communication between a terminal and the Google Wallet app
A terminal identifies itself with a Collector ID that is mapped to a Redemption Issuer ID. When a Smart Tap occurs, the terminal transmits its Collector ID to the user's device. The Google Wallet app then examines the Class ID and Collector ID of each stored pass. When one or more matches are found, the Google Wallet app transmits the matching passes to the terminal. See Merchant configuration for setup details.
Example 1: One Redemption Issuer
In the preceding diagram, there are two different Issuers:
- Issuer
2018
is a pass developer (also called an Aggregator) - Issuer
1990
is a merchant, fooPizza (also called a Redemption Issuer)
The Redemption Issuer, fooPizza, wants to enable Smart Tap functionality for their pass (managed by the Aggregator). The Aggregator and Redemption Issuer must complete the following steps to enable Smart Tap for the merchant terminals.
Step | Role | Description |
---|---|---|
1 | Aggregator | Create a pass class and object (in the diagram, abc
and 123 , respectively). |
2 | Aggregator | Include the Redemption Issuer's ID in the
redemptionIssuers property of the pass class. This
tells Google Wallet that the Issuer ID 1990 is allowed
to redeem pass objects that reference this class. |
3 | Redemption Issuer | Obtain a Collector ID (in the diagram, 12345678 ).
|
4 | Redemption Issuer | Set the Collector ID 12345678 on each Smart Tap
capable terminal that will be used. Any object with the
Class ID abc and Collector ID 12345678 will be
conveyed to the reader. |
Example 2: Multiple Redemption Issuers
A single pass class can have multiple Redemption Issuers. In order to be able to
redeem a specific pass class, a Redemption Issuer's ID must be included in the
redemptionIssuers
property of the class. Each Redemption Issuer then has its
own Collector ID, which is configured on their Smart Tap capable terminals.
In the preceding diagram, there are three different Issuers:
- Issuer
8088
is a pass developer (Aggregator) - Issuer
1990
is a merchant, fooPizza (Redemption Issuer) - Issuer
2018
is a merchant, yumPie (Redemption Issuer)
The Aggregator and Redemption Issuers must complete the following steps to enable Smart Tap for the merchant terminals.
Step | Role | Description |
---|---|---|
1 | Aggregator | Create a pass class and object (in the diagram, abc
and 123 , respectively). |
2 | Aggregator | Include the Redemption Issuers' IDs in the
redemptionIssuers property of the pass class. This
tells Google Wallet that the Issuer IDs 1990 and
2018 are allowed to redeem pass objects that reference
this class. |
3 | Redemption Issuers | Obtain Collector IDs (in the diagram, 12345678 for
fooPizza and 18802001 for yumPie). |
4 | Redemption Issuers | Set the corresponding Collector ID on each Smart Tap
capable terminal that will be used. Any object with the
Class ID abc and a matching Collector ID will be
conveyed to the reader. |
Example 3: No Aggregator
A pass class can be developed and issued within the same Issuer account. In this
case, there is no Aggregator managing pass classes for multiple Redemption
Issuers. In order to be able to redeem a specific pass class, the pass developer
must include their Issuer ID in the redemptionIssuers
property of the class.
The pass developer must then obtain a Collector ID and configure it on their
Smart Tap capable terminals.
The pass developer must complete the following steps to enable Smart Tap for the merchant terminals.
Step | Role | Description |
---|---|---|
1 | Pass Developer | Create a pass class and object (in the diagram, abc
and 123 , respectively). |
2 | Pass Developer | Include their Issuer ID in the redemptionIssuers
property of the pass class. This tells Google Wallet
that the Issuer ID 2018 is allowed to redeem pass
objects that reference this class. |
3 | Pass Developer | Obtain a Collector ID (in the diagram, 12345678 ).
|
4 | Pass Developer | Set the corresponding Collector ID on each Smart Tap
capable terminal that will be used. Any object with the
Class ID abc and a matching Collector ID will be
conveyed to the reader. |
User experience and behavior
The behavior of what is transmitted between a terminal and the Google Wallet app depends on the user and how they are interacting with the Google Wallet app at that time.
Scenario 1: User opens a specific pass
Step | Role | Description |
---|---|---|
1 | User | Select a specific pass in the Google Wallet app. |
2 | User | Tap a Smart Tap enabled terminal. |
3 | Terminal | (Collector ID matches) The pass is transmitted to the
terminal. (Collector ID does not match) The pass is not transmitted to the terminal. |
Scenario 2: Google Wallet Home tab or unlocked screen view
Step | Role | Description |
---|---|---|
1 | User | Open the Home tab in the Google Wallet app, or unlock the device's screen. |
2 | User | Tap a Smart Tap enabled terminal. |
3 | Terminal | (Single valid Collector ID match) The pass is
transmitted to the terminal.
(Multiple valid Collector IDs match) Display a carousel of valid passes and transmit the one selected by the user. |
Note The validity of a pass depends on the specific configuration of the pass object. Be sure to check the following pass object properties:
state
validTimeInterval
Smart Tap collection example
The following table describes the Issuers and passes that will be used in this example:
Merchant name | ILuvCoffee | Coffee-Foo | Mocha-R-Us |
---|---|---|---|
Issuer ID | 123 |
456 |
789 |
Collector ID | 11111111 |
44444444 |
77777777 |
Loyalty Tiers | R-Basic | My Rewards | |
R-Gold |
ILuvCoffee has two different loyalty tiers: R-Basic and R-Gold. Meanwhile, Coffee-Foo has a loyalty program with a single tier, My Rewards, and Mocha-R-Us has no loyalty program.
As part of a cross-promotion campaign, the merchants would like to have the following options available to their customers:
- R-Basic tier customers can use Smart Tap to redeem their loyalty membership at both Coffee-Foo and Mocha-R-Us
- R-Gold tier customers do not need Smart Tap redemption
- My Rewards customers can use Smart Tap to redeem their loyalty membership at Coffee-Foo only
For this campaign to work, each loyalty class will need the following values
set in the redemptionIssuers
property of the class definition.
Loyalty class | Redemption Issuer IDs |
---|---|
R-Basic | ["456", "789"] |
R-Gold | [] |
My Rewards | ["456"] |
With this configuration, any pass objects that reference these classes will have the following Collector IDs:
- R-Basic:
44444444
,77777777
- R-Gold: No Collector IDs will be included
- My Rewards:
44444444
Collector authentication at tap time
As part of Issuer configuration, an Issuer account may have multiple public keys associated with it. These public keys are stored in the Google Wallet app, which uses them for authentication when a user taps their device on a Smart Tap enabled terminal. This authentication step takes place after the app has found a pass object issued to the user that has a Collector ID matching the value advertised by the terminal.
Continuing the example in the previous section, the following table describes public keys associated with each Issuer.
Merchant name | ILuvCoffee | Coffee-Foo | Mocha-R-Us |
---|---|---|---|
Issuer ID | 123 |
456 |
789 |
Collector ID | 11111111 |
44444444 |
77777777 |
Loyalty Tiers | R-Basic | My Rewards | |
R-Gold | |||
Public Keys | aaa | bbb |
An example customer has the following loyalty cards saved in their Google Wallet app:
- ILuvCoffee: R-Basic
- Coffee-Foo: My Rewards
As before, the following values are set in the redemptionIssuers
property for
each loyalty class.
- R-Basic:
["456", "789"]
- My Rewards:
["456"]
If the user taps their device at terminals for each merchant, there are three possible outcomes:
Merchant terminal | Outcome |
---|---|
ILuvCoffee | Since ILuvCoffee (Redemption Issuer ID 123 ) isn't
currently configured to redeem its own loyalty class,
R-Basic, nothing is transmitted. |
Coffee-Foo | The Google Wallet app authenticates to the Coffee-Foo
terminal using the bbb public key. Depending on the
current screen the user is viewing on their device, one
of the scenarios listed in the
User experience section
will occur. |
Mocha-R-Us | There is no public key for Mocha-R-Us in this example. Even though the R-Basic program can be redeemed with merchant, it cannot authenticate to the terminal, so nothing will be transmitted. |
Authentication limits
When a pass is synced to a user's Google Wallet app, all Redemption Issuers of that pass are looked up from the Google Wallet backend. The Collector ID, public keys, and key versions for each Redemption Issuer are stored locally in the Google Wallet app.
A pass can have many Redemption Issuer IDs. Each then maps to a specific Collector ID for a specific merchant. Additionally, there can be many public keys and key versions for a single Collector ID.
The Google Wallet app will not attempt to authenticate to a terminal if it doesn't have any passes that are redeemable by that terminal. This is based on the Collector ID and public key version. To update public keys for your pass, the terminal must have an internet connection so that it can retrieve the new public keys from the Google Wallet backend.
A single pass can be associated with many public keys at once. See Merchant configuration for information on setting multiple public keys for the same pass.
Value transmission during tap
In order to send data from a pass during tap, the pass object's
smartTapRedemptionValue
must be set. Once the class that corresponds to the
object is enabled for Smart Tap, this value will be sent to the terminal.
Based on your integration and use case, this value will be used to identify your user's pass and perform any needed transaction logic, such as the following:
- Update the user’s balance or status
- Update your own backend based on the transaction
- Issue an update to the pass object using the Google Wallet API so that it reflects any changes to the user's status on their device
The terminal and the Google Wallet app handle encryption of all the data
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 set in the
smartTapRedemptionValue
property of the pass object. This means that the pass
developer doesn't have to handle encryption of transmitted data.
If you want to add another layer of security, you can set the
smartTapRedemptionValue
property so that only the system receiving the
transmitted data (such as a Point of Sale) can decrypt it. However, the pass
developer and POS administrator will be responsible for the
encrypytion/decryption process.