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:
- Authentication flow: Identifies and verifies (authenticates) the user.
- 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.
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:
- Authentication flow
- Association flow
- Funds Transfer flow
- Reserve Capture flow
- Refund flow
- Fraud Reporting flow
- 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.
All timestamps are represented as milliseconds since the Unix epoch (Jan 1, 1970) in UTC.
- April 23, 2019 8:23:25 PM GMT = 1556051005000 milliseconds
- August 16, 2018 12:28:35 PM GMT = 1534422515000 milliseconds
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.
- USD$1.23 = 1230000 micro USD
- USD$0.01 = 10000 micro USD
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.
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.
Form of Payment. This is more general than an instrument. Visa, MasterCard, and PayPal are all FOPs.
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.
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.
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 two ways to identify and authenticate the user:
- SMS-MO Authentication (production)
- Simulated SMS-MO Authentication (sandbox)
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.
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
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.
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:
- Negotiates an identity called a token to represent this user.
- Provides account information to inform Google's risk engine.
- Gathers necessary first time setup information to create and establish the
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
Association flow overview
- A Google user with an email address of email@example.com want to add her InvisiCash account to the Google Play Store so she can use it for purchases.
- The Google Play Store opens up the InvisiCash app in order to authenticate.
- The user logs into her InvisiCash account with the email address firstname.lastname@example.org. It may be that she uses her Gmail email address for both if that is her login for her InvisiCash account.
- The InvisiCash app sends the authentication ID back to the Google Play Store.
- The Google Play Store sends the authentication ID on to the Google Servers.
- 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.
- The InvisiCash servers store the Google Payment Token (
GPT), and the association ID. Both are now associated with Sally’s InvisiCash account.
- InvisiCash approves this association. Then Google’s Servers create an instrument that may be used for future purchases.