Google Standard Payments:

Tokenized FOP

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. Purchase flow
4. Refund flow
5. 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. Tokenized FOPs support two ways to identify and authenticate the user:

1. SMS-MT OTP Authentication (SMS Mobile Terminated, One-Time Password)
2. Redirect Authentication

When onboarding, integrators work with Google to choose the authentication mechanisms that best fit their product.

Authentication flows can be used in two contexts: first, to identify a new customer in order to make an association, and secondly, to challenge a user for the credentials of an existing instrument. The result of the authentication flow can be used as input to multiple flows, such as the association flow, refresh token flow, challenged purchase flow, and so on. Additionally, the authentication flow can be used in standalone mode, not tied to any subsequent flow.

SMS-MT OTP Authentication

In this authentication mechanism, the user enters a phone number in a Google UI. Google sends this phone number to the integrator (via the sendOtp method). The Integrator sends a one-time password to the user. The user enters the password into the Google UI which sends it along to the integrator. This triggers a success response by the Payment Integrator.

When SMS-MT OTP authentication is used in standalone mode, the value of the OTP is sent to the integrator using the verifyOtp method. This method verifies the OTP provided was the one sent.

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.

Note: If the integrator is going to use SMS-MT OTP during the redirect, Google strongly suggests leveraging the aforementioned SMS- MT OTP Authentication. It provides the user with a more seamless experience on Google properties.

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

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.

   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.

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.