Wallets

Wallet elements (applePay, googlePay) render a native payment button that opens the wallet sheet on tap. The sheet drives the flow: the shopper authorizes, the SDK receives a cryptogram, and onSubmit fires with the tokenized payload ready for your server.

Availability

Wallets probe device availability at mount time. Availability depends on the shopper’s device, browser, wallet configuration, and (for Apple Pay) merchant certificate. Handle both outcomes.

const applePay = overflow.applePay();

applePay.on('onChange', ({ available }) => {
  applePayBtn.hidden = !available;
});

applePay.on('onReady', () => {
  console.log('Apple Pay ready');
});

applePay.mount('#apple-pay');

On an unavailable device, onChange fires with { available: false, reason } and onReady is suppressed. Hide the button and, if you want, render a non-wallet fallback.
On an available device, onChange fires with { available: true }, the button mounts, then onReady fires.

Availability is environment-only. It does not require a provisioned card in the wallet; the wallet sheet handles “no card” by letting the shopper add one.

Request contact details from the sheet

Ask the wallet sheet to return shopper contact and address fields by setting require:

overflow.applePay({
  transaction: { amount: 5000, currency: 'USD' },
  require: {
    email: true,
    name: true,
    phone: true,
    billingAddress: true,
    shippingAddress: true,
  },
});

Requested fields land on onSubmit.value as optional keys once the shopper authorizes:

applePay.on('onSubmit', async ({ value }) => {
  await fetch('/your-backend/authorize', {
    method: 'POST',
    body: JSON.stringify({
      email: value.email,           // present when require.email was true
      name: value.name,             // { firstName, lastName }
      phone: value.phone,           // raw sheet string
      billingAddress: value.billingAddress,
      shippingAddress: value.shippingAddress,
      paymentMethod: {
        type: value.walletType === 'applePay' ? 'applepay' : 'googlepay',
        walletToken: value.walletToken,
      },
    }),
  });
});

Fields the sheet did not return are omitted from value (never null).

Gate the sheet with `onClick`

Subscribe to onClick to validate external state before the sheet opens. The handler receives a gate primitive: call preventDefault() to interrupt the default action, then resolve() to let the sheet open or reject() to cancel.

applePay.on('onClick', (event) => {
  event.preventDefault();
  if (cart.total <= 0) {
    event.reject();
    return;
  }
  event.resolve();
});

Skipping preventDefault() opens the sheet immediately. Calling reject() fires no onError; a deliberate cancellation is not a failure.

Apple Pay synchronous constraint

Safari validates that the call that opens the Apple Pay sheet runs in the same synchronous task as the originating click. await between preventDefault() and resolve() invalidates the user gesture and the sheet fails to open, silently. Apple Pay handlers that need to gate must do so synchronously: read pre-validated state from a local variable rather than awaiting a network call. Google Pay does not have this restriction; asynchronous gating works fine.

Handle sheet dismissal with `onExit`

When the shopper dismisses the wallet sheet without authorizing, onExit fires. This is not an error; it is a deliberate dismissal.

applePay.on('onExit', () => {
  showPaymentMethodPicker();
});

Use onExit to track abandonment, re-show a payment-method picker, or restore prior UI state.

Handle failures with `onError`

Sheet errors mid-flow surface through onError with code: 'wallet_failed':

applePay.on('onError', ({ code, message }) => {
  if (code === 'wallet_failed') toast(message);
});

Note: available: false on onChange is not an error. onError is reserved for actual mid-flow failures.

Wallets inside Checkout

When a wallet is one of the tabs inside a checkout element, onClick fires with an additional paymentMethod discriminator so a single handler can branch on which wallet was tapped:

checkout.on('onClick', (event) => {
  if (event.paymentMethod === 'applePay') {
    // Apple Pay: gate synchronously.
    event.preventDefault();
    if (cart.total <= 0) { event.reject(); return; }
    event.resolve();
  } else {
    // Google Pay: async gating is fine.
    event.preventDefault();
    reserveInventory().then((ok) => ok ? event.resolve() : event.reject());
  }
});

Checkout’s onExit fires with the same paymentMethod discriminator so you can distinguish which sheet the shopper dismissed.

Get started

Elements

Options

Events

Theming

Guides

Availability

Request contact details from the sheet

Gate the sheet with `onClick`

Apple Pay synchronous constraint

Handle sheet dismissal with `onExit`

Handle failures with `onError`

Wallets inside Checkout

See also

​Availability

​Request contact details from the sheet

​Gate the sheet with onClick

​Apple Pay synchronous constraint

​Handle sheet dismissal with onExit

​Handle failures with onError

​Wallets inside Checkout

​See also

Availability

Request contact details from the sheet

Gate the sheet with `onClick`

Apple Pay synchronous constraint

Handle sheet dismissal with `onExit`

Handle failures with `onError`

Wallets inside Checkout

See also