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 Custom Tab or standard webview).
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 | type | description |
|---|---|---|
| integratorId | string | A Google-assigned string that uniquely identifies the partner that initiates the session. (Generic Placeholder: "THE_PARTNER_ID") |
| serviceCountry | string | The country code where the service is provided for this specific user. ISO 3166-1 alpha-2. (Generic Placeholder: "[COUNTRY_CODE]", e.g. "MY", "ID") |
| hl | string | 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. example: "ja", "en-US" |
| isTestEnvironment | boolean | Boolean value to indicate whether to use Google prod or sandbox environments. |
| onAuthenticationRequestReady | 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 | function | undefined |
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 "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. |
Parameter of callback functions
The callbacks take a single parameter object. The following are the attributes of the parameter object of the callback functions passed to startAccountLinking.
onAuthenticationRequestReady
| name | type | description |
|---|---|---|
| authRequest | 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 | type | description | ||||||
|---|---|---|---|---|---|---|---|---|
| accountLinkingResult | boolean | A boolean to indicate whether the account linking was successful. | ||||||
| errors | array |
Array of error information.
|
closeAccountLinkingWindow
closeAccountLinkingWindow does not take any parameter.
linkUser
| name | type | description |
|---|---|---|
| authResponse | string | A string to indicate authentication information. A string containing the signed and encrypted Authentication Request ID. This is the same Authentication Request ID in the Authentication Request. Refer to the Response API Schema Reference page for formatting and JWS/JWE construction details. |
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.
In all error states, account linking is not established. If your server backend has allocated a temporary pending link status, it is highly recommended to clean it up so the user can successfully retry the flow later.
Errors Returned by the onComplete Callback
These errors are passed in the errors array payload inside the onComplete callback hook.
- E1xx indicates an integration or configuration error on the partner side.
- E2xx indicates a secure runtime error.
| Error Code | Description |
|---|---|
|
| The integratorId specified in the request is not authorized. Check that your ID is correctly registered with Google. |
|
| 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. |
|
| The serviceCountry specified is not a valid country code. Must be a valid ISO 3166-1 alpha-2 tag. |
|
| The partner integration is disabled in the web app configuration. Please contact your Google technical integration manager. |
|
| A secure Google system error occurred, and the account linking failed. |
|
| The partner's backend server timed out while processing the token request. |
|
| The linkUser transaction token returned by the partner has an invalid format or signature verification failed. |
JavaScript Exceptions (Thrown Errors)
These exceptions are raised immediately in the front-end when invoking the SDK helper methods.
Errors Raised by startAccountLinking (E40x):
These errors are raised on the initial pop-up launch attempts.
| Error Code | Description |
|---|---|
|
| Missing or invalid type for the required parameters object passed to startAccountLinking. |
|
| An optional callback hook parameter passed has an invalid type (must be a function). |
|
| The Google linking window is already open in the web view (preventing multiple duplicate windows). |
|
| The SDK tried to launch the Google pop-up window, but it was blocked (typically due to browser pop-up block settings). |
|
| The required onAuthenticationRequestReady callback hook is missing or is not a valid function. |
Errors Raised by linkUser (E41x):
These errors are raised when attempting the signature handshake completion.
| Error Code | Description |
|---|---|
|
| The Google popup window is not currently open when linkUser was invoked. |
|
| linkUser was called out of sequence (before the onAuthenticationRequestReady callback received the initial token). |
|
| The required parameter authResponse is missing, null, or is not a valid string. |
Code Example
The following integration snippet illustrates a typical implementation of Google Account linking using the JavaScript SDK inside your application's WebView.
This sample code demonstrates how to initialize the flow, handle callback hooks, and complete the secure signature verification handshake:
// Trigger Google e-Wallet account linking
window.googlepay.startAccountLinking({
// Google-assigned partner identifier (Generic Placeholder)
'integratorId': 'THE_PARTNER_ID',
// Scoping country for localized transaction profiles (Generic Placeholder)
'serviceCountry': '[COUNTRY_CODE]',
// Set to true to test against Google Sandbox environment
'isTestEnvironment': true,
// Force localized text display inside the Google UI (optional)
'hl': '[LOCALE_TAG]', // e.g. 'ms-MY', 'en-US'
// Hook: Triggered when Google creates the secure authentication request token
'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.
//
// For more details, refer to the deep-linked Request/Response API schemas.
const authResponse = callYourBackendToVerifyAndSign(authRequest);
// 3. Complete the verification loop by passing the signed response back to Google.
// Note: The 'userAddress' parameter remains structurally required by the library
// runtime assertions. You must pass an empty object {} if address collection is bypassed.
window.googlepay.linkUser(authResponse, {});
},
// Hook: Triggered when the secure linking window completes and closes
'onComplete': function(payload) {
if (payload['accountLinkingResult']) {
// Account linking completed successfully!
// You can now redirect the user back to your main application landing page,
// or show a native "Success" toast.
console.log('Google account linking succeeded!');
showCustomSuccessMessageAndExit();
} else {
// The linking transaction failed.
if (payload['errors'] && payload['errors'].length !== 0) {
// Inspect the error diagnostics returned
payload['errors'].forEach(error => {
console.error(`Error ${error.errorCode}: ${error.errorDetail}`);
});
// Show an error screen or prompt the user to retry the flow
showCustomErrorMessage(payload['errors'][0]);
}
}
},
});
Back-End Operations Context
For a complete and secure integration, your backend server must support the cryptographic verify/signing loop referenced in the front-end example:
- Decrypting the Request: Your backend must decrypt the base64url-encoded JWS/JWE token passed from the client (authRequest) to extract the requestId. Refer to the Request Schema Reference page.
- Signing the Response: Your backend must verify Google's signature, bind the requestId to the user account session, sign/encrypt it again, and return the authResponse base64url JWS/JWE string. Refer to the Response Reference page.
- Handling Google Link Callback: Once the front-end calls linkUser(authResponse, {}), Google's server will callback your backend server via the LinkUserAccount RPC. Your server must look up the matching requestId and activate the link.