Account ID
The Account ID is sent back from the integrator's server during the association flow; it is used to help Google identify the underlying account in two ways. First, to identify multiple instruments that use the same underlying user account in order to assess risk and fraud. Secondly this is used by Google customer service agents to identify this account. This value must uniquely identify the user account across association requests, and it must be immutable on the particular account and it must be identifiable by the user.
For example, if an integrator uses an email address for identity, this can be the email address. However if the integrator uses an email address for login but that address can be changed, then the email address is a poor choice for the account ID. Whatever is chosen, its value must be the same for multiple association attempts with the same payment integrator user identity.
Android Application Package (APK)
The package file format used by the Android operating system for distribution and installation of mobile apps.
API Versioning
This specification supports versioning. Supported versions are configured on the Google server. When moving from version N to M (where M is a major version greater than N) the integrator must support both N and M until Google verifies that all traffic has been migrated to M. The versions are identified differently based on the context. Android APIs and WebRedirect APIs will pass the API version as a parameter to the request. The server-to-server calls pass the version as a portion of the URL path.
Versions are not fixed by flow. So during migration from N to M, an integrator may see a capture with version M and a refund with version N for the same transaction. During association the integrator may get an authentication request of version M with an association request of version N.
Association ID
The associationID identifies the association between the customer's account
and the Google instrument. The associationId is very similar to the GPT. In
fact, it has the same lifetime as a GPT and has a 1:1 cardinality to a GPT. The
associationId differs from the GPT in its sensitivity. The GPT is a sensitive
token that is used for payments. The associationId is a public identifier that
represents the same relationship, but isn't as sensitive in nature.
The associationId is passed to the payment integrator during
associateAccount. This same value is passed during re-authentication to the
integrator. This allows the integrator to have context about what account must
be authenticated. If the Association ID is passed in, the same account that was
identified during the original association must be pre-filled and authenticated
against.
The payment integrator is expected to store all association IDs and associate them with a particular integrator account for the lifetime of the contract between the integrator and Google.
Authentication Request Id
The methods refreshToken, associateAccount and (optionally) capture take an
reference to an authentication. This reference is in the form of the requestId
of the particular authentication Google is referring to. This field is to be
used by the payment integrator to verify that indeed the method was proceeded by
a successful authentication.
Capture methods can have an authentication requestId populated. This happens
in two cases. If Google authenticates the user just prior to a capture, Google
populates the authentication requestId field. Also, Google often authenticates
the user at set up time when an automated payment schedule is set up. Google
writes the authentication requestId down on that schedule and sends the
requestId along with every capture associated with that particular schedule.
Payment integrators are expected to store all authentication requestIds for 30
days. If a payment integrator wants to audit the authentication requestIds
that can be present on a capture request, including those included in payment
schedules, then the integrator must store all authentication requestIds for
the lifetime of the contract between the integrator and Google.
Company
A company is a concept defined within Google's configuration and contract. A company defines the relationship between the integrator and Google. PGP keys and (optionally) SSL Root CAs are associated with the company. Most importantly a company is associated with one or more payment integrator account ids. GPTs created within a company mostly work for all payment integrator account IDs within the company. Some exceptions do apply. For example, if the GPT is associated with an account denominated in one currency (and does not support FX fees) and is trying to make a purchase on a payment integrator account ID in a different currency.
Form of Payment (FOP)
All transactions include one or more forms of payment (FOP), such as a credit card or Electronic Funds Transfer, which are used either by users to pay Google for product or services or by Google to pay users in the case of AdSense users and Google Play developers. Forms of payment are also often called Payment Instruments, Instruments, and Payment Methods.
Google Payment Token (GPT)
GPT is a random, web-safe base64-encoded value generated by the Google server at association time and passed to the integrator server. GPT is a private identifier that represents the linkage between the user's account with the integrator and the Google instrument. A GPT is a token that replaces user credentials or an account ID. This token is used during buy-flows to identify the account to credit or debit and is secret to both the parties. GPT must never be sent in clear text and must be encrypted to ensure privacy.
GPT is different from associationId because associationId is not protected
and is freely passed through public means (URLs, insecure connections). GPT is
only known to Google and the integrator.
The payment integrator is expected to store all GPTS and associate them with a particular integrator account for the lifetime of the contract between the integrator and Google.
Idempotency
An idempotent operation can be applied multiple times without
changing the result or having new side effects beyond the initial application
of the operation. Typically idempotency uses a “key” to identify the same
request. All of the requests defined between the two servers use an idempotency
key defined in the request header. The request header has a request ID that is
used as an idempotency key. The request ID is globally unique. Idempotent
requests must be exactly the same JSON body with one exception. The
requestTimestamp will be different for every request. This is an important
distinction. The requestTimestamp is the time the server sent this request. And
is unique per attempt. This helps reduce the ability for replay attacks.
Likewise, an idempotent response must be exactly the same JSON body except the
responseTimestamp will be different for every response.
All server-to-server methods except for the Echo method must be idempotent. Authentication requests to the integrator's UI (be it Android or Web) are not idempotent.
For examples of idempotent behavior, see the reference doc.
Identifier (ID)
Identifiers represent a transaction or communication between the payment integrator and Google.
Instrument
The instrument represents a stored method-of-payment associated with a single Google customer. Examples of instruments include:
- A credit card number on file
- A bank account & routing number
Users can have multiple instruments associated with their Google identity.
Micros
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
Payment Integrator
The external integrator that processes payments for a user transaction.
Payment Integrator Account ID
This identifier represents constraints around the contract between Google and the integrator. The Integrator Account ID is generated by Google and assigned to the integrator during setup time. Typically this is referred to as a "MID". All requests and responses must include this ID. This identifier is opaque and must never be parsed. The format of this identifier may not be consistent across all issued IDs.
This identifier never changes for the lifetime of a transaction. In the case of a capture and refund, the same identifier is used.
The constraints of the Integrator Account Id are defined by the contract itself. Generally, the constraints are around invoicing. For example an integrator supports CAD and MXN being invoiced as USD, but requires EUR transactions to be invoiced in EUR. In this case two different payment integrator account IDs will be used, one for USD invoicing and the other for EUR invoicing.
The identifier can be phased out in favor of new identifiers. In the case where
an identifier is being deprecated, Google will stop initiating captures to that
identifier. However the integrator must honor refunds for transactions made
against that identifier for one year from the last capture initiation (capture
initiation defined as the requestTimestamp found in the requestHeader).
PII
Personally Identifiable Information (PII) is information that personally identifies an individual and any other data which can be reasonably linked to such information by Google, such as a user's name, email address, mailing address, or telephone number, either alone or in combination
Request Id
The requestId identifies all communication between Google and the payment
integrator.
SPII
Sensitive Personally Identifiable Information (SPII) is a subset of personally identifiable information (PII) that presents a high risk to the user if it is compromised or misused. SPII often has restrictive handling and storage requirements imposed by legal, regulatory, or compliance entities.
Token
Tokens add an extra layer of security when sensitive credentials such as PII or SPII are exchanged between Google and the integrator.
User Address
At instrument creation time Google checks to see if the user is a Google Payments customer. This is independent of being a Google customer. In order to be a Google Payments customer, we need the user's billing address. Some regulatory agencies require us to know the full address of the user, while others require a subset of that address.
If the payment integrator has an address on file for this user, Google would like to get that address during the association flow in order to pre-fill the address form for the user. The user has the option to change that pre-filled in address. Pre-filling the user address decreases the friction in adding an instrument and increases conversion rate of users adding these instruments.
If the address is shared, Google also uses it as a calculation into their risk model. This allows Google's risk engine to understand the address the user says they are billed at while comparing that to the IP location the user is currently at.
Address sharing is purely an optimization. It is fine and expected that some integrators won't have a billing address for the user or cannot share this address.
Web-Safe Base64-Encoding
The encoding standard specified in RFC 4648 section 5, Base 64 Encoding with URL and Filename Safe Alphabet, also sometimes referred to as "web-safe Base64" or "base64url" encoding. (This is the same as the base64 encoding with URL and filename safe alphabet from RFC 3548 section 4.) All encrypted and signed values must be encoded using this standard.