Google Pay™ (via Processor)

note

This integration supports external 3DS for PAN_ONLY token type.

About

Google Pay™ (via Processor) explains how PaymentIQ acts as the processor for Google Pay™. It covers decrypting and storing token data to enable card-on-file for future deposits and withdrawals, and what this means for PCI scope. The actual transactions are still routed to and processed by the PSP (e.g. BamboraGa). Use this guide for PSPs which integrations in PaymentIQ support specifically the Google Pay™ flow via Processor. The PSPs which support this flow are listed in the "Providers" section below.

Provider Name	Google Pay
Link	https://pay.google.com/about/
Classification	Wallet
Regions	International
Currencies	Please verify supported currencies directly with the provider
Methods/PaymentTxTypes	GooglePayDeposit, GooglePayWithdrawal
PaymentIQ Configuration File	GooglePayConfig
Providers	Paysafe, Adyen, BamboraGa, Shift4

Configuration Information

Attributes

Attribute	Description
gatewayMerchantId	The merchant's unique identifier within PaymentIQ's system. This is the merchant's account ID in PaymentIQ Backoffice, used by Google Pay to identify which merchant account on PaymentIQ's gateway should process the payment.
merchantId	The Google Merchant ID issued by Google after registering in the Google Pay & Wallet Console. This identifies the merchant to Google.
merchantName	Optional. The merchant's name encoded in UTF-8 and displayed on the payment sheet. In TEST environments, or if unrecognized, "Pay Unverified Merchant" will appear.
supportedAuthMethods	Optional. Possible values: PAN_ONLY, CRYPTOGRAM_3DS. If not set, both types are considered to be set. Example: PAN_ONLY|CRYPTOGRAM_3DS
supportedNetworks	Optional. Possible values: VISA, MASTERCARD, AMEX, DISCOVER, INTERAC, JCB. If not set, all network types are considered to be set. Example: AMEX|DISCOVER

Important: Domain registration with Google

When using the initial deposit flow, the user is redirected to a Google Pay page hosted by PaymentIQ's API server. Google requires that this domain be registered and verified in your Google Pay Business Console. Failure to do so will prevent the Google Pay sheet from loading and result in an error, such as OR_BIBED_11.

Register api.paymentiq.io (or the base API URL of your PaymentIQ environment) as an authorized web domain. For step-by-step instructions on registering a domain, see Google's Publish your integration guide (see the "Integrate your website" section).

Recommended

To avoid any confusion, also register checkout.paymentiq.io (or your cashier origin domain) alongside api.paymentiq.io. This covers both the redirect and any inline flows.

Note: This step is needed for the redirect deposit flow only. Subsequent deposits and withdrawals using the stored card-on-file do not involve a redirect and are not affected by this requirement.

Google Pay in the Cashier

GooglePay methods can be configured under Admin -> Cashier -> Payment Methods and Inputs in PaymentIQ Backoffice.

The methods should be configured with the amount input:

• Cashier Payment Method:

  • Tx Type: GooglePayDeposit
  • Inputs: amount

• Cashier Payment Method:

  • Tx Type: GooglePayWithdrawal
  • Inputs: amount

Inline Deposit Flow

The inline flow is available with the same PSPs as the redirect processor flow. For the inline flow, merchantName should be set in GooglePayConfig.

For an inline Google Pay button rendered directly in the cashier (no redirect), configure the deposit payment method as follows:

• Cashier Payment Method:
  • Tx Type: GooglePayDeposit
  • Inputs: amount
  • Input Html Template Name: googlepay-processor-inline
  • Hide Submit: ON

With this configuration, the Google Pay button will be displayed inline within the cashier. The user clicks the Google Pay button directly instead of the cashier's submit button.

:::caution

Hide Submit must be set to ON for the inline flow. Without it, the cashier's default submit button will appear alongside the inline Google Pay button at the same time, which can break the payment process.

:::

INFO

With the inline flow, subsequent deposits using a stored account are not supported. Every time the user clicks the inline Google Pay button, the Google Pay pop-up appears to generate a new token. The full redirect deposit flow is executed each time.

The GooglePayWithdrawal method remains configured as above. Closed-loop withdrawals using the stored account work alongside the inline deposit flow without any additional configuration.

GooglePay Deposit

Initial deposit flow:

1. User enters amount in the cashier and pushes submit button.
2. User is redirected to GooglePay page to choose the card for the payment.
3. Token with card data is sent to PaymentIQ. Card data securely stored in user account in the cashier.
4. PaymentIQ sends a payment request along with card data to the processing PSP.
5. PaymentIQ receives a final transaction status from the PSP response, and redirects user to the page with final transaction status.

Subsequent deposit flow (using already stored account):

1. User enters amount in the cashier and pushes submit button.
2. PaymentIQ sends a payment request along with card data to the processing PSP.
3. PaymentIQ receives a final transaction status from the PSP response, and redirects user to the page with final transaction status.

GooglePay Withdrawal

Withdrawal can be triggered only after the first deposit was successfully executed using a PAN_ONLY token. In this case, the corresponding user account is stored and visible in the cashier, and can be used for withdrawal.

Note: When a CRYPTOGRAM_3DS token is used for the initial deposit, the account is still stored internally but is not visible to the user in the cashier, and therefore cannot be selected for withdrawal.

The withdrawal flow is similar to subsequent deposit flow.

Google Pay Integration Requirements

This section outlines the requirements that merchants must fulfil when integrating Google Pay™ through PaymentIQ. As PaymentIQ acts as the SDK/hosted-checkout layer that generates IsReadyToPayRequest and PaymentDataRequest properties on behalf of the merchant, the following steps apply.

Branding

Make sure that any documentation, UI, or marketing material referring to this payment method uses the trademark symbol on the first and most prominent mention: Google Pay™.

When displaying Google Pay as a payment option, you must use the official Google Pay logo and button assets without modification to colors, proportions, or appearance, in compliance with the:

• Google Pay web brand guidelines

Merchant Requirements & Compliance

Important

By using PaymentIQ's Google Pay™ integration, merchants must adhere to the Google Pay and Wallet API's Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.

To enable Google Pay™ functionality, merchants must complete the following essential steps:

1. Register and obtain a Google Merchant ID via the Google Pay & Wallet Console.
2. Enter the provisioned merchantId value into the PaymentIQ GooglePayConfig (see Configuration Information above).
3. Register and verify the domain used for the checkout in the Google Pay Business Console (see the domain registration warning in the Configuration Information section above). The domain that should be used is api.paymentiq.io.

For further reference, see the:

• Google Pay Web developer documentation
• Google Pay Web integration checklist
• Google Pay Web brand guidelines

TokenizationSpecification — gateway and gatewayMerchantId

PaymentIQ uses the PAYMENT_GATEWAY tokenization type when communicating with the Google Pay API on behalf of the merchant. The gateway value is the gateway ID registered by PaymentIQ during technical onboarding with Google. The gatewayMerchantId is the merchant's unique account ID within PaymentIQ's system (i.e., the value set in gatewayMerchantId in GooglePayConfig).

Example tokenizationSpecification object used internally by PaymentIQ:

{
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "<PAYMENTIQ_GATEWAY_ID>",
      "gatewayMerchantId": "<Merchant ID assigned in GooglePayConfig>"
    }
  }
}

Authorization Methods — PAN_ONLY and CRYPTOGRAM_3DS

Google Pay™ supports two card credential types via the allowedAuthMethods parameter:

Auth Method	Description	3DS Required
PAN_ONLY	Physical card details stored in Google Pay™	Yes (3DS flow)
CRYPTOGRAM_3DS	Tokenized virtual card stored on device; authentication handled by Google Pay™	No

This can be configured via supportedAuthMethods config parameter in GooglePayConfig. If not set, it is considered to be PAN_ONLY|CRYPTOGRAM_3DS.

External 3DS for PAN_ONLY

When a PAN_ONLY token is returned from Google Pay, the card data is a raw PAN without network-level authentication. To meet SCA requirements, PaymentIQ can trigger external 3DS authentication before sending the payment to the PSP.

Prerequisites:

1. The PSP must support the Google Pay decrypted flow (GooglePayDeposit tx type).
2. The PSP account config must have use3Dsecure enabled.
3. A 3DS routing rule must be configured to match the GooglePayDeposit tx type and route to a 3DS provider.

If all three conditions are met, PaymentIQ will automatically perform 3DS authentication for PAN_ONLY tokens before forwarding the payment to the PSP. For CRYPTOGRAM_3DS tokens, 3DS is never triggered regardless of routing configuration.

Supported Card Networks

PaymentIQ's integration with the Google Pay API supports the following card networks via the allowedCardNetworks parameter:

VISA, MASTERCARD, AMEX, DISCOVER, INTERAC, JCB

This can be configured via supportedNetworks config parameter in GooglePayConfig. If not set, it is considered to be all of the above.

Merchants must make sure they only enable networks that are applicable to their region and settlement requirements. For the full list of supported values, refer to Google Pay's web developer documentation.

Handling the Google Pay™ Payload

When a customer pays with Google Pay™, an encrypted payload is generated containing the payment data. PaymentIQ decrypts this payload on behalf of the merchant and securely stores the card data in the user's account.

The encrypted data is extracted from the paymentMethodData.tokenizationData.token property of the PaymentData response object returned by the Google Pay API. PaymentIQ then forwards the relevant card data to the processing PSP to complete the transaction — merchants do not need to handle this token directly.

Example Routing Rule

Field	Value
Payment Method	GooglePay
Provider	Your processor (e.g. Paysafe)
PSP Service	GOOGLEPAY
Condition	As needed (country, amount)