Skip to main content

Digital Wallets

Digital wallets (e.g., Google Pay, Apple Pay, PayPal) render their own button and act as the payment initiator. For the standard pay flow, see the Getting Started Guide.

Prerequisites​

  • Method available in session: The wallet method must be present in checkout.paymentMethods.
  • Environment support: The wallet will only render on supported devices/browsers and when requirements (e.g., merchant/domain setup) are met.

Display a Wallet Button in Three Steps​

1. Locate the Method​

Find the wallet method in checkout.paymentMethods.

2. Create the Element​

Get the element with paymentMethod.getPaymentElement(options).

3. Mount It​

Mount the element using paymentElement.appendTo(target).

<div id="x-pay-button"></div>
const method = checkout.paymentMethods.value.find((method) => method.method === "googlepay");

const paymentElement = method.getPaymentElement({
    xPayButton: {
        google: {
            buttonColor: 'default',
            buttonType: 'buy',
            buttonRadius: 4
        }
    }
});

paymentElement.appendTo(document.getElementById("x-pay-button"));

Handle Incompatible Methods​

A wallet can be unsupported on the current client (e.g. Apple Pay outside Safari). Compatibility is resolved at mount time, not before: the partner SDK loads with the element, then reports incompatibility. There is no reliable pre-mount check, so design your UI to react rather than pre-filter.

When a method is incompatible, the SDK:

  1. Dispatches a fatal error on the element with internalEventCode: "pluginIsIncompatibleWithClient".
  2. Deactivates the method and removes it from checkout.paymentMethods.

Render wallet buttons from checkout.paymentMethods. An incompatible method drops out of the list on its own, so its button disappears with no extra handling.

checkout.paymentMethods.subscribe((methods) => {
  const googlePay = methods.find((m) => m.method === "googlepay");
  // Re-render your button area from the current list.
  // A method that self-disabled is already absent here.
});

Explicit: listen on the element​

To act the moment a method self-disables (remove a container, drop a section header, log), subscribe to fatalError before mounting:

paymentElement.on("fatalError", (error) => {
  if (error.internalEventCode === "pluginIsIncompatibleWithClient") {
    // Unsupported on this client. Clean up your button area.
    document.getElementById("x-pay-button").remove();
  }
});

paymentElement.appendTo(document.getElementById("x-pay-button"));

fatalError also fires for other unrecoverable errors. Check internalEventCode to tell incompatibility (pluginIsIncompatibleWithClient) apart from a genuine failure (died).

Best Practices​

  • Respect official UI: Do not alter the official button styles or behavior.
  • Order sensibly: Suggest a clear order of methods (e.g., gift card, then wallet button).
  • One clear call-to-action: Avoid showing multiple competing pay buttons at once.

Troubleshooting​

  • Button not rendering: Confirm the method exists: checkout.paymentMethods.value.find(m => m.method === "googlepay").
  • Unsupported environment: Some wallets only appear in compatible browsers/devices and locales. See Handle Incompatible Methods.

Complete examples​

Google Pay​

Loading demo…

Apple Pay​

Loading demo…