Transparent payment button

Sometimes the pay button should not look like a button at all: you already have a product card, a banner or a price tag, and you want pressing it to open Qatom checkout. This guide shows how to lay a transparent payment element over a strip of your own design, what that strip can and cannot cover, and what you must add so keyboard and screen reader users can still find it.

What you can cover

The payment element is a button inside an iframe, so your page cannot click it for the shopper or make it larger than the element allows. Within those rules:

If you want the whole of a large area to open checkout, use a visible pay button next to it instead; see the Payment Element page for how to style one.

1. Mark up the area to cover

Give the card position: relative, and put an empty mount target over the strip you want to make payable. Here it covers the 44px caption at the bottom of a card.

<div class="card">
  <img src="/prints/sunset.jpg" alt="Sunset over the bay" />
  <div class="caption">Sunset print, $0.50</div>
  <div id="pay" class="pay-overlay"></div>
</div>
.card {
  position: relative;
  width: 320px;
}

.caption {
  height: 44px;
  box-sizing: border-box;
  display: flex;
  align-items: center;
  padding: 0 12px;
}

/* The strip the button covers: the caption, full width, 44px tall. */
.pay-overlay {
  position: absolute;
  left: 0;
  bottom: 0;
  width: 100%;
  height: 44px;
}

/* Stretch the element's iframe over the whole strip. payment-js sizes it
   to the button plus 100px; these rules override that. While checkout is
   open, the same rules make it fill the window. */
.pay-overlay iframe {
  display: block;
  width: 100% !important;
  height: 100% !important;
}

/* A visible focus ring, which the invisible button cannot draw itself
   (see step 4). */
.pay-overlay.is-focused {
  outline: 3px solid #1a7f64;
  outline-offset: -3px;
}

Do not give the card, or anything around it, a transform, filter or perspective. While checkout is open the iframe covers the window with position: fixed, and any of those properties on an ancestor would trap it inside the card instead. overflow: hidden on the card is fine.

2. Load payment-js

The sample in step 3 imports it from the CDN (https://cdn.m.todaq.net/micropay.js), which defines loadMicroPayments. If you build with a bundler, install the package instead and import loadMicroPayments from @todaqmicro/payment-js:

npm install @todaqmicro/payment-js

3. Create a transparent button and mount it

<script type="module">
  import "https://cdn.m.todaq.net/micropay.js";

  const micro = await loadMicroPayments("<PUBLIC_SECRET>", { apiVersion: "main" });

  const element = await micro.elements().create("payment", {
    hash: "<HASH>",
    // The button's accessible name: what a screen reader announces.
    trailing: "Buy the sunset print",
    // A space in place of the Qatom mark, whose accent colour
    // the styles below cannot make transparent.
    leading: " ",
    styles: {
      colorBackground: "transparent",
      colorPrimary: "transparent",
      // Wider than the iframe, so the button fills the whole strip.
      padding: "0 100vw 0 0",
    },
  });

  if (element) {
    element.mount("#pay");
  }
</script>

Replace <PUBLIC_SECRET> with your account’s public secret and <HASH> with the item’s hash. create() resolves to null when the item cannot be loaded, so check for it before mounting.

What each option does here:

Every create() option and styles key is described under Options on the Payment Element page.

4. Show keyboard focus

The button can be reached with Tab like any other, and Enter opens checkout. It draws its own focus ring, but the ring sits just outside the button, where the iframe clips it, so a keyboard user sees nothing. Your page cannot style the inside of the iframe, and CSS such as :focus-within on the card does not match while focus is inside a cross-origin frame. Toggle a class from script instead:

const overlay = document.querySelector("#pay");

// When focus moves into the element's iframe, this window loses focus
// and the iframe becomes the active element.
window.addEventListener("blur", () => {
  setTimeout(() => {
    overlay.classList.toggle("is-focused", document.activeElement === overlay.querySelector("iframe"));
  });
});

window.addEventListener("focus", () => {
  overlay.classList.remove("is-focused");
});

The ring also stays after a mouse click until focus leaves the button. That is expected: focus is on the button.

5. Deliver what was bought

When the payment completes, payment-js dispatches a payment event on document. Its detail carries hash, nonce, timestamp and hostname.

document.addEventListener("payment", async (event) => {
  const { hash, nonce, timestamp } = event.detail;

  if (hash !== "<HASH>") {
    return;
  }

  const response = await fetch("/purchases", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ hash, nonce, timestamp }),
  });

  if (response.ok) {
    // Deliver the print.
  }
});

The event is not proof of payment: anyone can dispatch one. Your server must confirm each payment with Qatom before it delivers; see Confirm each payment on your server.

Limits