Google Pay

Google Pay lets users pay with a card already saved to their device — no card entry, no redirect. The payment sheet is native and dismisses back into your app once the transaction is confirmed.

Identity creation, KYC, eligibility, and OTP must be completed before reaching the payment step. See the Integration Guide if you haven't done this yet. This guide picks up from paymentReady: true.

Google Pay via the React Native SDK is Android only.

When your Android app presents Google Pay directly, Google requires app-level approval before you can process live payments. This is separate from any approval Banxa holds.

To apply:

1. Integrate Google Pay in your app following Google's integration requirements
2. Complete the Google Pay API production access request
3. Google will review your integration and confirm approval

You can develop and test against Google Pay's test environment while your approval is in progress. See Testing below.

Once your app has Google Pay approval (or is in test mode), trigger the payment sheet after your backend confirms paymentReady: true:

import {
  isPrimerCheckoutWebViewResult,
} from '@banxa-official/react-native-sdk';

const result = await banxa.buy.createOrderAndShowPrimerCheckout(orderRequest, {
  paymentMethod: 'googlePay',
  callbacks: {
    onCheckoutComplete: () => {
      // Google Pay confirmed — transaction is in progress
    },
    onError: (error) => {
      // Google Pay unavailable or failed — see error handling below
    },
    onDismiss: () => {
      // User dismissed the payment sheet without completing
    },
  },
});

if (isPrimerCheckoutWebViewResult(result)) {
  // Google Pay unavailable for this session — SDK fell back to hosted WebView
  render(<CheckoutWebView {...result.webViewProps} />);
}

The orderRequest must include externalCustomerId — pass the same identityReference you used for eligibility.

onError is called when Google Pay is unavailable for the current session. Common causes:

• User has not set up Google Pay on their device
• No cards added to Google Pay
• None of the user's cards match supported networks
• Device doesn't support Google Pay

Google Pay provides a test environment that returns simulated payment results without processing real transactions. Use this during development before your production approval is confirmed.

const banxa = new Banxa({
  environment: 'sandbox',
  // ...
});

Google Pay can be tested on a physical Android device or on an Android emulator with Google Play Services installed.

The error codes below are Primer errors surfaced through the SDK.

Google Pay button does not appear

Google Pay is not available for the current user or session. Common reasons:

• User has not set up Google Pay on their device
• No cards added to Google Pay
• None of the user's cards match supported networks
• Device does not have Google Play Services

The SDK filters Google Pay from available payment methods in these cases. Only show a Google Pay option when the SDK confirms it is available.

Google Pay sheet appears in test but fails in production

Your app has not yet received Google Pay production approval. Ensure your production access request has been approved by Google before releasing to users.

[unable-to-present-payment-method]

Google Pay is not available for this session. See causes above.

[payment-cancelled]

The user dismissed the Google Pay sheet without completing payment. No action required — handle via onDismiss or onError in your callbacks.

Before releasing to production:

• Confirm your Google Pay production approval is active
• Switch to production credentials in the SDK
• Confirm with your Banxa integration contact that your account is provisioned for production

The Embedded Payment Button renders Google Pay inside a web component — no SDK install required. It is a web integration for Vanilla JS, React, and Vue apps. No additional Google Pay setup is required — Banxa's approval covers the web integration.

Before you start: Contact your Banxa integration contact to get provisioned. The button-only setting must be enabled on your environment before this works.

npm install @banxa-official/embedded-checkout-web-component

Import the package once to register the custom element:

import '@banxa-official/embedded-checkout-web-component';

Once your backend confirms paymentReady: true from eligibility, create an order. This returns a checkoutUrl which you pass to the web component.

POST /{partner}/v2/buy
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "externalCustomerId": "user-123",
  "fiat": "AUD",
  "crypto": "BTC",
  "walletAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
  "fiatAmount": "500.00",
  "redirectUrl": "https://app.yourcompany.com/complete"
}

Pass the checkoutUrl as the source attribute:

<banxa-checkout source="https://checkout.banxa.com/..."></banxa-checkout>

The component stays hidden until the checkout page signals it is ready — at that point it resizes to fit the payment button and becomes visible.

Lifecycle callbacks

Assign functions to these properties on the element instance:

Each callback receives a detail object, not a DOM event.

<script type="module">
  import '@banxa-official/embedded-checkout-web-component';
</script>

<banxa-checkout id="checkout" source="https://checkout.banxa.com/..."></banxa-checkout>

<script>
  const el = document.getElementById('checkout');
  el.onLoading = (detail) => console.log('loading', detail);
  el.onReady = (detail) => console.log('ready', detail);
  el.onPaymentPending = (detail) => console.log('payment pending', detail);
  el.onComplete = (detail) => console.log('complete', detail);
  el.onError = (detail) => console.log('error', detail);
</script>

Before releasing to production:

• Confirm with your Banxa integration contact that your environment is provisioned for the Embedded Payment Button
• Switch to production credentials for order creation

The JS Native Payments SDK renders Google Pay in the native payment sheet directly on your page through the <banxa-primer-checkout> web component. Unlike the Embedded Payment Button, it is not limited to a button: the same component can present cards and Google Pay together. It is a web integration for Vanilla JS, React, and Vue apps.

npm install @banxa-official/javascript-native-payments-sdk @primer-io/primer-js

@primer-io/primer-js is the peer dependency that powers the native payment sheet.

Because the Google Pay sheet renders on your own web domain rather than a Banxa-hosted surface, your domain needs its own Google Pay approval before you can process live payments. This is how Google Pay's registration model works for any merchant that renders the button on its own surface: Banxa's website approval does not extend to your domain. Established Google Pay integrators require the same of their headless partners.

To go live:

1. Create a Google Pay Business Profile and accept the Terms of Service in the Google Pay & Wallet Console.
2. Obtain your own Merchant ID.
3. Submit your specific domain for review, following Google Pay: Publish your integration.

Payments are processed through Primer as the gateway, so you do not need your own PCI DSS attestation. That does not exempt you from registering your own domain and obtaining Google's approval for it. See the Google Pay integration checklist. Coordinate with your Banxa integration contact so your Merchant ID and domain are configured correctly on Banxa's side.

Once your backend confirms paymentReady: true from eligibility, create the order and return the nativeToken (the Primer client token) to your page. Keep your API key server-side.

import { BanxaApiClient } from '@banxa-official/javascript-native-payments-sdk';

const client = new BanxaApiClient({ apiKey, partner, environment: 'sandbox' });

const order = await client.createOrder({
  externalCustomerId: 'user-123', // the same identityReference used for eligibility
  fiat: 'AUD',
  crypto: 'BTC',
  fiatAmount: '500.00',
  walletAddress: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq',
  redirectUrl: 'https://app.yourcompany.com/complete',
});

// return order.nativeToken to the browser

Register the component, include GOOGLE_PAY in payment-methods, and set the token returned by your backend.

<script type="module">
  import { registerBanxaPrimerCheckout } from '@banxa-official/javascript-native-payments-sdk/web';
  registerBanxaPrimerCheckout();
</script>

<banxa-primer-checkout id="checkout" payment-methods="GOOGLE_PAY" locale="en"></banxa-primer-checkout>

<script type="module">
  const { nativeToken } = await (await fetch('/api/create-order', { method: 'POST' })).json();

  const checkout = document.getElementById('checkout');
  checkout.clientToken = nativeToken;

  checkout.addEventListener('banxa:payment-success', () => { /* Google Pay confirmed */ });
  checkout.addEventListener('banxa:payment-failure', () => { /* payment failed */ });
</script>

To offer Google Pay alongside cards in one sheet, set payment-methods="PAYMENT_CARD,GOOGLE_PAY".

• Complete your own Google Pay approval for your production domain (Business Profile, Merchant ID, and domain review)
• Install the @primer-io/primer-js peer dependency in your production build
• Switch to production credentials for order creation

For the full component API (attributes, events, layout modes), see the JS Native Payments SDK Reference.