Auth Element
The auth element is a Sign in with Qatom button. A shopper presses it, and a sheet opens over your page: they enter their email and type the code they are sent, or approve in the Qatom app. They then confirm which wallet to sign in with. When they do, your page receives an authorized event carrying a session: a one-hour credential your page uses to charge their wallet through the paywall, one approval at a time or against a budget they set.
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 one of your items (a commodity). The element uses it to identify your account; signing in charges nothing. Getting started shows how to create one.
Quick start
Load payment-js, create the element, mount it where the button should appear, and listen for authorized.
<div id="sign-in"></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("auth", {
hash: "<HASH>",
});
if (element) {
element.mount("#sign-in");
}
document.addEventListener("authorized", (event) => {
const { session } = event.detail;
// Keep the session for paywall calls (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 Sign in button, on your page. It stays in place, dimmed, while the sheet is open.
- Sign in, 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. A shopper who signed in on this device before skips this step.
- Confirm sign-in: their email, the wallet they are signing in with, and its balance. They can add funds by card first; card payments are processed by Stripe, and card details never reach your page or Qatom.
- Signed in: the sheet closes and your page receives the
authorizedevent. The button now reads Signed in.
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("auth", { hash, ... }). Only hash is required; the rest change how the button looks. Each live button on this page is real: press one to see the sign-in sheet, but you don’t need to sign in.
| Option | Type | Default | Section |
|---|---|---|---|
hash |
string | — (required) | Account: hash |
theme |
"light" | "dark" |
"light" |
Theme |
leading |
string | the Qatom mark | Label |
middle |
string | "Sign in" |
Label |
trailing |
string | — | Label |
styles |
object | — | Look |
Account: hash
The hash of any one of your items. The auth element uses it to identify your account; signing in charges nothing.
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 two parts:
| Part | Default | Replaced by |
|---|---|---|
| Before the words | the Qatom mark | leading |
| The words | Sign in |
middle, or trailing |
middle and trailing both replace the words; when both are set, trailing wins. Keep label text to plain ASCII for now: other characters, such as → or é, currently display garbled.
leading: "Qatom"trailing: "Members sign in"Look: styles
Fine-tune the button with CSS values, using the same keys as the payment element, so the two buttons can match.
| 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
await micro.elements().create("auth", {
hash: "<HASH>",
trailing: "Members sign in",
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 the sheet is open, the iframe covers the whole window, and your page keeps the button’s space so nothing around it moves.
destroy() removes the button from the page.
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 authorized event
When the shopper signs in, payment-js dispatches an authorized event on document:
| Field | What it is |
|---|---|
session |
The session token, a string. It is valid for one hour. |
The event also fires shortly after the element loads when the shopper already has a session on this device, so listen for it before you mount the element and treat it as “the shopper is signed in”, not “the shopper just pressed the button”.
let session = null;
document.addEventListener("authorized", (event) => {
session = event.detail.session;
// Show the signed-in parts of your page.
});
The session lets your page charge the shopper’s wallet, with their approval. Keep it in memory, never in a URL or your logs, and send it only to Qatom.
Charge through the paywall
With a session, call POST /v4/paywall with your public secret in the body and the session in the X-Session-ID header. Name the item being bought with catalog_item_id; any other properties are its arguments.
const response = await fetch("https://pay.m.todaq.net/v4/paywall", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Session-ID": session,
},
body: JSON.stringify({
public_secret: "<PUBLIC_SECRET>",
catalog_item_id: 128,
}),
});
if (response.ok) {
// Paid: the body is the response of the service you sold.
const result = await response.json();
}
Each call asks the shopper to approve it in the Qatom app, and waits until they approve or deny it, so show that you are waiting. To charge without a prompt each time, ask for a budget first: POST /v4/paywall/preauthorization with the same headers asks the shopper once, in the app, to allow spending up to an amount on one service, and later paywall calls to that service draw it down until it runs out.
| Status | What it means |
|---|---|
200 |
The payment settled. The body is your service’s response, passed through unchanged. |
400 |
Nothing was charged: the item or its arguments are not valid. problems names each argument at fault. |
401 |
The session is missing or has expired. Ask the shopper to sign in again. |
404 |
The shopper has no wallet to pay from. |
502 |
The payment or your service failed. When the body says charged: true, the shopper paid and only the delivery failed: do not retry, which would charge them again. |
The request body, the budget call and every response 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 authorized event never fires |
Listen on document, not on the element, and add the listener before you mount the element. |
A paywall call answers 401 |
The session is over an hour old. Ask the shopper to sign in again. |