Association user flow

Overview

The purpose of the association flow is to establish a long-lived token (aka, an opaque identifier) that both the Payment Integrator (company setting up their form of payment within our system) and Google agree represents the link between Google's user account and the integrator's user account. This long-lived token is called the Google Payment Token (GPT). An instrument is a way to pay for services and goods within Google's various ecosystems and marketplaces. A Google customer may have more than one instrument.

How the flow works

  1. Google negotiates a token to represent a link between Google's customer and the integrator's user account.
  2. Google gathers the necessary first time setup information to create and establish the GPT.

Proof of identity and authentication must first be established through the authentication flow. The output of the authentication flow is passed to the associateAccount method. Then the association flow will associate the Google user account with the Google instrument. This sets up the instrument so it can be used for payments.

Here is a diagram which details the Association flow:

Association flow sequence diagram

Association flow diagram

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: The interface at Google where the customer begins to setup a payment method.
  • Payment Integrator UI: The integrator’s interface (web or Android) that the customer has access to for that account.
  • Google Server: The backend servers at Google that perform the authentication checks and associate the user’s integrator account with a GPT (Google Payment Token).
  • Payment Integrator Server: The backend server of the integrator where the user has an account.

This is an association flow, where the user’s Google account is being linked by a Google token to their integrator account. Here is how this flow works.

  1. The user initiates the flow in the Google UI (such as a web or app interface).
  2. The Google UI sends a message for Google’s Server to supply it with an authentication request (Request Authentication Data).
  3. The Google Server sends a request for authentication (authenticationRequest) back to the Google UI.
  4. The Google UI connects the user to the Payment Integrator UI (authenticationRequest).
  5. The user is prompted for their identity and credentials.
  6. The Payment Integrator UI sends the response to the Payment Integrator Server.
  7. The Payment Integrator Server authenticates the response and sends the authentication response (authenticationResponse) to the Payment Integrator UI.
  8. This authentication response is forwarded to the Google UI.
  9. The Google UI sends a message to the Google Server to verify the response from the Integrator (set up User instrument).
  10. The Google Server validates the response by verifying the signature, and then associates the user’s Account with the Payment Integrator with a GPT and association ID (authenticationRequestID, associationID) at Google.
  11. A success message is sent to Google’s Server.
  12. A success message is sent to the Google UI.
  13. A success message is sent to the User, stating that their instrument is ready to use.

Best practices and other considerations

Multiple instruments

The integrator must allow for many GPT’s to be associated with a single user's integrator account. For example, this is needed if a user deletes their instrument and creates a new instrument with the same integrator user account.

It’s possible for two Google customers to associate with the same user’s integrator account. If that is the case, each user would have a different instrument associated with each individual. For each instrument there is an independent association flow and a unique GPT.

Safety measures

If the integrator believes there has been an account takeover on a user's integrator account, new associations can be declined for that account and existing instruments that have already been associated may return decline codes during future purchases.

GPT lifespan

The GPT is intended to be long lived, and by default has no expiration. Google strongly recommends a GPT that does not expire. This allows for an uninterrupted purchase experience by the user.

For those integrators that cannot support a token that has no expiration, the integrator can provide the expiration time via the tokenExpirationTime field of the associateAccount method. Once a token is near expiry, Google will send the user through the refresh token flow in order to extend the token's lifespan.

Other identifiers

There are other identifiers besides GPT that are exchanged during association. Here is a list of these with links to more information.

  • AssociationId: A Google defined, public facing token, identifying the association between the customer's account at Google and the instrument. Whereas the GPT is only used in server to server requests, the AssociationId is the client equivalent. (See the glossary entry for more information).
  • AccountId: A vendor defined identifier (often an account number), used to discover fraud and understand account relationships. Google's customer operation agents also use it to identify, and then help diagnose customer issues. (See the glossary entry for more information).
  • AccountNickname (or fullAccountNickname): A string that vendors use to identify their customers. It is used for display purposes as well. The AccountNickname is masked by the vendor for SPII sake, the fullAccountNickname is not masked.