Google Standard Payments: Banking FOP

Overview

A banking form of payment (FOP) is one where Google and the Payment integrator (Partner Bank or integrator) perform a one-time exchange of account identity credentials and user authorization in order to establish an Association between Google and the Bank. Later on, a reference to this association can be presented back to the integrator to allow moving money from of the user's account to another bank account.

Google uses two flows to establish this exchange of information:

  1. Authentication-Authorization flow: authenticates the user and obtains authorization from the user to establish this connection.
  2. AssociateAccount flow: establishes an association for previously identified and authenticated users. This is done through a method call which establishes the association between Google and the Payment integrator. This flow is also referred to as association.

Once the association is established, Google will use it during money movement for a fast and seamless checkout experience for our users. Google calls this an instrument. A Google customer has one or more instruments. An instrument is a way to pay for services and goods within Google's various ecosystems and marketplaces.

These flows are described in more detail in the sections below. The examples in the sections below walk you through a fake bank called InvisiBank.

Important Concepts

Symbols & Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in these documents are to be interpreted as described in RFC 2119.

Timestamps

All timestamps are represented as milliseconds since the Unix epoch in UTC.

For example:

  • August 14, 2010 16:30:00.00 AM GMT = 1281803400000
  • November 6, 2007 9:37:00 PM MST = 1194410220000

Amounts

Monetary values in this API are represented using a format called "micros", a standard at Google. Micros are an integer based, fixed precision format. To represent a monetary value in micros, multiply the standard currency value by 1,000,000.

For example:

  • USD$1.23 = 1230000 micro USD
  • USD$0.01 = 10000 micro USD

Idempotency

All method calls within this API must have idempotent behavior. Simply put, integrators should not attempt to reprocess any request already successfully processed; the response for the successful processing should be reported instead. All methods have a common RequestHeader which contains a requestId. This requestId is the idempotency key for all calls.

For any non terminal answer (a non HTTP 200), it must not be idempotently processed. So a request that previously got a 400, when called a second time must not idempotently return 400, it must be re-evalutated. At re-evaluation, it could return a 400 or be processed successfully.

For more information on idempotency see this detailed guide.

Authentication-Authorization Flow

The purpose of the authentication-authorization flow is to identify and authenticate the user to the integrator and to obtain authorization from the user to perform the other actions in the flow. Authentication-Authorization is handled via a redirect. This can either be to an app or a web redirect.

Redirect Authentication-Authorization

Redirect authentication-authorization happens by Google redirecting the user to an integrator-owned application. That application could be a web application or an Android application.

Android and Web redirects behave similarly. Here, Google redirects the user to the integrator's app. The integrator identifies and authenticates the user in whatever form is most natural for that integrator. Once authenticated, the integrator redirects the user back to Google's UI to finish the association. Upon redirect, Google provides a requestId in order to identify this authentication session. That identifier is then used as authentication proof and identity during Association.

Integrators that choose this flow must provide a web authentication URL as this is the most common denominator across all surfaces (Desktop, Mobile). However Android authentication is strongly recommended as it provides the best user experience on Mobile.

Depending on the device context and the apps installed, Google UIs will choose the web or the Android App redirect.

This authentication mechanism provides the integrator with the most freedom. There are many ways to authenticate and identify a user. Username + password, biometric information and security questions are all viable solutions as well. Google doesn't intend to dictate how a integrator verifies a user. The integrator takes care of authenticating the user. By using this method, Google intends to leverage the integrator's various user interfaces to authenticate the user and simply provide Google with proof of authentication.

In addition, we will pass a list of Authorization scopes that should be shown to the user to obtain authorization for each of these actions (e.g. in the AssociateAccount flow, we need authorization to associate the user's account with a Google account).

For the Association flow, this flow will also allow a user to select the account that they have with the Payment integrator that they would like to be the target for the AssociateAccount call that will follow this flow.

For more information on authentication see this detailed guide.

Association Flow

The purpose of the association flow is to establish an association in order to create an instrument. This flow:

  1. Creates an association in the integrator's system linking the account which was selected during the Authentication-Authorization flow to a specified Google account.
  2. Negotiates a reference that will be used to refer to this GPT.
  3. Provides account information to inform Google's risk engine.

The established reference to the GPT is agreed on by both Google and the integrator.

The association flow requires that Google provide proof of authentication/authorization to the integrator. Prior to every association flow, Google invokes the authentication-authorization flow to acquire this proof.

The diagram below shows the sequence of calls for the authentication-authorization flow and association flow

Association Flow

For more information on authentication see this detailed guide.