Reverse Binding SDK

Overview

Google provides a client-side JavaScript SDK to allow partner integrators to launch the secure Google Account linking flow directly within a secure pop-up window in their application (typically served inside a Chrome Custom Tab).

For the architectural overview, sequence diagram, and Chrome Custom Tabs (CCT) requirements, refer to the Reverse Binding guide.

SDK Downloads

Partners must download and integrate the library files to expose the window.googlepay API namespace in their web views:

SDK Methods

Method Name	Description
`startAccountLinking`	Open WebApp UI, Google's UI flow to link the account, in a new window. It takes parameters about the account linking, and takes callbacks.
`closeAccountLinkingWindow`	Forcefully closes the UI flow window. No parameters. In the normal flow, this shouldn't be called. Should only be called when the partner decides to terminate the account linking flow.
`linkUser`	Initiates the actual account linking procedure. Should be called from `onAuthenticationRequestReady` callback passed by `startAccountLinking`.

Parameters of SDK Methods

The functions with parameters take an object as a sole parameter. The attributes of the parameter object are listed below.

startAccountLinking

name	Requirement	type	example	description
`integratorId`	Required	string	`"EWALLET_PARTNER"`	A Google-assigned string that uniquely identifies the partner that initiates the session.
`serviceCountry`	Required	string	`"JP"`, `"US"`	The country code where the service is provided for this specific user. ISO 3166-1 alpha-2. (e.g. `"JP"`, `"MY"`, `"ID"`).
`hl`	Required	string	`"ja"`, `"en-US"`	Web Interface Language. A well-formed IETF BCP 47 language tag representing the locale of the user. If provided, it's used to localize the content in the application window. If it's not provided, the Google Account language preference is used. If the user hasn't signed in to Google yet, the browser language preference is used. Always provide a valid BCP 47 tag; passing empty or malformed strings causes system error `E200`.
`utm_campaign`	Required	string	`"home_page_direct_nocampaign"`, `"playzone_bindbanner_nocampaign"`, `"transactionsuccess_15cashback"`	A string parameter used to track and attribute the source marketing campaign or entry point for the account linking session. Google records this campaign identifier in analytics, telemetry, and conversion tracking logs.
`onAuthenticationRequestReady`	Required	function	callback function	Called when Authentication Request is created, and is ready to initiate account linking. The partner should extract Authentication Request ID from Authentication Request and use it to generate Authentication Response. Then the partner should call `window.googlepay.linkUser`.
`onComplete`	Required	function	callback function	Called when the account linking flow is done and the Google WebApp UI is closed. The user might have clicked the button to close the window on the final screen, or user might have forcefully closed the window by clicking the "x" button of the window, or swiping out the app. The parameter indicates the result of the account linking and/or errors. Error codes are indicated in the Error codes section.
`isTestEnvironment`	Optional	boolean	`true`, `false`	Boolean value to indicate whether to use Google prod or sandbox environments.
`maskedAccountId`	Optional	string	`"user***@domain.com"`	Masked ID of the user identifying the partner account. This will be used for display purposes in the Google UI.
`cardForChainedProvisioning`	Optional	string	`"ABCD Card ••1234"`	The name and the masked numbers of the card the partner wants to provision after the account linking. If the parameter is undefined, provisioning is not triggered after the account linking flow. The format must be consistent with the card information returned by the `listPaymentMethods` method. The last 4 digits of the parameter are checked against the list of cards from `listPaymentMethods`. Provisioning is started (`startProvisioningDeviceToken` in `onComplete` is set to `true`) only when the last 4 characters of `cardForChainedProvisioning` are digits, and they match one of the cards in the list.

Parameter of callback functions

onAuthenticationRequestReady

name	Requirement	type	description
`authRequest`	Required	string	Signed and encrypted form of the Authentication Request ID. The Authentication Request is to be sent to the partner's backend to process and generate Authentication Response. Refer to the Request API Schema Reference page for details on decrypting the payload and extracting fields.

onComplete

name Requirement type description

accountLinkingResult Required boolean A boolean to indicate whether the account linking was successful.

startProvisioningDeviceToken Optional boolean A boolean to indicate whether the partner should start the push provisioning flow. The user may decide not to do the provisioning, in which case the value is set to false.

accountLinkingData Optional string A string value to be passed to the Android push provisioning SDK as accountLinkingData. The value is returned only when startProvisioningDeviceToken is true.

errors

Optional

array

Array of error information objects:

`errorCode`	string	Error Code
`errorDetail`	string	Details of the error

closeAccountLinkingWindow

closeAccountLinkingWindow does not take any parameter.

linkUser

name	Requirement	type	description
`authResponse`	Required	string	A string to indicate authentication information. A string containing the signed and encrypted Authentication Request ID. This is the same Authentication Request ID received in the `authRequest`. Refer to the Response API Schema Reference page for formatting and JWS/JWE construction details.
`userAddress`	Optional	object	Optional user address payload. Pass an empty object `{}` if address collection is bypassed.

Error Codes

The client-side library raises diagnostic exceptions under the errors payload key inside the onComplete callback, or throws a JavaScript exception immediately during initial method validation.

Errors Returned by the onComplete Callback

Error Code	Description
`E101`	The `integratorId` specified in the request to the Google Account linking Web App is not authorized. Check that your ID is correctly registered with Google.
`E102`	The origin domain (URL) of the page invoking the SDK is not authorized for the specified `integratorId`. Ensure your allowed origins domain list is registered and configured with Google.
`E103`	The `serviceCountry` specified in the request to the Google Account linking Web App is not a valid country code. Must be a valid ISO 3166-1 alpha-2 tag.
`E104`	The `cardForChainedProvisioning` specified in the request to the Google Account linking Web App does not follow the defined format.
`E105`	The partner integration is disabled in the Google Account linking configuration. Please contact your Google technical integration manager.
`E200`	A secure Google system error occurred, and the account linking failed. (Note: Can be caused by omitting or passing an invalid `hl` locale parameter).
`E201`	The partner's backend server timed out while processing the token request (exceeded the 10-second frontend timer).
`E202`	The `linkUser` transaction token returned by the partner has an invalid format or signature verification failed.
`E203`	The Google Account is already linked to the partner account.
`E300`	FOP save error, while the account linking succeeded.

JavaScript Exceptions (Thrown Errors)

Errors Raised by startAccountLinking (E40x):

Error Code	Description
`E401`	Missing or invalid parameter for the required param of `startAccountLinking`.
`E402`	Optional callback function param has an invalid type (must be a function).
`E403`	Window dimension (width or height) in the `startAccountLinking` param has an invalid type.
`E404`	The Google linking window is already open in the web view (preventing multiple duplicate windows).
`E405`	The SDK tried to launch the Google pop-up window, but it could not open (typically blocked by browser pop-up blocker).
`E406`	The required `onAuthenticationRequestReady` callback hook is missing or is not a valid function.

Errors Raised by linkUser (E41x):

Error Code	Description
`E410`	The Google pop-up window is not currently open when `linkUser` was invoked.
`E411`	`linkUser` was called out of sequence (before the `onAuthenticationRequestReady` callback received the initial token).
`E412`	The required parameter `authResponse` is missing, null, or is not a valid string.
`E413`	`userAddress` is missing or invalid.

Code Example

// Trigger Google e-Wallet account linking
window.googlepay.startAccountLinking({
  // Google-assigned partner identifier (Required)
  'integratorId': 'THE_PARTNER_ID',

  // Scoping country for localized transaction profiles (Required, ISO 3166-1 alpha-2)
  'serviceCountry': 'JP',

  // Web Interface Language (Required, well-formed IETF BCP 47 language tag)
  'hl': 'ja',

  // Source marketing campaign or entry point attribution (Required)
  // Examples: 'home_page_direct_nocampaign', 'playzone_bindbanner_nocampaign', 'transactionsuccess_15cashback'
  'utm_campaign': 'home_page_direct_nocampaign',

  // Set to true to test against Google Sandbox environment (Optional)
  'isTestEnvironment': true,

  // Masked user account ID for display purposes in the Google UI (Optional)
  'maskedAccountId': 'user***@domain.com',

  // Card details to trigger chained push provisioning after linking (Optional)
  'cardForChainedProvisioning': 'ABCD Card ••1234',

  // Hook: Triggered when Google creates the secure authentication request token (Required)
  'onAuthenticationRequestReady': function(payload) {
    // 1. Extract the secure encrypted request token
    const authRequest = payload['authRequest'];

    // 2. Forward the token to your server backend to verify, sign,
    // and return an encrypted authResponse payload.
    const authResponse = callYourBackendToVerifyAndSign(authRequest);

    // 3. Complete the verification loop by passing the signed response back to Google.
    window.googlepay.linkUser(authResponse, {});
  },

  // Hook: Triggered when the secure linking window completes and closes (Required)
  'onComplete': function(payload) {
    if (payload['accountLinkingResult']) {
      console.log('Google account linking succeeded!');

      if (payload['startProvisioningDeviceToken']) {
        const pushTokenData = payload['accountLinkingData'];
        console.log('Initiating push provisioning with token:', pushTokenData);
        launchAndroidPushProvisioning(pushTokenData);
      }

      showCustomSuccessMessageAndExit();
    } else {
      if (payload['errors'] && payload['errors'].length !== 0) {
        payload['errors'].forEach(error => {
          console.error(`Error ${error.errorCode}: ${error.errorDetail}`);
        });
        showCustomErrorMessage(payload['errors'][0]);
      }
    }
  },
});

Backend Implementation

For specifications on how your backend server must decrypt the authRequest JWE token, sign the authResponse JWS token, and handle the Google server callback, see Backend Operations Context in the Reverse Binding Flow guide.

Reverse Binding SDK Stay organized with collections Save and categorize content based on your preferences.