Google Pay Integration

Accept payments using cards stored in Google Pay

Google Pay allows customers to make payments using cards they've saved in their Google account. Instead of manually entering card details, customers can complete checkout by selecting a card from their Google Pay wallet and confirming payment. This provides a faster, more convenient payment experience across desktop and mobile devices.

Google Pay is available on Chrome, Edge, and other Chromium-based browsers on Android, iOS, macOS, Windows, and Linux. For other payment methods, see Payment Form or Apple Pay.

When to Use Google Pay

Use Google Pay when you want to provide a fast, streamlined checkout experience for customers using Chrome or other Chromium-based browsers. Google Pay is ideal for cross-platform applications that need to support both mobile and desktop users.

Benefits of Google Pay

Faster Checkout: Customers can complete payment by selecting a saved card without typing details
Improved Conversion: Reduced friction in checkout leads to higher completion rates
Cross-Platform: Works consistently across Android, iOS, desktop, and mobile web
Enhanced Security: Google Pay uses tokenization to protect card data
Trust and Familiarity: Customers recognize and trust the Google Pay brand
Broad Compatibility: Works on Chrome, Edge, and other Chromium browsers

Common use cases

E-Commerce Checkout: Streamline checkout for online shoppers
Subscription Signup: Reduce friction during subscription enrollment
Quick Purchases: Enable impulse purchases with streamlined payment
Recurring Payments: Save payment methods for subscription billing
Mobile Commerce: Provide optimized checkout for mobile shoppers
Cross-Device Experiences: Consistent payment across phones, tablets, and computers

Google Pay Availability

Google Pay is available in specific environments and requires certain conditions to work properly.

Supported Browsers and Platforms

Google Pay is available on:

Chrome 61 or later on Android, iOS, macOS, Windows, Linux
Edge 79 or later on Android, iOS, macOS, Windows
Other Chromium-based browsers (Brave, Opera, Vivaldi, etc.)

Browser Compatibility: Google Pay is only available in Chromium-based browsers. It will not work in Safari (except on Android) or Firefox. Always check for availability using the callback function provided by the SDK.

Checking Availability

The SDK provides a callback to detect if Google Pay is available:

form.googlepay(
  (available) => {
    const el = document.getElementById('google-pay-button')
    if (available) {
      if (el) el.style.display = 'block'
    } else {
      if (el) el.style.display = 'none'
    }
  }
)

Account Activation

Before you can accept Google Pay payments, you must activate Google Pay for your Payload account by registering with the Google Pay Business Console.

Step 1: Create a Business Profile

Navigate to Google Pay Business Console (opens in a new tab)
Sign in with your Google account
Create a new business profile
Enter your business information (must match your Payload merchant application)

Business Information: Ensure the business name, address, and contact information match what was submitted with your merchant application to Payload. Inconsistencies may cause delays in approval.

Step 2: Create a Website Integration

Configure your website for Google Pay:

Navigate to the Integrations tab in Google Pay Business Console
Click Add website under the Integrate with your website section
Enter the URL where your checkout page will be hosted
Select Gateway as your integration type
Upload the requested screenshots of your checkout flow
Save your changes
Click Submit for approval

Approval Process: Google will review your integration and typically responds within a few business days. You cannot accept live Google Pay payments until your integration is approved.

Step 3: Provide Merchant ID to Payload

After your integration is approved:

Copy the Merchant ID from the upper right corner of the Google Pay Business Console
Log into your Payload account
Navigate to Settings > Features & Add-ons > Google Pay
Paste the Merchant ID into the Google Pay Merchant ID field
Save your settings

Your Payload account is now configured to accept Google Pay payments.

Integrating with Payment Forms

Use Google Pay with the Payment Form SDK to process payments immediately. This is ideal for checkout flows where customers pay for products or services.

intent.py

googlepay.html

googlepay.js

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
from flask import Flask, jsonify
 
app = Flask(__name__)
 
@app.route('/payment-form-intent', methods=['POST'])
def create_payment_intent():
    # Create a payment form intent
    intent = pl.Intent.create(
        type='payment_form',
        payment_form={
            'payment_template': {
                'amount': 100.00,
                'description': 'Order #12345',
                'receiver': {
                    'account_id': 'acct_receiver123'
                }
            }
        }
    )
 
    # Send the token to your frontend
    return jsonify({'token': intent.token})

<!DOCTYPE html>
<html>
<head>
  <script src="https://payload.com/Payload.js"></script>
  <script src="https://pay.google.com/gp/p/js/pay.js"></script>
</head>
<body>
  <form id="payment-form" pl-form="payment">
    <label>Amount</label>
    <input type="number" pl-input="amount" value="100.00" required />
 
    <label>Description</label>
    <input type="text" pl-input="description" value="Purchase" required />
 
    <label>Account Holder Name</label>
    <input type="text" pl-input="account_holder" required />
 
    <label>Billing ZIP Code</label>
    <input type="text" pl-input="billing_address[postal_code]" required />
 
    <div id="google-pay-button"></div>
  </form>
 
  <script src="googlepay.js"></script>
</body>
</html>

// Fetch client token from your server
fetch('/payment-form-intent', { method: 'POST' })
  .then(res => res.json())
  .then(data => {
    // Initialize Payload with the client token
    Payload(data.token)
 
    // Initialize the payment form
    const form = new Payload.Form(document.getElementById('payment-form'))
 
    // Create Google Pay button
    const paymentsClient = new google.payments.api.PaymentsClient({
      environment: 'PRODUCTION' // Use 'TEST' for testing
    })
 
    const button = paymentsClient.createButton({
      onClick: () => {} // Handled by Payload.googlepay
    })
 
    document.getElementById('google-pay-button').appendChild(button)
 
    // Activate Google Pay on the button
    form.googlepay(button, function(active) {
      if (!active) {
        // Google Pay is not available on this device
        button.style.display = 'none'
        console.log('Google Pay is not available')
      }
    })
 
    // Handle successful payment
    form.on('processed', (evt) => {
      console.log('Payment processed:', evt.transaction_id)
      window.location.href = `/payment/success?txn=${evt.transaction_id}`
    })
 
    // Handle declined payment
    form.on('declined', (evt) => {
      console.error('Payment declined:', evt.message)
      alert('Payment declined. Please try a different payment method.')
    })
 
    // Handle errors
    form.on('error', (evt) => {
      console.error('Error:', evt.message)
      alert('Payment failed: ' + evt.message)
    })
  })

This example shows the complete flow for accepting Google Pay payments:

Backend: Create an intent with type='payment_form' and configure payment amount
Frontend HTML: Add a button with pl-googlepay attribute
Frontend JavaScript: Initialize the form and activate Google Pay with .googlepay()
Event Handling: Listen for processed, authorized, or declined events

When the customer clicks the Google Pay button:

Google's payment sheet opens with available cards from their Google account
Customer selects a card and confirms payment
Payment is processed immediately
The processed event fires with the transaction ID

Integrating with Payment Method Forms

Use Google Pay with the Payment Method Form SDK to save payment methods for future use. This is ideal for subscription signups, wallet management, and recurring billing setup.

intent-server.py

googlepay.html

googlepay.js

import payload
from flask import Flask, jsonify
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
app = Flask(__name__)
 
 
@app.route('/create-payment-method-intent', methods=['POST'])
def create_intent():
    # Create an intent for a payment method form
    intent = pl.Intent.create(
        type="payment_method_form",
        payment_method_form={
            "payment_method_template": {
                "account_id": "acct_customer123",
                # Optionally configure defaults
                'transfer_type': 'two_way',
            }
        },
    )
 
    # Return the client token to the frontend
    return jsonify({'client_token': intent.token})
 
 
 
if __name__ == "__main__":
    app.run(port=3000)

<!DOCTYPE html>
<html>
<head>
  <script src="https://payload.com/Payload.js"></script>
  <script src="https://pay.google.com/gp/p/js/pay.js"></script>
</head>
<body>
  <form id="payment-method-form" pl-form="payment_method">
    <label>Account Holder Name</label>
    <input type="text" pl-input="account_holder" required />
 
    <label>Billing ZIP Code</label>
    <input type="text" pl-input="billing_address[postal_code]" required />
 
    <div id="google-pay-button"></div>
  </form>
 
  <script src="googlepay.js"></script>
</body>
</html>

// Fetch client token from your server
fetch('/payment-method-form-intent', { method: 'POST' })
  .then(res => res.json())
  .then(data => {
    // Initialize Payload with the client token
    Payload(data.token)
 
    // Initialize the payment method form
    const form = new Payload.Form(document.getElementById('payment-method-form'))
 
    // Create Google Pay button
    const paymentsClient = new google.payments.api.PaymentsClient({
      environment: 'PRODUCTION' // Use 'TEST' for testing
    })
 
    const button = paymentsClient.createButton({
      onClick: () => {} // Handled by Payload.googlepay
    })
 
    document.getElementById('google-pay-button').appendChild(button)
 
    // Activate Google Pay on the button
    form.googlepay(button, function(active) {
      if (!active) {
        // Google Pay is not available on this device
        button.style.display = 'none'
        console.log('Google Pay is not available')
      }
    })
 
    // Handle successful payment method creation
    form.on('success', (evt) => {
      console.log('Payment method created:', evt.payment_method_id)
      window.location.href = '/account/payment-methods?success=true'
    })
 
    // Handle errors
    form.on('error', (evt) => {
      console.error('Error:', evt.message)
      alert('Failed to save payment method: ' + evt.message)
    })
  })

This example shows the complete flow for saving Google Pay payment methods:

Backend: Create an intent with type='payment_method_form'
Frontend HTML: Add a button with pl-googlepay attribute
Frontend JavaScript: Initialize the form and activate Google Pay with .googlepay()
Event Handling: Listen for success or error events

When the customer clicks the Google Pay button:

Google's payment sheet opens with available cards
Customer selects a card and confirms
Payment method is saved without processing a payment
The success event fires with the payment method ID

Setting Account Defaults

Configure the saved payment method as the default for automatic billing:

# On your backend
intent = pl.Intent.create(
    type="payment_method_form",
    payment_method_form={
        "payment_method_template": {
            "account_id": "acct_abc123",
            "account_defaults": {
                "paying": "payments"  # Make this the default payment method
            }
        }
    }
)

Styling the Google Pay Button

You can customize the Google Pay button appearance using Google's standard button types and themes, or create a custom button.

Using Google Pay Button Styles

Google provides standard button styles that follow their brand guidelines:

<button pl-googlepay class="gpay-button"></button>

.gpay-button {
  background-color: #000;
  background-image: url("https://www.gstatic.com/instantbuy/svg/dark_gpay.svg");
  background-origin: content-box;
  background-position: center center;
  background-repeat: no-repeat;
  background-size: contain;
  border: 0;
  border-radius: 4px;
  height: 40px;
  min-width: 90px;
  padding: 11px 24px;
  cursor: pointer;
}
 
.gpay-button:hover {
  background-color: #3c4043;
}

Button Color Options

Google Pay offers different button themes:

/* Black button (recommended) */
.gpay-button-black {
  background-color: #000;
  background-image: url("https://www.gstatic.com/instantbuy/svg/dark_gpay.svg");
}
 
/* White button */
.gpay-button-white {
  background-color: #fff;
  background-image: url("https://www.gstatic.com/instantbuy/svg/light_gpay.svg");
  border: 1px solid #dadce0;
}

Custom Button with Logo

Alternatively, create a custom button with the Google Pay logo:

<button pl-googlepay class="custom-google-pay">
  <img src="/google-pay-mark.svg" alt="Google Pay" />
  <span>Pay with Google Pay</span>
</button>

.custom-google-pay {
  background-color: #000;
  color: #fff;
  border: none;
  border-radius: 4px;
  padding: 12px 24px;
  font-size: 16px;
  display: flex;
  align-items: center;
  gap: 8px;
  cursor: pointer;
}
 
.custom-google-pay:hover {
  background-color: #3c4043;
}
 
.custom-google-pay img {
  height: 20px;
}

Google Pay Brand Guidelines: Follow Google's Brand Guidelines (opens in a new tab) for button design to ensure your implementation meets Google's requirements and maintains brand consistency.

Handling Events

The Payment Form SDK emits events specific to Google Pay interactions and payment processing.

Success Events

form.on('success', (evt) => {
  console.log('Payment processed:', evt.transaction_id)
  if (evt.payment_method_id) {
    console.log('Payment method saved:', evt.payment_method_id)
  }
  window.location.href = `/success?txn=${evt.transaction_id}`
})

Error Events

form.on('declined', (evt) => {
  console.error('Payment declined:', evt.message)
  alert('Your payment was declined. Please try another card.')
})
 
form.on('error', (evt) => {
  console.error('Google Pay error:', evt.message)
  const el = document.getElementById('google-pay-button')
  if (evt.error_type === 'google_pay_not_available' && el) {
    el.style.display = 'none'
  }
})

Testing Google Pay

Testing Google Pay requires using browsers that support the Google Pay API with test configurations.

Testing in Sandbox Mode

When using Payload in test mode:

Google Pay will work with test cards added to your Google account
No actual charges are processed
You can use test card numbers to simulate different scenarios

Setting Up Test Environment

To test Google Pay:

Use Chrome DevTools Device Mode:
- Open Chrome DevTools (F12)
- Click the device toolbar icon to enable device emulation
- Select a mobile device or custom viewport
Add Test Cards to Google Pay:
- Visit Google Pay (opens in a new tab)
- Add test card numbers provided by your payment processor
Test on Your Site:
- Load your checkout page in Chrome
- Click the Google Pay button
- Select a test card and complete payment

Test Cards: Use test card numbers provided by Payload or your payment processor. In test mode, Google Pay will accept these cards for testing without processing real charges.

Best Practices

Follow these best practices for optimal Google Pay integration.

User Experience

Show Google Pay prominently on checkout pages for Chrome users
Hide the button on unsupported browsers using the availability callback
Provide alternatives like manual card entry for users without Google Pay
Use standard styling that matches Google's brand guidelines
Add loading states during payment processing
Show clear error messages when payment fails

Merchant Configuration

Complete Business Console setup before launching to production
Match business information between Google Pay and Payload
Test thoroughly after receiving integration approval
Keep contact information updated in Google Pay Business Console
Monitor approval status regularly

Security

Always use HTTPS - Google Pay requires secure connections
Validate on backend - Don't rely solely on frontend validation
Keep integration updated - Follow Google Pay API updates

Testing

Test on multiple browsers - Verify Chrome, Edge, and other Chromium browsers
Test all card networks - Ensure Visa, Mastercard, Amex, and Discover work
Test error scenarios - Verify declined payments are handled gracefully
Test cancellation - Ensure the experience when users cancel is acceptable
Test on mobile - Verify the mobile experience is optimized

Next Steps

Enhance your payment experience with additional features and payment options

Manage Payments and Subscriptions

Use Payment Processing to understand the payment lifecycle and status tracking, monitor Transaction Status to check payment states, set up Recurring Payments for automatic billing with saved methods, and explore Autopay Overview to learn how Autopay enrollment works.

Add More Payment Options

Accept Apple Pay payments from Apple Pay users, enable instant bank account payments with Plaid, and build custom forms with Payment Form for manual card and bank account payments.

Monitor and Analyze Payments

Use Webhook Events to monitor payment events in real-time, track payment metrics with Reporting Overview, and analyze payment data with Transaction Reports.

Payment Form - Build custom payment forms
Payment Method Form - Save payment methods
Apple Pay - Apple Pay integration guide
Plaid - Plaid integration guide
Intents API Reference - Complete API reference
Transactions API Reference - Transaction API details

Apple Pay Plaid