Payment Element

The payment element is a pay button for one item you sell. A shopper presses it, and a checkout opens over your page: they sign in with their email (or approve in the Qatom app), pay from their Qatom wallet, and top up by card if the wallet is short. When the payment completes, your page receives a payment event, and your server confirms it before handing over what was bought.

You need two things from your Qatom account:

Quick start

Load payment-js, create the element for your item, and mount it where the button should appear.

<div id="pay"></div>

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

  if (element) {
    element.mount("#pay");
  }

  document.addEventListener("payment", (event) => {
    // event.detail: { hash, hostname, nonce, timestamp }
    // Send it to your server to confirm the payment (see below).
  });
</script>

If you build with a bundler, install the package instead of loading the script:

npm install @todaqmicro/payment-js
import { loadMicroPayments } from "@todaqmicro/payment-js";

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

Always pass { apiVersion: "main" }: it is the only version, and loadMicroPayments rejects without an options object.

What your shopper sees

  1. The pay button, on your page, showing the item’s price.

  2. Checkout, a sheet that opens from the bottom of the screen over your page. The shopper enters their email and types the code they are sent. If they use the Qatom app, they approve the sign-in there instead.

  3. Pay: the item’s total, and a Pay from choice of how to pay.

    • Credit card, the default: the card form is on the sheet, and paying charges the price to their card.
    • One of their Qatom wallets: the sheet shows the wallet’s balance and what will remain, and one tap pays from it. If the wallet cannot cover the price, they can top it up by card first.

    Card payments are processed by Stripe; card details never reach your page or Qatom. Either way, you receive the same payment.

  4. Payment complete: the sheet closes and your page receives the payment event.

A shopper with no Qatom wallet gets one as part of this; there is nothing for you to set up.

Options

Pass options to create("payment", { hash, ... }). Only hash is required; the rest change how the button looks. Each live button on this page sells the same demo item: press one to see checkout, but you don’t need to pay.

Option Type Default Section
hash string — (required) Item
theme "light" | "dark" "light" Theme
leading string the Qatom mark Label
middle string "Pay" Label
trailing string — Label
decimalPoints number, 0–6 3 Price
styles object — Look

Item: hash

The commodity hash of the item the button sells. The button shows its price, and checkout charges it. Getting started shows how to create one.

Theme: theme

Match the page the button sits on. "light", the default, draws a dark button for a light page; "dark" draws a white button for a dark page.

Label: leading, middle, trailing

The label has three parts, and each option replaces one of them:

Part Default Replaced by
Before the words the Qatom mark leading
The word before the price Pay middle
The words and the price together Pay $0.050 trailing

When trailing is set, middle and the price are not shown. Keep label text to plain ASCII for now: other characters, such as → or é, currently display garbled.

Price: decimalPoints

How many decimals the price shows, from 0 to 6. The default is 3. From npm, 0 needs payment-js 0.5.5 or later; older versions drop it and keep three decimals.

Look: styles

Fine-tune the button with CSS values.

Key Example What it changes
colorBackground "#4F46E5" The button’s fill.
colorPrimary "#FFFFFF" The label and the mark.
borderRadius "999px" The corners.
padding "0 20px" Space inside the button. The height stays 44px.
border "1px solid #E4EBE8" or 1 A border. A number is a width in pixels, drawn in the label’s colour.
fontFamily "Georgia, serif" The label’s typeface. Use a font every system has, or leave the default.

Keys you leave out keep the theme’s value. Values must be plain CSS: no url(...), no <, > or \, at most 200 characters each. A value outside those rules stops the button from loading.

Putting it together

Options combine freely:

await micro.elements().create("payment", {
  hash: "<HASH>",
  decimalPoints: 2,
  trailing: "Unlock article",
  styles: {
    colorBackground: "#4F46E5",
    borderRadius: "999px",
  },
});

Mounting and removing

mount(target) takes a CSS selector or an HTMLElement, and replaces whatever that element contains with the button. The button lives in an iframe that sizes itself to fit; while checkout is open, the iframe covers the whole window, and it shrinks back to the button when checkout closes.

destroy() removes the button from the page.

element.mount(document.querySelector("#pay"));

// Later, for example when the item is no longer for sale:
element.destroy();

create() resolves to null instead of an element when the item cannot be loaded, for example when the hash does not exist. Check for it before calling mount.

The payment event

When a payment completes, payment-js dispatches a payment event on document. Its detail says what was paid:

Field What it is
hash The item that was paid for.
nonce A one-time reference to this payment.
timestamp When it was paid, in Unix seconds. With nonce it identifies the payment.
hostname The shopper’s Qatom wallet.
document.addEventListener("payment", async (event) => {
  const { hash, nonce, timestamp } = event.detail;

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

  if (response.ok) {
    // Show what was bought.
  }
});

The same event is also dispatched as purchase, an older name kept for existing pages. Listen for payment in new code.

Confirm each payment on your server

An event in the browser is not proof of payment: anyone can dispatch one. Before you hand over what was bought, have your server confirm the payment with Qatom, using your account’s access token (see Getting started). Never put that token in the page.

Check that a payment is genuine, without using it up:

curl "https://pay.m.todaq.net/v4/payment/$HASH/validate?nonce=$NONCE&timestamp=$TIMESTAMP" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A 200 returns the payment, including cost and used_at, which stays null until the payment is redeemed. A 404 means no payment matches.

Redeem it at the moment you deliver, so the same payment cannot be used twice:

curl -X POST "https://pay.m.todaq.net/v4/payment/$HASH/validate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"nonce\": \"$NONCE\", \"timestamp\": $TIMESTAMP}"

A 200 means the payment was valid and is now used. A 400 means it does not exist or was already redeemed: do not deliver. Both calls are in the API reference.

Troubleshooting

What you see Why, and what to do
create() resolves to null The item could not be loaded. Check that the hash exists in the environment you are calling.
loadMicroPayments rejects with a TypeError It was called without an options object. Pass { apiVersion: "main" }.
No button appears, and the iframe shows an error A styles value broke the rules above, or theme is not light or dark.
The payment event never fires Listen on document, not on the element, and add the listener before the shopper can pay.