Google Pay™ lets your customers pay quickly and securely on the web using cards saved to their Google Account. As a Payment Service Provider (PSP), HiPay handles token decryption and payment processing on your behalf.
We support Google Pay integration on both Web and Android platforms.
📋 Before processing live transactions, all merchants must adhere to the official Google Pay API Terms of Service and Acceptable Use Policy. This compliance is mandatory regardless of your integration method (Mobile or Web).
Choose Your Integration Path
🌐 Web Integration
For websites and web applications, integrate Google Pay directly on your checkout page. Thanks to this documentation and the official Google Pay Web integration checklist, you will be able to start accepting Google Pay payments on your website.
You can choose to build your own solution or use our HiPay JS SDK for a faster, streamlined integration, please see the section bellow.
📲 Android Integration
For native Android applications, follow Google’s official Android integration guide to implement Google Pay in your mobile app. Please refer to the Android integration checklist and Android brand guidelines to ensure compliance.
If you choose not to use HiPay’s JavaScript SDK and prefer to maintain full control over the user experience and the integration of the official Google Pay API on your Front-end, you must configure Google Pay using the PAYMENT_GATEWAY mode.
You have to follow the Google documentation to integrate a GooglePay solution on your website.
💡 How it works: In this scenario, Google encrypts the buyer’s card data using HiPay’s public key. Your Front-end receives a secure token, which you have to convert as a HiPay token before to transmit to your server (Back-end) to execute the HiPay Order API call.
📋 Prerequisites: Getting Your Merchant ID
Before starting the technical integration, you must first set up your account on Google Pay & Wallet.
Required steps:
- Access the Google Pay & Wallet Console: Go to pay.google.com/business/console
- Create or sign in to your Google Account associated with your business
- Accept the terms: Accept the Google Pay Terms of Service and Acceptable Use Policy
- Configure your merchant profile and obtain your unique Merchant ID
- Save your Merchant ID: You will need it to configure your payment requests
⚠️ Important: Without this prior configuration, your integration will not work. Ensure your Merchant ID is properly configured before proceeding.
STEP 01
Initialize the client
Load the official Google script and instantiate the PaymentsClient in TEST or PRODUCTION mode.
STEP 02
Configure your parameters
Set up the official Google Pay API in PAYMENT_GATEWAY mode using hipay as the gateway.
STEP 03
Render the button
Verify user readiness via the API and inject the official button while respecting Google’s guidelines.
STEP 04
Convert the token
Retrieve the encrypted Google Pay token and convert it into a HiPay token using our secure vault API.
Step 1: Include and Initialize Google Pay
First, you need to load the official Google Pay JavaScript library onto your checkout page. The best practice is to load it asynchronously and instantiate the PaymentsClient as soon as the script has finished loading.
<script async src="https://pay.google.com/gp/p/js/pay.js" onload="onGooglePayLoaded()"></script>
Once the script is loaded, it automatically triggers the onGooglePayLoaded() callback function. Inside this function, you must instantiate the PaymentsClient by defining your target environment (TEST or PRODUCTION).
function onGooglePayLoaded() {
// Instantiate the Google Pay client
const paymentsClient = new google.payments.api.PaymentsClient({
// ENVIRONMENT CONFIGURATION:
// Use 'TEST' for development, staging, and QA environments.
// Use 'PRODUCTION' for your live store (requires HTTPS and approved domain).
environment: 'TEST'
});
// You can now define your configuration objects and check if the user is ready to pay
// (See Step 2 for configuration details)
}
Step 2: Configure Payment and Merchant Parameters
Once the client is ready, you need to define the payment configuration objects. This includes specifying hipay as your payment gateway, selecting the card networks you wish to support, and providing your merchant identifiers for both HiPay and Google.
// 1. Define the Tokenization Specification (HiPay Gateway configuration)
const tokenizationSpecification = {
type: 'PAYMENT_GATEWAY',
parameters: {
'gateway': 'hipay',
'gatewayMerchantId': btoa('YOUR_PUBLIC_API_USERNAME') // Your HiPay public API username encoded in Base64 format
}
};
// 2. Define the Card Payment Method (Supported networks and authentication)
const cardPaymentMethod = {
type: 'CARD',
parameters: {
allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'], // HiPay supports both authentication methods
allowedCardNetworks: ['MASTERCARD', 'VISA', 'MAESTRO'], // Supported card networks on HiPay
billingAddressRequired: true,
billingAddressParameters: {
format: 'FULL', // FULL includes all address fields (street, city, postal code, country)
isPhoneNumberRequired: false // Set to true if you need the phone number
}
},
tokenizationSpecification: tokenizationSpecification
};
// 3. Complete Google Pay Request Object containing your Merchant Identity
const paymentDataRequest = {
apiVersion: 2,
apiVersionMinor: 0,
allowedPaymentMethods: [cardPaymentMethod],
merchantInfo: {
// TEST ENVIRONMENT: This field is not validated by Google. You can use a dummy value (e.g., '01234567890123456789').
// PRODUCTION ENVIRONMENT: Replace with your official 20-digit Google Merchant ID obtained from the Google Pay Console.
merchantId: 'YOUR_GOOGLE_MERCHANT_ID',
merchantName: 'Your Store Name' // The brand name that will be displayed to the customer in the Google Pay payment sheet
},
transactionInfo: {
totalPriceStatus: 'FINAL',
totalPrice: '45.00', // Total transaction amount
currencyCode: 'EUR', // ISO 4217 currency code
countryCode: 'FR' // ISO 3166-1 alpha-2 country code - Required if customer is in a SCA-regulated region (e.g., EEA, UK)
}
};
📌 Note on Merchant Identifiers : Please note that merchantInfo.merchantId and gatewayMerchantId are different:
merchantInfo.merchantIdis your Google Merchant ID, generated by Google after registering your website on the Google Pay Console. (In theTESTenvironment, this field can be omitted or left as dummy).gatewayMerchantIdis a base64-encoded public API username from your HiPay account to identify Google Pay tokens as being associated with you.
💳 Authentication Methods: PAN_ONLY vs CRYPTOGRAM_3DS
HiPay supports both authentication methods for Google Pay transactions, each providing different levels of tokenization security and risk management:
PAN_ONLY
- Tokenization: Google provides the standard Primary Account Number (PAN) token
- HiPay’s Role: HiPay processes the transaction and may trigger 3DS authentication based on its fraud detection engine and payment risk assessment
- Use Case: Standard card processing where 3DS is conditionally applied according to regulatory and risk-based requirements
- Payment Flow: Token → Risk Assessment → Possible 3DS Challenge → Authorization
CRYPTOGRAM_3DS
- Tokenization: Google provides an encrypted cryptogram with device binding instead of a PAN
- HiPay’s Role: HiPay processes the encrypted token directly without triggering 3DS. The security is inherent to the device-based tokenization, not dependent on 3DS challenges
- Use Case: High-security transactions where strong tokenization eliminates the need for additional authentication flows
- Payment Flow: Encrypted Token (Device-Bound) → Direct Processing → Authorization (No 3DS Page)
📋 Configuring Your Authentication Methods
In your Google Pay request, define your preferred authentication methods:
const cardPaymentMethod = {
type: 'CARD',
parameters: {
allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
allowedCardNetworks: ['MASTERCARD', 'VISA', 'MAESTRO']
}
};
🔐 Forcing 3DS Authentication
Control how 3DS is applied to PAN_ONLY transactions by setting the authentication_indicator parameter in your HiPay Order request (see Step 5: Server-side Processing (HiPay API Call)): use value 1 to let HiPay’s fraud detection engine decide when 3DS is needed, or value 2 to enforce 3DS authentication for all transactions.
{
"authentication_indicator": 1, // 1 as default value, or 2 to force 3DS
// ... other order parameters
}
How it works:
-
- When you include both methods, Google Pay selects the appropriate tokenization method based on device capabilities and issuer support.
- When you want only device-based tokenization, use only
['CRYPTOGRAM_3DS']to ensure stronger security throughout the payment chain. - The
authentication_indicatorparameter controls 3DS behavior forPAN_ONLYcredentials only.
🌍 Geographic Considerations
The authentication methods you support may depend on your transaction’s geographic context. Refer to Google’s SCA (Strong Customer Authentication) guide for more details:
-
- PAN_ONLY: Generally available globally, but HiPay may trigger 3DS based on fraud detection and the cardholder’s location
- CRYPTOGRAM_3DS: Recommended for regions with Strong Customer Authentication (SCA) requirements, such as the EEA (European Economic Area) and UK
Always ensure you include the correct countryCode in your transaction information to allow Google Pay to determine the appropriate authentication method based on local regulations.
📍 Collecting Billing Address Information
The billingAddressParameters configuration allows you to request the customer’s billing address during the Google Pay transaction.
const cardPaymentMethod = {
type: 'CARD',
parameters: {
allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
allowedCardNetworks: ['MASTERCARD', 'VISA', 'MAESTRO'],
billingAddressRequired: true,
billingAddressParameters: {
format: 'FULL',
isPhoneNumberRequired: false
}
},
tokenizationSpecification: tokenizationSpecification
};
This information is useful for:
- Fraud Prevention: Validate the billing address against card issuer records
- Order Fulfillment: Use the address for delivery or verification
- Compliance: Ensure you have the necessary customer information for regulatory requirements
Configuration Options
billingAddressRequired: Set totrueto require billing address information. Iffalse, billing address is optionalbillingAddressParameters: Object containing billing address collection settings:format:FULL– Collects complete address (street, city, postal code, country)FULL-ISO3166– Collects complete address including name, street address, locality, region, country code, postal code, and ISO 3166 administrative areaMIN– Collects minimal address (postal code and country only)
isPhoneNumberRequired: Set totrueif you need the customer’s phone number with their billing address
The billing address returned in the Google Pay response should be passed to HiPay in your Order request for additional validation and fraud prevention.
Step 3: Check Readiness and Render the Button
Before displaying the payment button, you must verify if the user is capable of paying with Google Pay using the isReadyToPay() method. If the response is positive, you can dynamically render the official button.
⚠️ Important: To ensure your production access is approved by Google, your button must strictly comply with the official Google Pay Brand Guidelines. Never create a custom HTML/CSS button from scratch; always use the button creation API provided by the script.
// Check if the user is ready to pay with the defined configuration
paymentsClient.isReadyToPay(paymentDataRequest)
.then(function(response) {
if (response.result) {
// Create the official Google Pay button
const button = paymentsClient.createButton({
buttonColor: 'default', // 'default', 'black', or 'white'
buttonType: 'buy', // 'buy', 'plain', 'donate', 'checkout', etc.
buttonSizeMode: 'responsive',
onClick: onGooglePayButtonClicked // Function triggered when clicked
});
// Append the button to your HTML container (e.g., <div id="google-pay-container"></div>)
document.getElementById('google-pay-container').appendChild(button);
} else {
// Fallback: hide the Google Pay option or show standard credit card forms
console.log("Google Pay is not available for this user/device.");
}
})
.catch(function(err) {
console.error("isReadyToPay error: ", err);
});
<body>
<div id="'google-pay-container"></div>
</body>
Step 4: Retrieving the Payment Token
When the user clicks the Google Pay button, you must trigger the Google payment sheet using loadPaymentData(). Once the buyer validates the transaction in the Google Pay payment sheet, the Google API returns a PaymentData object. You must extract the raw JSON string of the encrypted token, then you have to convert it as a HiPay token, here is the response format of a HiPay token.
// This function is automatically triggered when the user clicks your official Google Pay button
function onGooglePayButtonClicked() {
// Open the secure Google Pay interactive sheet
paymentsClient.loadPaymentData(paymentDataRequest)
.then(async function(paymentData) {
// 1. Extract the encrypted payment token string from Google's response
const googlePayToken = paymentData.paymentMethodData.tokenizationData.token;
// 2. Exchange the Google token for a HiPay token via our secure vault API
const response = await fetch('https://secure2-vault.hipay-tpp.com/rest/v2/google-pay/token.json', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + btoa('<YOUR_PUBLIC_API_USERNAME>:<YOUR_PUBLIC_API_PASSWORD>'),
'Content-Type': 'application/json'
},
body: JSON.stringify({
google_pay_token: googlePayToken
})
});
const hipayTokenData = await response.json();
// 3. Forward this HiPay token to your backend to process the actual payment
// (See Step 5)
processBackendPayment(hipayTokenData.token);
})
.catch(function(err) {
// Handle errors or user cancellation (e.g., user closed the Google sheet)
console.error("Google Pay payment sheet error: ", err);
});
}
Step 5: Server-side Processing (HiPay API Call)
From your server, make an API call to our order creation endpoint POST /v1/order, injecting the token extracted in the previous step.
{
"orderid": "CMD-2026-98765",
"amount": 45.00,
"currency": "EUR",
"payment_product": "<BRAND_OR_DOMESTIC_NETWORK_OF_HIPAY_TOKEN>",
"cardtoken": "<TOKEN_FIELD_OF_HIPAY_TOKEN>",
"accept_url": "https://www.your-site.com/success",
"decline_url": "https://www.your-site.com/decline"
}
⚠️ Coming Soon: The Google Pay integration via HiPay SDK JS is currently under development and will be available shortly. In the meantime, please refer to the Direct Integration tab to set up your payment method.
The HiPay JS SDK is the recommended way to integrate Google Pay. It simplifies the implementation by managing the official Google Pay API lifecycle, button rendering, and secure tokenization automatically within the HiPay ecosystem.
💡 Why use the SDK? It reduces your development time and ensures that you are always compliant with Google’s latest security and branding requirements without manual updates to your integration code.
Furthermore, with the HiPay JS SDK, there’s no need to register on Google Pay Console. The payment button is hosted in our secure iframe, and we manage the merchant ID on your behalf. Simply integrate our SDK and you’re ready to accept Google Pay payments.
Step 01
Initialize the SDK
Instantiate HiPay with your public credentials and target environment.
Step 02
Create the button
Call hipay.create('wallet', …) — the SDK handles loading the Google Pay library.
Step 03
Listen to events
The paymentAuthorized event triggers your backend order logic.
Step 1: Setup the HiPay JS SDK
To get started, include the HiPay JavaScript SDK on your HTML page. Here is the documentation to do so.
Then, create an instance of the HiPay JavaScript SDK by reading this documentation.
Step 2: Creating the Google Pay button
Define the Google Pay component and mount it to your container. The SDK will automatically generate the official Google Pay button.
const googlePayButton = hipay.create('wallet', {
selector: 'google-pay-button-container',
provider: 'googlepay',
request: {
amount: '49.99',
currency: 'EUR',
supportedNetworks: ['MASTERCARD', 'VISA', 'MAESTRO'] // Supported card networks on HiPay
},
displayName: 'My store', // The brand name that will be displayed to the customer in the Google Pay payment sheet
countryCode: 'FR',
existingPaymentMethodRequired: false, // If true, the Google Pay button will be displayed only if the customer has an active card in his wallet that matches your supported networks
buttonStyle: { // See options here : https://developers.google.com/pay/api/web/reference/request-objects?hl=fr#ButtonOptions
color: 'black',
type: 'buy',
cornerRadius: 4,
width: 250
}
});
<body>
<div id="'google-pay-button-container"></div>
</body>
Step 3: Event handling
The button emits three main events. The paymentAuthorized event is the core of the integration — it receives the HiPay token then you have to trigger the order creation on your backend.
ready
Button Ready
Google Pay is available and the button has been rendered. Use this event to make the container visible.
notEligible
Not Eligible
Google Pay is not eligible on this device and Google Pay must not be displayed. Use this event to know if the device is not eligible.
paymentAuthorized
Payment Authorized
The user has confirmed. Receives the tokenHipay. Call your backend then completePaymentWithSuccess().
paymentUnauthorized
Payment Unauthorized
The user has confirmed but an error occured during tokenization on Google Pay side or HiPay one.
cancel
Cancel
The user has cancelled the Google Pay payment sheet.
// Button ready
googlePayButton.on('ready', () => {
// Make the container visible
});
// Google Pay not available on this device/browser
googlePayButton.on('notEligible', () => {
// Hide the button, offer an alternative payment method
});
// Payment authorized by the user
googlePayButton.on('paymentAuthorized', async (tokenHipay) => {
try {
await createOrder(tokenHipay); // Call your backend
await googlePayButton.completePaymentWithSuccess();
} catch (err) {
await googlePayButton.completePaymentWithFailure();
}
});
completePaymentWithSuccess() and completePaymentWithFailure() must be called with await before any navigation, to allow the SDK to properly close the Google Pay sheet.