Google Pay: Drop In Guide

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 country in which the order is created

Prepare the SDK for payments

Web
Android
React Native

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 prevents the payment sheet from being presented inside an Android webview, whether it is your own, or within a third-party (e.g. Facebook browser). As a result, Google Pay cannot be made available in this type of browser.

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.

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.

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+.

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

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.

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.

Payment methods

​Before you begin

​Accept payments with Google Pay

​Prepare the client session

​Prepare the SDK for payments

​Show Universal Checkout

​Customization

​Limitations

​Troubleshooting

The Google Pay button does not appear

​Show Universal Checkout

​Customization

​Show Universal Checkout

​Customization

​Limitations

​Go live

Before you begin

Accept payments with Google Pay

Prepare the client session

Prepare the SDK for payments

Show Universal Checkout

Customization

Limitations

Troubleshooting

Show Universal Checkout

Customization

Show Universal Checkout

Customization

Limitations

Go live