Select one of the following pass verticals to learn more about how it can be used.
The Google Pay API for Passes allows you to engage with users through event tickets. The concepts discussed in this guide should help you better understand the capabilities of saved event tickets.
To implement event tickets, use the JWT POST request method or "skinny" JWT links, which are methods that pre-insert the classes and objects.
The following use cases are available only to the event ticket vertical:
- Update passes.
- Make a button to save multiple passes.
- Group event tickets.
- Receive upcoming event notification.
- Linked offers.
- Handle expired passes.
- Link to a saved pass.
- Link out from a saved pass.
Update passes
If there are changes to a pass after it's created, use the REST API to deliver those changes to users. If the changes affect only classes, you can also use the Google Pay Merchant Center. Pass updates are an important way to engage with your users.
To update the fields for all of the event tickets for a specific event, such as when the
venue address changes, you only need to
update
or patch
the EventTicketClass
or use the
Google Pay Merchant Center.
Google propagates this information to all EventTicketObject
s associated
to the updated EventTicketClass
. This is the case for all fields defined
at the EventTicketClass
level.
To update a single pass, such as when the seat number for one ticket holder changes, you need to
update
or patch
a single EventTicketObject
. This is the case for all fields defined at
the EventTicketObject
level.
Sometimes, you might not know when a change happens, or when to trigger an update
or
patch
request. In cases like that, periodically schedule update
or
patch
requests for each and every class and object. You can find all classes of a
particular issuer account if you call the EventTicketClass
list
method.
You can find all objects of a particular class if you call the EventTicketObject
list
method.
Make a button to save multiple passes
If a user buys multiple passes, and they're likely to save all of them to Google Pay, then it's useful to allow a user to save many objects with one click of a Save to Google Pay button or link. You can define multiple objects or classes when you sign the JSON Web Token (JWT).
You must create the JWT in either of the following formats:
- With pre-inserted classes and objects only.
- With only object and class resources that are fully defined within the JWT.
For an example of how to create a button for multiple passes, see Save multiple attendees button.
For more information on the UI representation of Passes, see Group event tickets.
Group event tickets
There are features which work differently if they're used on a group rather than individual objects, such as status notifications, or the organization of multiple saved Passes in the user interface.
The conditions by which EventTicketObject
are considered to be a group depend on
whether or not the class.eventID
property is defined.
Group with class.eventId
The class.eventId
property can group tickets, regardless of other properties.
For example, if two EventTicketObject
objects have class.eventId = "foo"
, even if they have
different class.eventName
and class.dateTime.start
, both objects are
considered to be in a group.
When class.eventID
is used, objects only require the following properties to be
consistent in order to be considered as a group.
- Issuer ID (from Google Pay API for Passes Merchant Center)
class.eventId
Group without class.eventId
If class.eventId
isn't set for EventTicketObject
objects, they're only
considered a group if all of the properties listed below are the same:
- Issuer ID (from Google Pay API for Passes Merchant Center)
class.eventName
class.dateTime.start
Receive upcoming event notifications
Google Pay sends a notification to the user three hours prior to the
event. The event time is defined by
class.dateTime.start
.
To receive this notification, the user must have notifications enabled. To check this, they can navigate to Settings > Notifications and see if Updates about your passes is turned on.
The notification shows up in the notifications area, and in the lock screen, if the user has notifications enabled for the lock screen.
The notification has the following unmodifiable format:
class.eventName Expand for more options
If they tap the notification and unlock their device, their pass appears in the Google Pay app.
If the user has multiple passes, only the soonest useable pass is shown. If they've saved grouped passes as per Group event tickets, the notification only shows one of the passes in the group. However, when they tap it, the user can swipe left and right to see the other passes in that group.
The notification is pinned and won't auto-dismiss after a user opens it. Auto-dismiss occurs 60
minutes after class.dateTime.end
. If no class.dateTime.end
time is provided, class.dateTime.start
is used instead..
Linked offers
Linked offers allow existing offers to appear within the event ticket view, making
relevant content easier for the user to discover. The writable list field
linkedOfferIds
in a EventTicketObject
indicates which
offers are associated with the event ticket.
Creating the offer before linking
To link a linked offer, the offer classes and objects linked to the event ticket
must already be created. To learn more about creating offers, see
Offers. Unlike
standalone offers, linked offers do not require a user to explicitly save the offer. The
id
field found in the OfferObject
is used to point to the
EventTicketObject
.
Link offers to an event ticket
The existing offers can be linked to an event ticket
using the REST API calls
insert
,
or update
,
or patch
,
or modifyLinkedOfferObjects
.
When offers are linked to an event ticket upon creation
of the event ticket using the
insert
call or when offers are both linked and unlinked to an existing event ticket using the
update
call, the field linkedOfferIds
can be written with the rest of the
EventTicketObject
using the established format:
{ "id": "2945482443380251551.ExampleObject1", "classId": "2945482443380251551.ExampleClass1", ... "linkedOfferIds": [ "2945482443380251551.OfferObject1", "2945482443380251551.OfferObject2" ] }
When offers are linked and unlinked to an existing event ticket using the
patch
call, the field linkedOfferIds
can be the only field in the request:
{ "linkedOfferIds": [ "2945482443380251551.OfferObject1", "2945482443380251551.OfferObject2" ] }
However, in order to avoid mistakes when dealing with arrays, specify which linked offers need
to be added and which need to be removed, and be able to omit the linked offers that should remain
untouched. We recommend to use the
modifyLinkedOfferObjects
method as in the following example:
{ "linkedOfferObjectIds" { "addLinkedOfferObjectIds": [ "2945482443380251551.OfferObject1", "2945482443380251551.OfferObject2" ], "removeLinkedOfferObjectIds": [ "2945482443380251551.OfferObject3", "2945482443380251551.OfferObject4" ] } }
Designing event ticket with linked offers
Linked offers will appear in an event ticket view between the card section and the details section, as shown below. Only a maximum of 5 linked offers are displayed in the carousel. If more offers are linked to the event ticket, the user can click on the "More" button at the end of the carousel to display them all.
When clicked the linked offer uses a simplified offer design, as shown below.
Handle expired passes
Under the "Passes" tab of the Google Pay app, there's an "Expired passes" section that contains all archived or inactive passes. A pass is moved to the "Expired passes" section if at least one of the following conditions is true:
-
It's been at least 72 hours since
class.dateTime.end
expired. Ifclass.dateTime.end
isn't specified,class.dateTime.start
is used instead. The pass moves to "Expired passes" anytime between 72-96 hours afterclass.dateTime.end
orclass.dateTime.start
expires. -
object.validTimeInterval.end.date
expires. The pass moves to "Expired passes" anytime up to 24 hours afterobject.validTimeInterval.end.date
expired. -
The
object.state
field is marked asExpired
,Inactive
, orCompleted
.
Link to a saved pass
Once a user has a pass saved, reference its objectId
in order to link to the
pass.
Use the following link to reference the pass:
https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}
The pass can be viewed with the Google Pay app or a web browser.
Link out from a saved Google Pay pass
You can link to your app or website below the header of a saved Google Pay pass. This feature is available for all types of Google Pay passes.
Request access
Request access with the support form for in-store merchants. Keep the following in mind:
- You must share your issuer ID in the form.
- Under Issue type, select "Technical/API Integration."
- Select Link your app or website below the Google Pay pass.
Set the app link on your Google Pay pass
For a given Google Pay pass, define appLinkData
to set the URI of your app or
website. The URI can be any format, but we recommend that you use a
dynamic link.
The format and context of the appLinkData
field can be seen in the following source
code:
{ "id": string, "classId": string, … … … "appLinkData": { "androidAppLinkInfo": { "appLogoImage": { "sourceUri": { "uri": string } }, "title": { "defaultValue": { "language": string, "value": string } }, "description": { "defaultValue": { "language": string, "value": string } }, "appTarget": { "targetUri": { "uri": string, "description": string } } } } … … … }