Google Pay¶

Introduction¶

Google Pay is a digital wallet for online payments offered by Google. Customers can add their credit or debit cards to their Google Pay wallet and use them to pay at web shops or mobile applications through the Payment Gateway.

Benefits:

Customers simply select a card from their Google Pay wallet — no need to manually enter card details
Secure encryption and decryption raises trust and reduces online fraud
Streamlined checkout experience increases conversion rates

Tokenization Types¶

Google Pay supports two types of tokenized cards:

Authentication Method	Description	3D Secure Required
PAN_ONLY	A standard credit/debit card stored in the Google account. The actual card PAN is tokenized.	Yes — 3DS verification is required for fraud protection
CRYPTOGRAM_3DS	A virtual card with a device-specific account number (DPAN) used in place of the real card. A digital signature from the mobile device protects against fraud.	No — the cryptogram serves as authentication proof

The Payment Gateway supports both CRYPTOGRAM_3DS and PAN_ONLY authorization methods.

Supported card networks: Visa, Mastercard

Integration Methods¶

There are two ways to accept Google Pay payments:

Method	Description	Additional Development
Hosted Payment Page	Google Pay is displayed as a payment option on the hosted payment form	None required
API Integration	Merchant integrates directly with the Google Pay API and sends the payment token to the gateway	Yes — Google Pay API + gateway API

Activation Prerequisites¶

Before accepting Google Pay payments, you must:

Submit a request to your account manager to enable Google Pay on your terminal
Follow the Google Pay API Terms of Use
Complete the Google Pay integration checklist and publish your integration ( required for API integration only)

Hosted Payment Page¶

If you are already integrated with the Hosted Payment Page, no additional development is required.

Simply request activation of the Google Pay payment method from your account manager. Once enabled, a Google Pay option will appear on the hosted payment form alongside other payment methods.

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway as Payment Gateway
    participant Google as Google Pay
    Customer ->> Merchant: Initiates checkout
    Merchant ->> Gateway: Create HPP session
    Gateway -->> Merchant: Redirect URL
    Merchant ->> Customer: Redirect to HPP
    Customer ->> Gateway: Select Google Pay on HPP
    Gateway ->> Google: Initiate Google Pay
    Customer ->> Google: Authenticate & confirm payment
    Google -->> Gateway: Google Pay token
    Gateway ->> Gateway: Process payment
    Gateway -->> Merchant: Payment result (webhook/redirect)

API Integration¶

For merchants who want full control over the checkout experience, you can integrate directly with the Google Pay API and submit the payment token to the gateway.

Integration Steps¶

Integrate with the Google Pay API for Web
Customer clicks the Google Pay button on your checkout page
Customer selects a card and confirms payment in the Google Pay dialog
Google Pay returns a payment token to your frontend
Send the token to your backend server
Submit the token to the Payment Gateway API

Google Pay API Web Integration¶

Before starting, review the following Google resources:

Google Pay API Configuration¶

When calling the Google Pay API, configure the PaymentMethod object with the following parameters:

{
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": [
          "PAN_ONLY",
          "CRYPTOGRAM_3DS"
        ],
        "allowedCardNetworks": [
          "VISA",
          "MASTERCARD"
        ]
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "finrelaypayments",
          "gatewayMerchantId": "<your_merchant_id>"
        }
      }
    }
  ],
  "transactionInfo": {
    "countryCode": "BA",
    "currencyCode": "EUR",
    "totalPriceStatus": "FINAL",
    "totalPrice": "10.00"
  },
  "merchantInfo": {
    "merchantId": "<your_google_merchant_id>",
    "merchantName": "<your_merchant_name>"
  },
  "callbackIntents": [
    "PAYMENT_AUTHORIZATION"
  ]
}

Configuration Parameters¶

Parameter	Value	Description
`allowedAuthMethods`	`["PAN_ONLY", "CRYPTOGRAM_3DS"]`	Both authentication methods are supported
`allowedCardNetworks`	`["VISA", "MASTERCARD"]`	Supported card networks
`tokenizationSpecification.type`	`"PAYMENT_GATEWAY"`	Use gateway tokenization

| tokenizationSpecification.parameters.gateway | "finrelaypayments" | Gateway identifier for Finrelay |

| tokenizationSpecification.parameters.gatewayMerchantId | Your merchant ID | Provided by your account manager |

Merchant IDs

gatewayMerchantId: Your merchant identifier in the Payment Gateway — provided by your account manager
merchantId: Your Google merchant ID — obtained from the Google Pay Business Console

Payment Processing¶

After the customer completes the Google Pay flow, the Google Pay API returns a PaymentData object. To process the payment:

Extract the token from paymentData.paymentMethodData.tokenizationData.token
Base64-encode the token string
Send it to the Payment Gateway API as the payment_method.data.google_pay_token field

Flow Diagram¶

sequenceDiagram
    participant Customer
    participant Frontend as Merchant Frontend
    participant Backend as Merchant Backend
    participant Gateway as Payment Gateway
    participant Acquirer
    Customer ->> Frontend: Click Google Pay button
    Frontend ->> Customer: Google Pay dialog
    Customer ->> Frontend: Confirm payment
    Frontend ->> Frontend: Receive PaymentData from Google Pay
    Frontend ->> Backend: Send Google Pay token
    Backend ->> Backend: Base64-encode token
    Backend ->> Gateway: POST /api/transactions/authorize<br/>(payment_method.type = "google-pay")
    Gateway ->> Gateway: Decode & decrypt Google Pay token
    Gateway ->> Acquirer: Process transaction
    Acquirer -->> Gateway: Authorization result
    Gateway -->> Backend: Transaction response
    Backend -->> Frontend: Payment result
    Frontend -->> Customer: Payment confirmation

API Request Example¶

POST /api/transactions/authorize
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "reference": "ORDER-GP-001",
  "terminal_id": "TERM001",
  "description": "Google Pay payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "AUTHORIZE",
  "payment_method": {
    "type": "google-pay",
    "data": {
      "google_pay_token": "<Base64-encoded Google Pay token>"
    }
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Example Street",
    "city": "Sampletown",
    "country": "BA",
    "postal_code": "12345"
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0...",
    "accept_header": "text/html,application/xhtml+xml...",
    "java_enabled": false,
    "color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "time_zone_offset": -120,
    "language": "en-US"
  },
  "metadata": {},
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

Google Pay Payment Data Fields¶

Field	Type	Required	Description
`payment_method.type`	`string`	Yes	Must be `"google-pay"`
`payment_method.data.google_pay_token`	`string`	Yes	Base64-encoded Google Pay payment token

Token Encoding

The Google Pay token received from the Google Pay API is a JSON string. You must Base64-encode the entire token string before sending it to the Payment Gateway.

Google Pay Token Structure¶

For reference, the Google Pay token (paymentData.paymentMethodData.tokenizationData.token) is a JSON string with the following structure:

{
  "signature": "MEUCIQDk...",
  "intermediateSigningKey": {
    "signedKey": "{\"keyValue\":\"MFkwEw...\",\"keyExpiration\":\"1234567890000\"}"
  },
  "protocolVersion": "ECv2",
  "signedMessage": "{\"encryptedMessage\":\"abc123...\",\"ephemeralPublicKey\":\"BPni...\",\"tag\":\"xyz789...\"}"
}

This entire JSON string must be Base64-encoded before being sent as payment_method.data.google_pay_token.

Secure Customer Authentication (SCA/3DS) and PSD2¶

To comply with SCA (Strong Customer Authentication) and PSD2 regulations, the Payment Gateway will process Google Pay transactions through the 3DS flow when necessary.

After decrypting the Google Pay payment token, the payload contains one of two authentication methods:

Authentication Method	3DS Behavior
PAN_ONLY	3D Secure 2.0 authentication will be triggered — the customer may need to complete a 3DS challenge
CRYPTOGRAM_3DS	The payload is already authenticated — no additional 3DS step is required

Merchant Responsibility

The decryption of the Google Pay token is handled entirely by the Payment Gateway. As a merchant, you do not have visibility into whether the underlying credential is PAN_ONLY or CRYPTOGRAM_3DS. Your integration must be prepared to handle the 3DS flow (redirects and callbacks) for any Google Pay transaction.

Hosted Payment Page — HPP integration guide
API Integration — Direct API integration guide
Network Token — For merchants who decrypt Google Pay tokens themselves
Webhooks — Receive payment status notifications