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.
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.
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.
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
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
associateAccount and (optionally) capture take an
reference to an authentication. This reference is in the form of the
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
that can be present on a capture request, including those included in payment
schedules, then the integrator must store all authentication
the lifetime of the contract between the integrator and Google.
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.
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 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.
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
requestTimestamp is the time the server sent this request. And
is unique per attempt. This helps reduce the ability for replay attacks.
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.
Identifiers represent a transaction or communication between the payment integrator and Google.
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.
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.
- USD$1.23 = 1230000 micro USD
- USD$0.01 = 10000 micro USD
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
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
requestId identifies all communication between Google and the payment
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.
Tokens add an extra layer of security when sensitive credentials such as PII or SPII are exchanged between Google and the integrator.
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.
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.