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:

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

  1. The Sign in button, on your page. It stays in place, dimmed, while the sheet is open.
  2. 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.
  3. 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.
  4. Signed in: the sheet closes and your page receives the authorized event. 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.

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.

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.

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.