The Google Wallet API offers several flows for provisioning passes and adding them to a user's Google Wallet app. The specific flow that works for you depends on your use case and the types of passes you plan to issue to your users.
Before getting started, first ensure you have a strong understanding of how classes and objects work when creating a JWT to issue passes to your users.
Below, the following flows are outlined to create a pass in Google Wallet:
Create classes and objects using the REST API
In this approach, you have a backend server or process responsible for creating pass classes and objects for your users. When a user is going to save a pass to their Google Wallet app, your backend server encodes the pass object ID into a JWT that is signed by a service account key. An Add to Google Wallet link containing the signed token is then returned to the client. When the user opens the link, the encoded JWT is used to add the existing pass to the user's Google Wallet app.
The high-level steps of the flow are:
- Create a Class on your backend server using the Google Wallet API
- Create an Object on your backend server using the Google Wallet API (this references the class from the previous step)
- Create and sign a JWT that includes the ID of the pass object and pass class you created in the previous step
- Return the JWT to the client and create an Add to Google Wallet button
- [Optional] Update the pass by patching the object
Example flow diagram
The diagram below describes the flow for adding a loyalty card with a loyalty class and loyalty object. This same flow applies for all verticals with classes and objects using the Google Wallet API.
JSON sample
The following JSON example shows an existing loyalty card included in a JWT that is used to create an Add to Google Wallet link.
{
"aud": "google",
"iat": "ISSUER_ID",
"iss": "SERVICE_ACCOUNT_EMAIL",
"typ": "savetowallet",
"origins": [],
"payload": {
"loyaltyObjects": [
{
"classId": "ISSUER_ID.LOYALTY_CLASS_SUFFIX",
"id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX"
}
]
}
}
Create full classes and objects in the JWT
In this approach, the pass classes and/or objects are defined and encoded into a JWT that is signed by a service account key. An Add to Google Wallet link is then returned to the client. When the user opens the link, the encoded JWT is used to create the defined classes and/or objects.
The high-level steps of the flow are:
Define a Class as a JSON object
This is required if the class does not exist already. Alternatively, you can omit the class definition and simply reference the class ID in your object definition.
Define a Object as a JSON object
Create and sign a JWT that includes the class and object definitions from the previous two steps
Return the JWT to the client and create an Add to Google Wallet button
[Optional] Update the pass by patching the object
Example flow diagram
The diagram below describes the flow for adding a loyalty card with a loyalty class and loyalty object. This same flow applies for all verticals with classes and objects using the Google Wallet API.
JSON sample
New
The following JSON example shows creating a new loyalty class and object in a JWT that will create an Add to Google Wallet link.
{
"iss": "OWNER_EMAIL_ADDRESS",
"aud": "google",
"typ": "savetowallet",
"iat": "UNIX_TIME",
"origins": [],
"payload": {
"loyaltyClasses": [
{
"id": "ISSUER_ID.LOYALTY_CLASS_ID",
"programLogo": {
"sourceUri": {
"uri": "https://images.unsplash.com/photo-1512568400610-62da28bc8a13?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660"
},
"contentDescription": {
"defaultValue": {
"language": "en-US",
"value": "LOGO_IMAGE_DESCRIPTION"
}
}
},
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "Heraldic Coffee"
}
},
"localizedProgramName": {
"defaultValue": {
"language": "en-US",
"value": "Program Name"
}
},
"hexBackgroundColor": "#72461d",
"heroImage": {
"sourceUri": {
"uri": "https://images.unsplash.com/photo-1447933601403-0c6688de566e?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336"
},
"contentDescription": {
"defaultValue": {
"language": "en-US",
"value": "HERO_IMAGE_DESCRIPTION"
}
}
}
}
],
"loyaltyObjects": [
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.LOYALTY_CLASS_ID",
"loyaltyPoints": {
"balance": {
"int": "1234",
},
"localizedLabel": {
"defaultValue": {
"language": "en-US",
"value": "Reward Points",
},
},
},
"barcode": {
"type": "QR_CODE",
"value": "BARCODE_VALUE",
"alternateText": "",
},
}
]
}
}
Existing
The following JSON example shows creating a new loyalty object (referencing an existing class) in a JWT that will be used to create an Add to Google Wallet link.
{
"iss": "OWNER_EMAIL_ADDRESS",
"aud": "google",
"typ": "savetowallet",
"iat": "UNIX_TIME",
"origins": [],
"payload": {
"loyaltyObjects": [
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.LOYALTY_CLASS_ID",
"loyaltyPoints": {
"balance": {
"int": "1234",
},
"localizedLabel": {
"defaultValue": {
"language": "en-US",
"value": "Reward Points",
},
},
},
"barcode": {
"type": "QR_CODE",
"value": "BARCODE_VALUE",
"alternateText": "",
},
}
]
}
}