Browser (@fianto/js)

Install the packageCopy Anchor Link

pnpm add @fianto/js

Without a bundler, use the script build instead (step 5).

Open checkout from a clickCopy Anchor Link

Call openCheckout synchronously inside the click handler, with no await or setTimeout before it. It opens the popup first and only then waits for your route, so the browser's popup blocker sees a direct response to the click.

import { fetchCheckoutSession, openCheckout } from '@fianto/js';

const MESSAGES: Record<string, string> = {
  succeeded: 'Thanks! We are confirming your payment.',
  canceled: 'Checkout canceled.',
  expired: 'That checkout link expired. Check your order status before trying again.',
  closed: 'We could not tell what happened. Check your order status before paying again.',
};

document.querySelector('#pay')?.addEventListener('click', () => {
  openCheckout({
    session: () => fetchCheckoutSession('/api/checkout', { body: { item: 'beans' } }),
    fallback: 'redirect', // the default: if the popup is blocked, send the whole page to checkout
    popup: { width: 480, height: 720 }, // the default size
  }).then(
    (result) => {
      document.querySelector('#status')!.textContent = MESSAGES[result.status] ?? '';
    },
    (error) => console.error(error),
  );
});

session is a { id, url } you already have, or a function that returns a promise of one. Use fetchCheckoutSession(endpoint, { body }) for that function: it posts body as JSON with credentials: 'same-origin' and rejects with a CheckoutSessionError (code, status, retryAfter) when your route refuses, for example payment_in_progress. It rejects with network_error when the route cannot be reached, and session_request_failed when it answers an error without a { error: { code } } body.

Clicking again while a checkout is open should bring its popup to the front rather than start a second one: focusCheckout() does that and returns false when no popup is open. A second openCheckout() call takes over the popup, and the first call resolves closed with reason superseded.

Act on the resultCopy Anchor Link

Handle popup blockers and full-page checkoutCopy Anchor Link

If the browser blocks the popup, fallback: 'redirect' sends the whole page to checkout and the promise normally never settles. With fallback: 'none', openCheckout rejects with a PopupBlockedError instead. To skip the popup entirely, use redirectToCheckout:

import { fetchCheckoutSession, redirectToCheckout } from '@fianto/js';

document.querySelector('#pay')?.addEventListener('click', () => {
  // Sends the whole page to checkout. Resolves `closed` only if the payer comes back
  // through the back/forward cache.
  void redirectToCheckout(() => fetchCheckoutSession('/api/checkout', { body: { item: 'beans' } }));
});

Or drop in <fianto-button>Copy Anchor Link

With a bundler, import '@fianto/js/button' registers the element. Without one, serve the file dist/fianto-button.global.iife.js from the installed @fianto/js on your own site, at the path your <script> tag uses. That build also sets window.Fianto to openCheckout, redirectToCheckout, fetchCheckoutSession and focusCheckout.

<script src="/fianto-button.js"></script>

<fianto-button session-endpoint="/api/checkout" data-item="beans" label="buy"></fianto-button>
<p id="status" role="status"></p>

<script>
  var button = document.querySelector('fianto-button');
  button.addEventListener('fianto:result', function (event) {
    // event.detail is the openCheckout result: { status, session_id, reason? }
    document.getElementById('status').textContent = event.detail.status;
  });
  button.addEventListener('fianto:error', function (event) {
    console.error(event.detail.code, event.detail.message); // message is for you, not the payer
  });
</script>

On click, the button posts its data-* attributes as the JSON body to session-endpoint, so data-item="beans" arrives as { "item": "beans" }. Setting the element's session property (a { id, url } or a function returning a promise of one) overrides session-endpoint. With neither, the click fires fianto:error with code no_session_source. Both events bubble and cross shadow roots, so you can listen on any ancestor.

An unknown value falls back to the default. Size it with the CSS variables --fianto-button-height (40 to 55px, default 44px), --fianto-button-radius, --fianto-button-width (default auto) and --fianto-button-focus-ring, set on the element.

When your route refuses, the button shows the payer a short line chosen by the error's code, never your route's message. After a closed result with reason unreachable, it shows "Lost track of the checkout window. Check your order status before trying again." and ignores clicks for 6 s. A click while a checkout is open brings its popup to the front.

Let the popup talk to your pageCopy Anchor Link

If your page sends a Cross-Origin-Opener-Policy header, set it to same-origin-allow-popups, or send none. With same-origin, the popup is cut off as soon as it opens checkout: the result resolves closed with reason unreachable while the payer may still be paying, and the console shows a warning naming this fix.