Introduction to Google Standard Payments for Carriers

In the Google Standard Payments world, Carrier Billing is considered a tokenized form of payment (FOP), meaning Google and the Payment Integrator perform a one-time exchange of account identity credentials in order to establish a token. Later on, this token is presented back to the Payment Integrator to identify the account to charge.

Other forms of payment also use tokenization, so we have a general overview of Tokenized FOPs that is all mostly relevant to Carrier Billing. The Authentication, Association, Purchase, and Remittance flow are all described in more detail in that overview. This page provides more details in a Carrier Billing-specific context.

Carriers onboard to Google Standard Payments by implementing the APIs that make up the following flows:

Flow Description DCB3 Spec Equivalent
Authentication Identifies and authenticates the user's account in the Payment Integrator's system that will be used to make DCB payments SMS-MO with GoogleUserToken
Association Exchanges a long-lived token that Google and the Payment Integrator agree can be used to make payments using the user's Payment Integrator account approveuser callback with OperatorUserToken and GetProvisioning()
FundsTransfer Synchronously moves funds out of the user's Payment Integrator account. Transfers liability to the Payment Integrator Auth() and CHARGE lines in batch request files
Refund Synchronously returns some or all of the funds associated a previous FundsTransfer to the user's Payment Integrator account. Transfers liability to Google REFUND lines in batch request files
Remittance API-based settlement, preferably on a daily basis Monthly invoice PDF, monthly invoice details file, daily recon file
UpdateAssociatedAccount Informs Google of changes to a user's Payment Integrator account (e.g., transaction limits or provisioning status) GetProvisioning() poll
Fraud Informs Google about transactions that were reversed due to a user dispute. This is used to improve Google's risk engine, but does not affect money liability None

Overall Comparison to DCB3 Spec

The Google Standard Payments spec solves the same problems that the DCB3 Spec solves. However, it uses different technologies and API designs that improve on the solution. Here are the major differences at a glance:

Stack Technology Comparison

All API communication is done using HTTPS POSTs with PGP-encrypted and signed JSON. This means that Google and the Payment Integrator each have only one PGP key to rotate. These technologies also have better support than SOAP. More details about the communication stack can be found here.

API Philosophy Comparison

DCB3 relies heavily on files to reconcile payment state. Google Standard Payments has no files. API calls are retried idempotently and indefinitely until a final state is determined.

Final states are truly final for a particular idempotency key. Bugs and indeterminate states are not modeled as declines, but rather as non-200 HTTP responses. This allows us to catch bugs more quickly and avoid masking them as declines.

New Features

Google Standard Payments supports new features, including:

  • Fraud API to inform Google's risk engine of fraudsters
  • Update Associated Account API to inform Google of provisioning, transaction limits, and account status changes
  • More authentication challenge-support during purchases, like USSD PINs
  • Daily remittance cycle

DCB3 to Google Standard Payments Terminology Map

In this documentation and the specification itself, you will see terminology that looks new but is actually just different words for existing concepts.

  • Carrier -> Payment Integrator

WARNING: To avoid confusion with the DCB integrator concept, this doc attempts to use "Payment Integrator" and "DCB integrator" rather than simply "integrator". However, the general Google Standard Payments documentation uses "integrator" liberally as a shorthand for "Payment Integrator"

  • Billing Agreement ID -> Payment Integrator Account ID
  • OperatorUserToken (OUT) -> GooglePaymentToken (GPT)
  • correlation_id -> requestId
  • Revshare -> fee

Authentication Flow

For a general overview of the authentication flow for Tokenized FOPs, see this page.

Carrier Billing Specifics

For Carrier Billing, the goal of the authentication flow is to prove that the user has control of the SIM card tied to their carrier account. Carrier Billing users can be authenticated using any of these three mechanism:

Payment Integrators can work with Google to choose the authentication mechansims that best fit their product.

Comparison to DCB3

The authentication flow replaces the approveuser callback to Google with OUT of the DCB3 spec.

In DCB3, authentication and association were combined into a single flow. In Google Standard Payments, authentication is a separate concern from account association.

Association Flow

For a general overview of the association flow for Tokenized FOPs, see this page.

The main difference between the association flow used for Carrier Billing instruments and the general Tokenized FOPs flow is that the proof of authentication provided in the associateAccount method will vary depending on whether the Payment Integrator requested an additional user challenge.

If the Payment Integrator responded that they desired an additional user challenge, then the proof of authentication will be whatever proof of identity is produced by the particular authentication mechanism that Google used for the additional challenge. For instance, the proof of authentication produced by the SMS-MT OTP mechanism is the requestId of a sendOtp method plus the OTP itself.

Instrument Attributes

The general Tokenized FOP overview's Instrument Attributes section discusses the concept of accountAlias, accountNickname and fullAccountNickname.

Carrier Billing Specifics

  • accountAlias should be the user's phone number. It will be used to help identify the instrument in the event the user calls Google support regarding their account.
  • accountNickname and fullAccountNickname are display names used to identify the instrument in UI.

Comparison to DCB3 Spec

The association flow replaces the following components of the DCB3 spec:

  • GetProvisioning SOAP call
  • GetSubscriberAddress SOAP call
  • Carrier-generated OUT

A big difference here is the fact that Google generates the Google Payment Token (GPT) during the association flow instead of the carrier generating it.

It is also important to note that unlike in DCB3 where OUTs are scoped to a particular BillingAgreementId, the GPT is not scoped to any particular PaymentIntegratorAccountID.

Refresh Token Flow

For a general overview of the refresh token flow for Tokenized FOPs, see this page.

Carrier Billing Specifics

For Carrier Billing instruments, we strongly discourage Google Payment Tokens ever expiring since it results in subscription orders being cancelled. Rather than expiring tokens and relying on the refresh token flow to fix them, your use case can often be accomplished using the account update flow described below instead.

Account Update Flow

The account update flow allows the Payment Integrator to inform Google about updates to the user's integrator account. These fields are originally supplied to Google during the association flow. Some examples of account data that the Payment Integrator might want to update include:

  • the user's monthly, daily, and per-item transaction limits
  • the user's integrator account's provisioning status
  • the user's integrator account type (pre-paid, post-paid, enterprise, etc..)
  • the user's 'accountAlias', 'accountNickname', or 'fullAccountNickname'
  • whether the user has set up, removed, or changed a pre-shared static PIN
  • whether the user has closed their account or changed their phone number -- invalidating the user's instrument in Google's system.
  • delete token flow

Comparison to DCB3 Spec

The account update flow replaces the following components of the DCB3 spec:

  • Polling of GetProvisioning SOAP call
  • Periodic token invalidation

Purchase Flow

For a general overview of the purchase flow for Tokenized FOPs, see this page.

Carrier Billing Specifics

Some carriers use USSD or another technology to collect a PIN from their users during each purchase. For these carriers, instead of calling capture() we call asynchronousCapture() and we allow 30 seconds for the carrier to prompt the user for their PIN and finalize the capture. When the final state of the payment is determined, the carrier informs Google of the result by calling captureResultNotification().

Comparison to DCB3 Spec

There are major changes here.

  • Single, synchronous method call -- capture() instead of auth() + batch file
  • No batch files at all
  • No cancel() method (capture + refund instead of auth + cancel)
  • No user_message field in response -- decline codes are mapped to Google-owned messages localized to the user's account language.
  • Key terminology changes:
    • CorrelationId -> requestId
    • BillingAgreementId -> paymentIntegratorAccountId
    • OperatorUserToken -> googlePaymentToken

Challenged Purchase Flow

Development is ongoing to support a purchase flow that includes an authentication challenge to the user before each purchase. Most authentication methods that can be used before the association flow could also be used before the challenged purchase flow to provide additional user authentication.

Refund Flow

For a general overview of the refund flow for Tokenized FOPs, see this page.

The tokenized FOP supports a single message refund flow. The refund method supports refunding a full purchase or refunding a portion of a purchase. Multiple partial refunds can refund a single purchase.

Carrier Billing Specifics

There is nothing special about Carrier Billing instruments in the refund flow.

Comparison to DCB3 Spec

Refunds are triggered by a synchronous API call instead of a file. Also, multiple, partial refunds can be created for a single original payment instead of only supporting a single, full value refund.

Remittance Flow

For a general overview of the remittance flow for Tokenized FOPs, see this page.

The remittance flow is how Google and the Payment Integrator perform settlement. Google is the accounting system of record and does accounting for remittance transfers. On a regular basis, Google sends a remittance statement to the Payment Integrator. The statement provides a summary of the amount that the Payment Integrator owes to Google along with instructions on how to pay Google. In order for the Payment Integrator to reconcile, the Payment Integrator can query Google for the transaction level details that make up the remittance statement.

Carrier Billing Specifics

Carrier Billing remittanceStatementDetails include additional fields not listed in the remittance flow's API definitions yet. These include:

  • revshareCategory
  • itemPrice
  • tax
  • timestamp

For carriers with a 50/50 revshare split agreement with Google, the fees presented in the remittanceStatementDetails are aggregated per revshareCategory rather than presented on a per-event basis.

Comparison to DCB3 Spec

The remittance flow replaces the following concepts in the DCB3 spec:

  • Monthly ChargeReport/PaymentReport PDF
  • Monthly invoice details CSV file
  • Daily recon CSV files

The major differences here are the removal of any files and support for daily remittances. Instead of files, the amount to remit is delivered via a synchronous API and another API supports querying for details about the remittance statement.

Fraud Reporting Flow

The fraud reporting flow allows a payment integrator to inform Google of potentially fraudulent transaction by calling into the fraudNotification method. This flow is used to update Google's internal risk engine and does not initate any money movement.

Carrier Billing Specifics

There is nothing special about Carrier Billing instruments in the payment reversal notification flow.