Wallet best practices

Serve wallets over HTTPS

Apple Pay does not render on http:// origins. Google Pay requires HTTPS in production. Test on https:// (or use your staging domain) rather than localhost where possible.

List wallets first when prominent

Wallet buttons convert much better than card forms on supporting devices. If wallets are the primary experience, list them first:

overflow.checkout({
  paymentMethods: ['applePay', 'googlePay', 'card', 'bank'],
});

Wallets that fail their availability check are hidden without shifting the remaining methods.

Match your button to the sheet

Wallet buttons are visually distinct on purpose. Pass the per-provider buttonType / buttonStyle (Apple) or buttonType / buttonColor (Google) options to match your surrounding UI, but keep the sheet’s own branding intact.

overflow.applePay({ buttonType: 'plain', buttonStyle: 'black' });
overflow.googlePay({ buttonType: 'buy', buttonColor: 'default' });

Require only what you need

Every requirement you set on require puts an extra field in the sheet the shopper must complete. Set email, phone, billingAddress, and shippingAddress only when your integration needs them.

overflow.applePay({
  require: { email: true, billingAddress: true },
});

Handle `onClick` for gating

If you need to run a check before opening the sheet (agreement acceptance, minimum order value, live inventory), listen for onClick. Return false from the handler to prevent the sheet from opening.

apple.on('onClick', () => {
  if (!acceptedTerms) {
    showBanner('Accept the terms to continue.');
    return false;
  }
});

Update `transaction` on cart changes

When the cart total changes, forward it to the wallet element with .update(...):

apple.update({
  transaction: { amount: newTotalCents, currency: 'USD', countryCode: 'US', label: 'Order total' },
});

Add the CSP entries you need

If you set a Content Security Policy, allow the wallet-specific domains that render the sheet and buttons. See the Installation page for the baseline entries; consult your provider’s CSP guidance for wallet-specific hosts.

Get started

Elements

Options

Events

Theming

Guides

Serve wallets over HTTPS

List wallets first when prominent

Match your button to the sheet

Require only what you need

Handle `onClick` for gating

Update `transaction` on cart changes

Add the CSP entries you need

Next steps

​Serve wallets over HTTPS

​List wallets first when prominent

​Match your button to the sheet

​Require only what you need

​Handle onClick for gating

​Update transaction on cart changes

​Add the CSP entries you need

​Next steps

Serve wallets over HTTPS

List wallets first when prominent

Match your button to the sheet

Require only what you need

Handle `onClick` for gating

Update `transaction` on cart changes

Add the CSP entries you need

Next steps