Top-Up Flow

Begin Top-up Redirect Flow

When Google detects that a user does not have sufficient funds, for instance if a capture is declined with INSUFFICIENT_FUNDS, Google can direct the user to top-up their account.

How the flow works

The top-up flow can take place on the vendor's Android app or the vendor's website, Google will redirect the user to the integrator's flow and at the completion of the flow, the integrator must redirect the user back to Google.

The top-up flow should be seamless, so the integrator must implement the top-up flow defined here in order to take advantage of this feature.

In both of the above cases, Google will redirect the user directly to the integrator's website without any previous server-to-server call from Google.

The integrator must implement an HTTPS protocol using GET. The GET parameters, outlined in Redirect Request Parameters, will contain information about the top-up attempt.

The integrator must support URL lengths of 2,048 chars. This includes the scheme, host, port, path and parameters. All parameters will be UTF-8 encoded prior to being URL-encoded.

Web Redirect

This section describes how the top-up redirect flow works when the user is sent to the integrator's website.

Web Top-Up Flow

Here is a list of the objects and what they represent:

  • User: This is the person who wants to top-up their account with the integrator.
  • Google UI: In this case, the web interface at Google, where the customer triggers the top-up flow.
  • Google Server: The backend server at Google that does the authentication check, along with other authentication tasks.
  • Payment Integrator Web: The website of the integrator where the user has an account.

Redirect Request

Here's an example of the URL to which the user will be redirected as part of the Top-up Redirect flow (also known as redirect request):

https://www.integratordomain.com/example/redirectEndpoint?callbackUrl=https%3A%2F%2Fexample.google.com%2Freturn%2Furl%3FredirectRequestId%3DcmVxdWVzdDE&gspTopUpRequest=VEhJU19JU19BTl9FTkNSWVBURURfUkVESVJFQ1RfUkVRVUVTVF9QQVlMT0FEX0VYQU1QTEVfVEhBVF9JU19FTkNPREVEX1dJVEhfYmFzZTY0X1VSTC1TQUZFX0VOQ09ESU5H

The URL-decoded value of the callbackUrl parameter in this example is:

https://example.google.com/return/url?redirectRequestId=cmVxdWVzdDE

The gspTopUpRequest parameter is encrypted and signed using PGP or JWE+JWS before being base64url-encoded.

Redirect Request Parameters

The HTTPS GET request must have the following query parameters:

Query parameter name Property value
callbackUrl string

URL to redirect the user to when the top-up is completed. This value is URL encoded and has a max length of 512 characters.

This URL will include the requestId from the encrypted gspTopUpRequest in the redirectRequestId GET parameter. The vendor should validate that the redirectRequestId from the callbackUrl and the requestId from the encrypted payload are identical to verify that both are related.
gspTopUpRequest TopUpRedirectRequest

REQUIRED: The TopUpRedirectRequest should be encrypted and signed using PGP or
JWE+JWS. Further, this value should be web-safe base64 encoded.

Redirect Response

Here's an example of the URL to which the user will be redirected after completing the top-up flow (also known as redirect response):

https://example.google.com/return/url?redirectRequestId=cmVxdWVzdDE&gspTopUpResponse=VEhJU19JU19BTl9FTkNSWVBURURfUkVESVJFQ1RfUkVTUE9OU0VfUEFZTE9BRF9FWEFNUExFX1RIQVRfSVNfRU5DT0RFRF9XSVRIX2Jhc2U2NF9VUkwtU0FGRV9FTkNPRElORw==

The URL-decoded value of the redirectRequestId parameter in this example is cmVxdWVzdDE.

The gspTopUpResponse parameter is encrypted and signed using PGP or JWE+JWS before being base64url-encoded.

Redirect Response Parameters

The HTTPS GET response must have the following query parameters:

Query parameter name Property value
redirectRequestId string

REQUIRED: The requestId sent in the original/initiating redirect payment request. Google will verify this matches the sent requestId, and the Complete Redirect flow will fail if it doesn't match.
gspTopUpResponse RedirectResponse

REQUIRED: The TopUpRedirectResponse should be encrypted and signed using PGP or JWE+JWS. Further, this value should be web-safe base64 encoded.

Android App Redirect

Here are the objects and what they represent:

  • User: This is the person who wants to top-up their account with the integrator.
  • Google UI: In this case, the web interface at Google, where the customer triggers the top-up flow.
  • Google Server: The backend server at Google that does the authentication check, along with other authentication tasks.
  • Payment Integrator APK: The integrator’s app where the user has access to their integrator account.
  • Payment Integrator Server: The backend server of the integrator where the user’s information is stored.

Android Top-Up Flow

  1. The Google UI creates a top-up call which is sent to the Google Server (backend).
  2. The Google Server create a top-up request (TopUpRedirectRequest).
  3. The Google Server sends a call APK instruction to the Google UI (app).
  4. The Google UI sends the request to the Payment Integrator APK (TOPUP_V1(topUpReq)).
  5. The Payment Integrator APK sends the request (topUpReq) to the Payment Integrator’s server.
  6. The Payment Integrator Server sends a login challenge back to the Payment Integrator APK.
  7. The Payment Integrator APK displays the login challenge to the user.
  8. The user provides proof of their identity, which is sent to the Payment Integrator APK.
  9. This proof is then sent to the Payment Integrator Server and the user goes through the top-up flow.
  10. The Server creates a signed TopUpRedirectResponse.
  11. The top-up response is successful, and a topUpResp message is sent to the Payment Integrator APK.
  12. The success message (topUpResp) is sent to from the Payment Integrator APK to the Google UI.
  13. The Google UI sends the response to the Google Server where the Google Server interprets the successful response.

Best practices and other considerations

Choice of platforms

Providing a mobile app and desktop web authentication flow will allow the integrator to reach the most users. Google strongly recommends that integrators support the Android application as it provides the best user experience resulting in the highest conversion rate. The parameters passed in the authentication APIs for the web and Android applications are the same.