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:
- your account’s public secret, which is safe to put in a web page, and
- the hash of the item (a commodity) the button sells. Getting started shows how to create one.
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
-
The pay button, on your page, showing the item’s price.
-
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.
-
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.
-
Payment complete: the sheet closes and your page receives the
paymentevent.
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.
theme: "light"The default.theme: "dark"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.
leading: "Qatom"middle: "Tip"trailing: "Unlock article"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.
decimalPoints: 0Whole dollars: the $0.05 demo item rounds to $0.decimalPoints: 2decimalPoints: 6Look: 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.
styles: {
colorBackground: "#4F46E5",
borderRadius: "999px",
}Your brand colour, fully rounded.styles: {
colorBackground: "#FFFFFF",
colorPrimary: "#4F46E5",
border: "2px solid #4F46E5",
}An outline button.styles: {
fontFamily: "Georgia, serif",
}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×tamp=$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. |