Overview

Overview

A tokenized FOP (form of Payment) is one kind of payment integration into the Payments Platform. For a user to make a payment with this FOP, Google and the Payment integrator must perform a one-time exchange of account identity credentials. This in turn goes through the flow of establishing a token, representing that form of payment for that particular user. This token can then be used for payment over and over. Currently there are 2 versions of these APIs. Version 2 supports mobile carriers and reference number providers. All other tokenized FOP providers should implement version 1. The rest of this document is focused on version 1.

Google uses two flows to establish identity and create this token:

1. Authentication flow: Identifies and verifies (authenticates) the user.
2. Association flow: Establishes a token for a user (new or previously identified and authenticated). This token represents a particular form of payment by a particular user. The token may then be used in future purchases.

Once the token is established, Google will use it during the purchase flow for a fast and seamless checkout experience for the user. Google uses this token to represent an instance of a payment method by a customer. This is also called an instrument. A Google customer may have more than one instrument to pay for goods and services.

Finally, all movement of money between the integrator’s bank and Google’s bank is done in the remittance flow.

1) The user selects a product to buy

2) Next, they select a payment method

3) Now, they add a new payment method

4) They are redirected to authenticate

5) Finally, they are authenticated and can purchase

This diagram illustrates a broad overview of the flows:

Tokenized FOP overview

At a high level, adding your service as a form of payment to Google products involves these flows:

1. Authentication flow
2. Association flow
3. Funds Transfer flow
4. Reserve Capture flow
5. Refund flow
6. Fraud Reporting flow
7. Remittance flow

These flows are described in more detail in the sections below, and in even greater detail in the guides section.

Concepts and terminology

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 (Jan 1, 1970) in UTC.

For example:

• April 23, 2019 8:23:25 PM GMT = 1556051005000 milliseconds
• August 16, 2018 12:28:35 PM GMT = 1534422515000 milliseconds

Amounts

Monetary values in this API are in 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. Google will sporadically retry requests to ensure that transactions are in the same state on both sides. 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.

Any non terminal response (a non HTTP 200-success), must not be idempotently processed. So a request that previously got a 400 (bad request/failed precondition), when called a second time, must not idempotently return 400, it must be re-evaluated. At re-evaluation, it could return a 400 or be processed successfully.

For more information on idempotency see this detailed guide.

Integrator

A company who uses Google’s Payment Platform for their business. It could be internal (1P), such as Youtube or AdWords, It can also be an external (3P) business wanting to integrate their service to work with Google’s ecosystem.

FOP

Form of Payment. This is more general than an instrument. Visa, MasterCard, and PayPal are all FOPs.

Instrument

A particular instance of a form of payment by a specific customer. For instance, a user’s credit card, or their PayPal account. A tokenized FOP for a particular customer is also an instrument, because it is an instance of a form of payment for that customer, securely stored on our system.

Token

A representation, on Google’s system, of a specific user’s payment method. Since it contains all the information needed to make a purchase, a token is also an instrument. This may include such information as an account number a user has with their integrator.

Key flows

Authentication Flow

Authentication is the first flow that must take place. The purpose of the authentication flow is to identify and authenticate the user to the integrator. Authentication can happen a number of ways, depending on the environment (production vs. sandbox). Tokenized FOPs support three ways to identify and authenticate the user:

1. SMS-MO Authentication (production)
2. Simulated SMS-MO Authentication (sandbox)
3. Redirect Authentication (production)

Authentication flows are used to identify a new customer in order to make an association. The result of the authentication flow will be used as input to the association flow.

SMS-MO Authentication

In this authentication mechanism, the user requests to associate their carrier account with Google in a Google UI. Google generates an Authentication Request ID, which is sent from the user's phone to the Payment Integrator over SMS. The Payment Integrator decides whether to succeed or fail the authentication attempt, and notifies Google of this decision via the authenticationResultNotification endpoint.

This flow is described further on the SMS-MO Authentication Flow page.

Simulated SMS-MO Authentication

This authentication mechanism differs from the prior option in that the SMS is replaced by an HTTP call to the Payment Integrator-hosted simulateSms endpoint. This flow is meant to be used for testing and diagnostic purposes only, and is not a valid authentication mechanism in the production environment.

This flow is described further on the Simulated SMS-MO Authentication Flow page.

Redirect Authentication

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

Android and Web redirects behave similarly. 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 of identity during Association.

Integrators that choose this flow must provide a web authentication URL since this is the most common denominator across all surfaces (desktop or mobile). However, Android authentication is strongly recommended, providing 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, or biometric information and security questions, are both viable solutions. Google doesn't intend to dictate how an integrator verifies a user. The integrator takes care of authenticating the user. In this way, Google intends to leverage the integrator's various user interfaces to authenticate the user and simply provide Google with proof of authentication.

For more information on authentication see this detailed guide.

Association Flow

After the authentication flow via one of the mechanisms mentioned above, the user moves through the association flow. The purpose of the association flow is to establish a Google Payment Token (GPT) in order to create an instrument. This flow does the following:

1. Negotiates an identity called a token to represent this user.
2. Provides account information to inform Google's risk engine.
3. Gathers necessary first time setup information to create and establish the GPT.

The outcome is that the established GPT is agreed on by both Google and the integrator.

It is possible for two Google users to share the same user's account with the integrator. In this case, each user would have a different instrument. For each instrument there is an independent association flow, and therefore a unique GPT.

This illustration will walk you through a fake tokenized FOP called InvisiCash. This demonstrates the steps a user will go through for the authentication flow and association flow.

Association flow overview

Note: There are other ways of authentication. This is only one example. It may even be done on the web rather than through an app.

1. A Google user with an email address of [e-mail] want to add her InvisiCash account to the Google Play Store so she can use it for purchases.
2. The Google Play Store opens up the InvisiCash app in order to authenticate.
3. The user logs into her InvisiCash account with the email address [e-mail]. It may be that she uses her Gmail email address for both if that is her login for her InvisiCash account.
4. The InvisiCash app sends the authentication ID back to the Google Play Store.
5. The Google Play Store sends the authentication ID on to the Google Servers.
6. The Google Server sends a message to the InvisiCash server to associate the account. This association includes an Authentication ID, GPT (Google Payment Token), and association ID.
7. The InvisiCash servers store the Google Payment Token (GPT), and the association ID. Both are now associated with Sally’s InvisiCash account.
8. InvisiCash approves this association. Then Google’s Servers create an instrument that may be used for future purchases.