Enrollment and sign-in

The loyalty enrollment and sign-in feature allows users to search for your loyalty program and join or sign-in to their account from Google Pay. Users will be directed to your mobile-friendly website to complete the process, after which they can easily save their card to Google Pay.

This guide provides an overview of the implementation steps required to enable your loyalty program for this feature.

Overview

To get started, make sure you have previously set up your project and have access to the Google Pay API for Passes. If not, complete the instructions in the Links and web buttons.

You must follow these four steps to implement the enrollment and sign-in feature for your loyalty program:

  1. Set up a test environment in Google Pay for testing your enrollment/sign-in flows.
  2. Develop enrollment/sign-in pages that leverage Google Pay user data.
  3. Implement push back of loyalty card to Google Pay after enrollment/sign-in.
  4. Request verification and activation.

Set up a test environment in Google Pay

Determine the enrollment and sign-in URLs, your program logo, and the desired user fields. Then, use the discoverableProgram nested fields in the loyaltyclass to set the appropriate values.

Setting the values in the discoverableProgram will create a draft version of your enrollment/sign-in enabled loyalty program. To make sure this is visible to testers, make sure the testers have access to your Google Pay API for Passes Merchant Center and fill out the registration form. This will allow you to verify the correct functionality of your implementation during the development process.

Develop enrollment and sign-in pages that leverage Google Pay user data

When a user chooses to sign-in or enroll for your loyalty program, they are directed to a tailored page on your website in order to complete the enrollment or sign-in process. If a user chooses to enroll, Google Pay will request the user to approve sharing their user data with you.

You are required to provide one of the two pages, or both, that allow users to complete these actions.

  1. A sign-in URL where a user can sign in to an existing account.
  2. An enrollment URL where a user can create a new account.

Your sign in and enrollment pages must meet the following requirements:

  • Provide a mobile-friendly user experience.
  • Minimize the number of required fields during the enrollment process.
  • Allow the user to complete sign-in or enrollment within one single page.
  • Use HTTPS encryption with a valid certificate to ensure user data is transmitted securely.
  • Ensure at least 99.9% uptime of your sign-in and enrollment pages.

In addition to the requirements above, we recommend you allow users to enroll in your loyalty program without filling out any form or keeping the page to just your terms of service acceptance.

  • By leveraging the user data provided, you can create an account and immediately push back their loyalty card.
  • You can subsequently email the user a one-time password, or a link to configure their password and optional account details.
  • This reduces the chance of users abandoning their enrollment process, as every additional step can lead to additional drop-out.

When presenting the sign-in or enrollment page, Google Pay will create an Android WebView and a POST request is made to your provided URL. User data is provided in the parameter userProfile which is included in the POST request using the application/x-www-form-urlencoded content type and UTF-8 encoding. The value of the userProfile parameter is a Base64 encoded JSON object.

Depending on the action chosen by the user and the fields you have specified to request from the user, the JSON object may contain the following fields.

Field Enrollment Sign-in
email
firstName  
lastName  
addressLine [1-3]  
city  
state  
zipcode  
country  
phone  

Refer to the below for a decoded sample JSON object contained in the userProfile.

Resource

{
  "firstName": "Jane",
  "lastName": "Doe",
  "addressLine1": "1600 Amphitheatre Pkwy",
  "addressLine2": "Apt 123",
  "addressLine3": "Attn:Jane",
  "city": "Mountain View",
  "state": "CA",
  "zipcode": "94043",
  "country": "US",
  "email": "jane.doe@example.com",
  "phone": "555-555-5555"
}

Implement immediate push back of loyalty card to Google Pay

Once authenticated (sign-in), or after account creation (enrollment), your page should immediately push back the user’s loyalty card to Google Pay.

You can push back the loyalty card to Google Pay by redirecting to a link that follows the structure below. If you are not yet familiar with generating a JSON Web Token (JWT) for the LoyaltyObject that represents your user’s loyalty card, refer to Generate a JWT that represents the object.

https://pay.google.com/gp/v/save/{jwt_generated}

The safe length for a URL is 2000 characters. Your links should remain below this limit. Objects encoded in JWTs should be small, containing only data that is specific to the user. Try to keep most data in the object's class, creating it before making the JWT. For larger objects that do not fit the limit, consider first creating the object in the Google Pay API for Passes and sending only the object ID in the JWT.

Typical Communication Flow

The communication flow for a user completing enrollment or sign-in is illustrated in the following image. All actions between "Your Server" are your responsibility to implement.

Enrollment signin flows

Request verification and activation

Once you have completed development work and tested your enrollment/sign-in flows, submit a request through the registration form.

After a full review of your implementation that confirms correct functionality in combination with the Google Pay app, the loyalty enrollment/sign-in feature will be publicly launched for your loyalty program. This will allow any user to see the program and make use of this functionality.

In order to ensure an optimal user experience, recurring checks of your enrollment/sign-in implemention will be conducted to ensure ongoing compliance with the feature requirements. You will be notified in the event of discrepancies and the sign-in/enrollment functionality may be disabled until the issue is resolved.

Frequently Asked Questions

  • Are there any requirements for the images used in my loyalty program?
    • Yes, your images should be hosted on HTTPS location as they will not be visible in Google Pay otherwise.
  • Are there any tools that simplify the implementation and debugging of JWTs?
    • Yes, platforms such as www.jwt.io allow you to decode and debug your tokens during your development process, allowing you to verify the content you are submitting. Do note that Google has no affiliation and does not specifically recommend any of such third parties.
  • How do we correctly handle the Base64 encoded userProfile data?
    • Ensure that you are using UTF-8 encoding throughout your process. The JSON string is first UTF-8 encoded and subsequently encoded using android.util.Base64 with the options NO_WRAP and URL_SAFE. This corresponds with RFC 3548 section 4.

Sample Enrollment Flow

Loyalty enrollment flow