Redirect Authentication Flow

Authentication User Flow

Overview

The purpose of the Authentication flow is to identify and authenticate the user to the Payment Integrator (integrator).

Authentication is an input to other methods. Particularly for associateAccount and capture. This means that the proof of authentication is used as an input (parameter) to those two methods.

Google can also use the authentication flow in standalone mode to verify a user. In this case it is not used as an input to any other flow, but only to verify that a user is able to authenticate this identity.

Keep in mind that when you are onboarding, Google will work with you to choose the authentication mechanism that will best fit your product.

How the flow works

There are two ways to authenticate a user, each with its own flow. At the time of integration, the integrator must determine which to use.

  1. Redirect authentication
  2. SMS-MT OTP authentication

Redirect authentication

A Google user who needs authentication may be redirected to the integrator’s app or their website to have their identity verified. Here is a brief overview of the steps in this flow:

  1. Google redirects the user to the integrator’s web or Android app where they can be authenticated.
  2. To authenticate, the authentication requestId (from AuthenticationRequest) is used as proof of authentication.
  3. This results in a signed response, called the AuthenticationResponse.
  4. Afterwards, the app or website redirects the user back to Google.

Note: In standalone mode, the signed response (step 3), and the gspResult determine if the authentication has been successful.

The redirect authentication uses an HTTP GET method, with parameters encoded in the URL for a web application. It uses an Android Intent for an Android application authentication. For more details on encoding, see Web Authentication, and for Android intent parameters, see Android Authentication.

The result from each of these authentication mechanisms is a signed response called the AuthenticationResponse. This intent should include the encrypted, encoded Google Standard Payments Authentication Response (gspAuthenticationResponse) to communicate a successful authentication. If used in standalone mode, the gspResult and signature are used to determine the successful authentication.

The following sequence diagram shows the interaction between the user's browser, Google, and the integrator's web application:

Redirect-Web authentication flow

Web Authentication Flow

Here is a list of the objects and what they represent:

  • User: This is the person who wants to add a payment method to their Google account.
  • Google UI: In this case, the web interface at Google, where the customer begins to setup a payment method.
  • Google Server: The backend server at Google that does the authentication check, along with other authentication tasks.
  • Payment Integrator Web: The website of the integrator where the user has an account.

For this authentication flow, we already assume the user is on Google’s website (Google UI) and is trying to add a payment method. Here is where everything starts.

  1. The Google UI creates an authentication URL which is sent to the Google Server (backend). This is what triggers the authentication process.
  2. The Google Server creates an authentication request (AuthenticationRequest).
  3. The authentication request sent to the Google UI.
  4. The user receives the prompt that they need to authenticate their ID with the integrator.
  5. The user responds that they want to authenticate, which sends that message to the integrator’s website.
  6. The Payment Integrator’s website asks for verification of the user’s identity.
  7. The user provides proof of their identity, which is sent to the Payment Integrator’s website.
  8. The integrator creates a response (authenticationResponse) to the evidence they were given (with the authenticationResponse encoded in the message).
  9. This response URL is sent to the user.
  10. The response URL is immediately sent from the user to the Google UI.
  11. The Google UI sends the response the Google Server.
  12. The Google Server interprets the response as verified.

The next sequence diagram shows the interaction between the user's phone, Google, and the integrator's Android application:

Redirect-Android app authentication flow

Android app authentication flow

Note: neither of the above two diagrams illustrate the use of the authenticationId as input to another flow, but that is most often how it will be used.

Here are the objects and what they represent:

  • User: This is the person who wants to add a payment method to their Google account.
  • Google UI: In this case, the app interface, where the customer begins to setup a payment method.
  • Google Server: The backend server at Google that does the authentication check, along with other authentication tasks.
  • Payment Integrator APK: The integrator’s app where the user has access to their integrator account.
  • Payment Integrator Server: The backend server of the integrator where the user’s information is stored.

Since this is an authentication flow, we already assume the user is using an app (Google UI) and is trying to add a payment method. This is where initialization begins.

  1. The Google UI creates an authentication call which is sent to the Google Server (backend).
  2. The Google Server create an authentication request (AuthenticationRequest).
  3. The Google Server sends a call APK to the Google UI (app), requesting authentication.
  4. The Google UI sends the user information to the Payment Integrator APK (AUTHENTICATE_V1(authReq)).
  5. The Payment Integrator APK sends the request (authReq) to the Payment Integrator’s server.
  6. The Payment Integrator Server sends a challenge back to the Payment Integrator APK.
  7. The Payment Integrator APK sends the challenge back to the user.
  8. The user provides proof of their identity, which is sent to the Payment Integrator APK.
  9. This proof is then sent to the Payment Integrator Server.
  10. The Server creates a signed authenticationResponse.
  11. The authentication response is successful, and an authResp message is sent to the Payment Integrator APK.
  12. The success message (authResp) is sent to from the Payment Integrator APK to the Google UI.
  13. The Google UI sends the response to the Google Server.
  14. The Google Server interprets the successful response.

Authentication and Re-authentication

There are two points in time that authentication can occur:

  1. Initial authentication—used to identify and authenticate a user. The initial authentication is used as input to the associateAccount method.
  2. Re-authentication—used in all other contexts, such as standalone or as input to capture.

Re-authentication differs from initial authentication. It never desires to re-identify a user, simply to re-authenticate. Re-authentication is used by Google to challenge the user to prove they own a particular account and this happens at Google's discretion.

In this process a reference, called the associationId, is provided to the original association (from the association flow). This is provided through the call to the associateAccount method during the association flow. The associationId identifies the account to challenge against. For security, the user must not be able to change the account being challenged.

For SMS-MT OTP re-authentication, Google holds the phone number provided during the original call to sendOtp as a fixed number. This cannot be changed, again for security.

Here's an example flow where Google decides to challenge (re-authenticate) prior to making a purchase:

Re-authentication flow

Re-authentication flow

The list of objects and what they represent are as follows:

  • User: This is the person who wants to make a purchase.
  • Google UI: In this case, a Google website or phone app where the customer begins to make the purchase.
  • Payment Integrator UI: The customer facing website or app where the user can access their account information with the Integrator.
  • Google Server: The backend server at Google that does the re-authentication check, along with other tasks.
  • Payment Integrator Server: The backend server of the integrator where the user’s information is stored.

The re-authentication flow begins when a customer begins to make a purchase. This initializes a flow to re-authenticate the user.

  1. The user decides to purchase an item or service.
  2. The request is sent from the Google UI to the Google Server.
  3. The Google Server sends back an authentication request (autheticationRequest) to the Google UI.
  4. The Google UI sends a request to the Payment Integrator UI to authenticate (associationId, authenticationRequest) the user.
  5. The Payment Integrator UI looks up the user to verify their identity (LookupIdentity(associationId)).
  6. The Payment Integrator UI prompts the user for credentials on their UI (integrator’s website or app).
  7. The authentication response is sent to the Payment Integrator Server.
  8. The signed authentication response (authenticationResponse) is sent back to the Payment Integrator UI.
  9. The authentication response (authenticationResponse) is sent from the Payment Integrator UI to the Google UI.
  10. The Google UI sends the response with the purchase information to the Google Server.
  11. Google’s Server sends a capture message (to find available funds) to the Payment Integrator Server (authenticationRequestId, GPT, amount).
  12. The Payment Integrator Server sends a message of success back to the Google Server.
  13. Google’s Server sends a message of success to the Google UI.
  14. The Google UI delivers the item(s) to the customer (or notifies them that they will soon be delivered).

Best practices and other considerations

Choice of platforms

Providing a mobile app and desktop web authentication flow will allow the integrator to reach the most users. Google strongly recommends that integrators support the Android application as it provides the best user experience resulting in the highest conversion rate. The parameters passed in the authentication APIs for the web and Android applications are the same.