Typical API flows

The following diagram illustrates a typical communication flow used to insert a class, save an object, and update an object. All actions between your server, the web browser, and Google Pay API for Passes are your responsibility to implement. The following diagram uses Loyalty as an example, but all other Passes could use a similar flow.

Figure 1. API flow diagram.

Typical API flow for JS buttons and JWT web links

The following outline explains the same process as figure 1 in more detail. It covers the typical API flow for JavaScript (JS) buttons and JSON Web Tokens (JWTs):

1. Loyalty card issuer creates a LoyaltyClass.
1. Your server defines the LoyaltyClass.
2. Your server makes a POST request to insert theLoyaltyClass in the Google Pay API for Passes server.
Note: If you use the JS button, this step doesn't necessarily apply. Since there's no character limit, you do not need to pre-insert the class. However, it's still better to pre-insert a class so that it can be used multiple times. This is often the best method to handle loyalty cards.
2. Your server has a service to generate a JWT for a LoyaltyObject for a particular LoyaltyClass. This object represents that user's loyalty card.
1. Your server uses a JWT to render a Save to Google Pay (S2GP) button:
• For websites, use our JavaScript button.
• For email, SMS, and native apps, use the JWT link with a S2GP button.
3. The user clicks or taps Save to Google Pay on the loyalty card issuer's website, email, native app, or SMS.
1. The user is taken to a landing page to save a LoyaltyClass object. The object to be saved is rendered on the landing page based on the JWT. If the button is tapped from a native app, the user is prompted to save the object in the Google Pay app.
2. The user clicks Save to Google Pay on the issuer's property to save the LoyaltyObject.
3. The LoyaltyObject is inserted to the Google server, then pushed to the Google Pay app. The LoyaltyObject is referred to as a "Loyalty Pass."
Note: After a user's save, or a server REST, inserts a LoyaltyClass or LoyaltyObject for the first time, subsequent JWTs with the same classID or objectID render what's already inserted in the Google Server. If you change information in the JWT for an existing classID or objectID, it doesn't update the information. See Step 4 on how to update existing classes and objects.
4. Card issuer updates card data:
1. The loyalty card issuer does a GET request of the LoyaltyObject with the use of the Object.id.
2. The loyalty card issuer updates the LoyaltyObject.
3. The loyalty card issuer makes a PUT or PATCH request to insert the updated LoyaltyObject on the Google Pay API for Passes server.
4. The LoyaltyObject is pushed to the Google Pay app.

"Skinny" JWT variation

Due to truncation by browsers, JWTs used in web links must not exceed 1800 characters. If this becomes a challenge, it might be best for you to insert both the class and object beforehand. Then, the JWT only needs to contain the object id field.

Note: Insert the class and object only after a user shows that they want to save a Pass to Google Pay. To initiate the skinny JWT save flow, we recommend that you define your own save link.

The following diagram shows an API flow to Add the Save to Google Pay button to your email or SMS.

Figure 2. Skinny JWT diagram.

JWT POST request API flow

It's often difficult to implement the backend work required to create and insert a class before an object is saved, but the JWTs are likely to exceed the 1800-character limit. This is most useful for event tickets and boarding passes, where many classes are created over time.

Note: The JWT POST request method can be used when you save from your app, but it cannot be used in SMS or email since it uses a POST call.

The flow, with a flight class as an example, is as follows:

1. Your server generates a JWT for both FlightObject and FlightClass. Both are defined in the JSON, and the FlightObject references the FlightClass.
2. This JWT is sent from your server to your client application, which displays a Save to Google Pay button. Be sure to use a button that follows the S2GP brand guidelines.
3. The user clicks the S2GP button in your client application.
   1. A POST request is made to the JWT endpoint. This inserts the class ID(s) and object ID(s). If the class ID(s) or object ID(s) in the JWT already exist in the system, they aren't inserted again. Review our API reference documentation on how to update existing classes and objects. If they've already been inserted, no error is thrown.
   2. The returned URI response is opened for the user so that they can save the pass. This URI is valid for a week after it's returned.

To implement the API, read Use the JWT POST request method.

Figure 3. JWT POST request diagram.

In figure 3, there aren't arrows between "Your server" and "Google server" in the save flow. This is the fundamental difference between the JWT POST and the JWT link and intent method. However, we recommend that you implement server-to-server communication to update Passes.