Google Pay: Drop In Guide

Integrate Google Pay on your website or mobile application with just a few lines of code.

Before you begin

This guide assumes that you know how to

• Show Drop-in Checkout

Accept payments with Google Pay

Prepare the client session

Google Pay requires the following data to process a payment successfully. Pass the following data in the client session, or in the payment request (for manual payment creation).

Parameter Name	Required	Description
currencyCode	✓	3-letter currency code in ISO 4217 format, e.g. USD for US dollars
order ↳ lineItems		Details of the line items of the order
order ↳ countryCode	✓	The merchant’s country (ISO 3166-1 alpha-2) — where the transaction is processed, not the buyer’s country

order.countryCode maps to Google Pay’s TransactionInfo.countryCode: “The ISO 3166-1 alpha-2 country code where the transaction is processed.” Use the country of your acquiring entity (for example, if your acquirer is in the EEA, this is required for SCA compliance).

Prepare the SDK for payments

Web

Show Universal Checkout

Google Pay is automatically presented to the customer when calling Primer.showUniversalCheckout.

Typescript

try {
  await Primer.showUniversalCheckout(clientToken, {
    container: '#checkout-container',
    options,
    onCheckoutComplete({ payment }) {
      console.log('Checkout complete.', payment)
    },
  })
} catch (e) {
  // handle error
}

Customization

Check the Customization Guide to learn how to customize payment method buttons.

Additionally, you can style the Google Pay button by passing the following options:

Typescript

const options = {
    /* Other options... */
    googlePay: {
        buttonType: 'long', // 'long' (default) | 'short'
        buttonColor: 'black', // 'default' (default) | 'black' | 'white',
    }
}

Capture billing address

By default, Google Pay does not capture the user’s billing address.

You can ask to capture the billing address by setting the option captureBillingAddress. The billing address is added to the client session before the payment is made.

Typescript

const options = {
    /* Other options... */
    googlePay: {
        captureBillingAddress: true,
    }
}

Limitations

• Google Pay can be presented inside an Android WebView, but only when the host Android app enables WebView support for Google Pay. This is done in the app itself, following Google’s Using Android WebView guide, and requires Google Play Services 25.18.30 or later. No change is required in Primer’s SDK — Primer’s Google Pay integration works in a WebView once the app is configured.

  If the host app hasn’t enabled WebView support — or the page is opened in a third-party in-app browser that doesn’t (e.g. the Facebook, Instagram, or TikTok browser) — Google Pay won’t present its payment sheet and the button won’t be available there.

Troubleshooting

The Google Pay button does not appear

Primer drop-in checkout runs a few checks to validate that the user can pay with Google Pay.

The Google Pay button does not appear if one of these conditions is met:

• Google Pay JS library fails to be downloaded. This usually comes from a network issue on the user side.
• Google Pay believes the browser is not supported. Under the hood, the SDK uses Google Pay’s function isReadyToPay to validate this.
• The country code or the currency code are missing from the client session.

Android

Show Universal Checkout

Google Pay is automatically presented to the customer when calling Primer.instance.showUniversalCheckout.

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  private fun setupObservers() {
    viewModel.clientToken.observe(this) { clientToken ->
      showUniversalCheckout(clientToken)
    }
  }
  private fun showUniversalCheckout(clientToken: String) {
    Primer.instance.showUniversalCheckout(this, clientToken)
  }
}

Customization

Capture billing address

Capturing billing address is supported on 2.16.0+ SDK versions.

By default, Google Pay does not capture the user’s billing address.

You can ask to capture the billing address by setting the option captureBillingAddress. The billing address is added to the client session before the payment is made.

KOTLIN

val settings = PrimerSettings(
    /* Other options... */
    paymentMethodOptions = PrimerPaymentMethodOptions(
            googlePayOptions = PrimerGooglePayOptions(captureBillingAddress = true)
    ),
)

Required Existing Payment Method

Support for enabling the requirement of an existing payment method is included in SDK versions 2.27.0+.

By default, Google Pay is presented to the user regardless of whether they have a supported card in their wallet.

You can now automatically hide Google Pay if the user’s wallet does not contain a supported card by setting existingPaymentMethodRequired to true.

KOTLIN

val settings = PrimerSettings(
    /* Other options... */
    paymentMethodOptions = PrimerPaymentMethodOptions(
            googlePayOptions = PrimerGooglePayOptions(existingPaymentMethodRequired = true)
    ),
)

Collect email address

Support for collecting user’s email address is included in SDK versions 2.33.0+.

You can now collect user’s email address by setting emailAddressRequired to true.

KOTLIN

val settings = PrimerSettings(
    /* Other options... */
    paymentMethodOptions = PrimerPaymentMethodOptions(
        googlePayOptions = PrimerGooglePayOptions(emailAddressRequired = true)
    ),
)

Collect shipping address and phone number

Support for collecting user’s shipping address and phone number is included in SDK versions 2.33.0+.

You can now collect user’s shipping address and phone number by setting shippingAddressParameters to PrimerGoogleShippingAddressParameters(phoneNumberRequired = true).

KOTLIN

val settings = PrimerSettings(
    /* Other options... */
    paymentMethodOptions = PrimerPaymentMethodOptions(
        googlePayOptions = PrimerGooglePayOptions(
            shippingAddressParameters = PrimerGoogleShippingAddressParameters(phoneNumberRequired = true)
        )
    ),
)

Customize Google Pay Button Appearance

The PayButton API is a requirement for all new Android Google Pay API integrations that use a Google Pay payment button. Support for customizing Google Pay Button Appearance is included in SDK versions 2.33.0+.

You can customize the Google Pay button’s appearance by setting the buttonOptions parameter within PrimerGooglePayOptions. This allows you to modify attributes such as the button’s type and theme.

KOTLIN

val settings = PrimerSettings(
    /* Other options... */
    paymentMethodOptions = PrimerPaymentMethodOptions(
        googlePayOptions = PrimerGooglePayOptions(
            buttonOptions = GooglePayButtonOptions(
                buttonType = ButtonConstants.ButtonType.PAY,
                buttonTheme = ButtonConstants.ButtonTheme.DARK
            )
        )
    ),
)

For more details, refer to the Primer Google Pay Button Options documentation.

Restrict card types

Support for restricting credit and prepaid cards is included in SDK versions 2.52.0+.

By default, Google Pay offers all supported card types. You can restrict which card types are offered by setting allowCreditCards and allowPrepaidCards to false.

KOTLIN

val settings = PrimerSettings(
    /* Other options... */
    paymentMethodOptions = PrimerPaymentMethodOptions(
        googlePayOptions = PrimerGooglePayOptions(
            allowCreditCards = false,
            allowPrepaidCards = false
        )
    ),
)

Google Pay has no equivalent flag to disallow debit cards, so a credit-only configuration is not achievable on the platform.

React Native

Show Universal Checkout

Google Pay is automatically presented to the customer when calling Primer.showUniversalCheckout.

Typescript

const CheckoutScreen = async (props: any) => {
  const onUniversalCheckoutButtonTapped = async () => {
    try {
      await Primer.showUniversalCheckout(clientToken)
    } catch (err) {
      // handle error
    }
  }
}

Customization

Capture billing address

Capturing billing address is supported on 2.17.0+ SDK versions.

By default, Google Pay does not capture the user’s billing address.

You can ask to capture the billing address by setting the option isCaptureBillingAddress. The billing address is added to the client session before the payment is made.

Typescript

let settings: PrimerSettings = {
    paymentMethodOptions: {
        /* Other options... */
        googlePayOptions: {
         isCaptureBillingAddressEnabled: true
        }
    },
};

Required Existing Payment Method

Support for enabling the requirement of an existing payment method is included in SDK versions 2.21.0+.

By default, Google Pay is presented to the user regardless of whether they have a supported card in their wallet.

You can now automatically hide Google Pay if the user’s wallet does not contain a supported card by setting isExistingPaymentMethodRequired to true.

Typescript

let settings: PrimerSettings = {
    paymentMethodOptions: {
        /* Other options... */
        googlePayOptions: {
         isExistingPaymentMethodRequired: true
        }
    },
};

Collect email address

Support for collecting user’s email address is included in SDK versions 2.28.0+.

You can now collect user’s email address by setting emailAddressRequired to true.

Typescript

let settings: PrimerSettings = {
    paymentMethodOptions: {
        /* Other options... */
        googlePayOptions: {
         emailAddressRequired: true
        }
    },
};

Collect shipping address and phone number

Support for collecting user’s shipping address and phone number is included in SDK versions 2.28.0+.

You can now collect user’s shipping address and phone number by setting shippingAddressParameters to { phoneNumberRequired: true }.

Typescript

let settings: PrimerSettings = {
    paymentMethodOptions: {
        /* Other options... */
        googlePayOptions: {
         shippingAddressParameters: { phoneNumberRequired: true }
        }
    },
};

Customize Google Pay Button Appearance

The PayButton API is a requirement for all new Android Google Pay API integrations that use a Google Pay payment button. Support for customizing Google Pay Button Appearance is included in SDK versions 2.28.0+.

You can customize the Google Pay button’s appearance by setting the buttonOptions parameter within IPrimerGooglePayOptions. This allows you to modify attributes such as the button’s type and theme.

Typescript

let settings: PrimerSettings = {
    paymentMethodOptions: {
        /* Other options... */
        googlePayOptions: {
            buttonOptions: {
          buttonTheme: PrimerGooglePayButtonConstants.Themes.Dark,
          buttonType: PrimerGooglePayButtonConstants.Types.Checkout
        }
        }
    },
};

For more details, refer to the Primer Google Pay Button Options documentation.

Restrict card types

Support for restricting card types is included in SDK versions 2.46.0+.

By default, Google Pay offers all supported card types. You can restrict which card types are offered by setting allowedCardTypes to any combination of credit, debit, and prepaid.

Typescript

let settings: PrimerSettings = {
    /* Other options... */
    paymentMethodOptions: {
        googlePayOptions: {
            allowedCardTypes: ["debit"]
        }
    },
};

Limitations

Google Pay is not compatible with iOS. The payment method button will not be presented.

Go live

You don’t need to do anything particular to go live — just make sure to use production credentials.