Banxa Embedded Checkout Web Component

Embed Banxa checkout in any web application via the <banxa-checkout> custom element.

Install

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

Quick start

Import the package once to register the custom element:

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

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

The module also exports the element class:

import { BanxaCheckout } from '@banxa-official/embedded-checkout-web-component';

API

Attribute

| Name | Description | |------|-------------| | source | Checkout iframe URL. When set or changed, the component mounts or reloads the iframe. Removing it unmounts the iframe. |

Callback properties

Assign functions to these properties on the element instance. Each receives a detail object (not a DOM event).

| Property | When called | |----------|-------------| | onLoading | Checkout reports loading (banxa:loading) | | onReady | Checkout is ready with dimensions (banxa:ready) | | onPaymentPending | Payment is pending (banxa:payment-pending) | | onComplete | Payment completed (banxa:payment-complete) | | onError | Checkout error (banxa:error) |

Custom events

The same lifecycle is also dispatched as DOM events. Listen with addEventListener or framework bindings (@ready in Vue, etc.).

| Event | event.detail | |-------|----------------| | loading | status from iframe message | | ready | { width, height } | | paymentPending | status from iframe message | | complete | status from iframe message | | error | { code, message } |

On banxa:ready, numeric width and height resize the iframe and make it visible. Until then the iframe stays hidden.

Vanilla HTML

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

React (use ref for callback properties)

import { useEffect, useRef } from 'react';
import '@banxa-official/embedded-checkout-web-component';

export function Checkout() {
  const checkoutRef = useRef(null);

  useEffect(() => {
    const el = checkoutRef.current;
    if (!el) return;

    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);
  }, []);

  return <banxa-checkout ref={checkoutRef} source="https://checkout.banxa.com/..." />;
}

Vue

Use camelCase for paymentPending — it matches the custom event name.

<template>
  <banxa-checkout
    source="https://checkout.banxa.com/..."
    @loading="onLoading"
    @ready="onReady"
    @paymentPending="onPaymentPending"
    @complete="onComplete"
    @error="onError"
  />
</template>

<script setup>
import '@banxa-official/embedded-checkout-web-component';

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

Checkout iframe integration

Note: This section is for teams building or hosting the checkout page loaded inside the iframe. Package consumers only need the API above.

The checkout page should postMessage objects with a type string and additional top-level fields. Messages are only handled when they originate from the component’s iframe.

{ type: string, ...fields }

| type | Fields | Component behaviour | |--------|--------|---------------------| | banxa:loading | status | Emits loading | | banxa:ready | width, height (numbers) | Resizes iframe, emits ready with { width, height } | | banxa:payment-pending | status | Emits paymentPending | | banxa:payment-complete | status | Emits complete | | banxa:error | code, message (optional) | Emits error with { code, message }; message defaults to Unknown error |

Example messages:

window.parent.postMessage({ type: 'banxa:loading', status: 'loading' }, '*');
window.parent.postMessage({ type: 'banxa:ready', width: 480, height: 640 }, '*');
window.parent.postMessage({ type: 'banxa:payment-pending', status: 'pending' }, '*');
window.parent.postMessage({ type: 'banxa:payment-complete', status: 'completed' }, '*');
window.parent.postMessage(
  { type: 'banxa:error', code: 'CHECKOUT_ERROR', message: 'Checkout failed' },
  '*'
);

Development

npm install
npm run dev          # smoke test (src)
npm run dev:examples # example app with mock checkout
npm run build
npm run preview

License

MIT