Getting Started

This guide takes you from no account to a working pay button: you create a Qatom account, get an access token, create a twin to be paid into and a commodity to sell, then put the payment element on your page and confirm each payment on your server.

Environment URLs

Staging: https://pay.stage.m.todaq.net
Production: https://pay.m.todaq.net

The samples below use production. To try the flow without real money, replace https://pay.m.todaq.net with the staging URL in every command; staging has its own accounts and its own digital quantity.

1. Obtain Your Account Details

Before diving into setting up your online micropayment, you need account details: a public secret, a client ID and a client secret.

Create an account with a POST request to the account endpoint:

curl -X POST "https://pay.m.todaq.net/v4/account"

You will receive a JSON object like this one, which contains everything you will need:

{
  "id": 1234,
  "created_at": "1763424000",
  "updated_at": "1763424000",
  "secrets": [
    {
      "public_secret": "<PUBLIC_SECRET>",
      "created_at": "1763424000",
      "updated_at": "1763424000"
    },
    {
      "client_id": "<CLIENT_ID>",
      "client_secret": "<CLIENT_SECRET>",
      "created_at": "1763424000",
      "updated_at": "1763424000"
    }
  ]
}

Store the public_secret, client_id and client_secret now: this response is the only time the client secret is returned. The public secret goes in your web page; the client ID and client secret stay on your server.

The commands that follow read them from shell variables:

CLIENT_ID="<CLIENT_ID>"
CLIENT_SECRET="<CLIENT_SECRET>"

2. Determining Your Product

Identify what you want to sell through your online platform. Whether it’s physical goods, digital products, or services, understanding your product offering is crucial for setting up a successful micropayment system.

In this guide we will take the example of a paywall for an article or blog post. Some other examples include: Book chapter, file download, form submission, etc.

3. Create What You Sell

Each thing you sell is a commodity with a fixed price, owned by the twin that is paid when someone buys it.

Step 1: Get an Access Token

Exchange your client credentials for an access token. -u sends them as Authorization: Basic, which is all the token endpoint needs:

curl -X POST "https://pay.m.todaq.net/v4/account/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Your response should look like this:

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_at": 1763427600,
  "refresh_token": "<REFRESH_TOKEN>",
  "refresh_expires_at": 1763427600
}

The access token lasts an hour. Calling the endpoint again while it has more than five minutes left returns the same token. Keep both tokens on your server, and set the access token for the next commands:

ACCESS_TOKEN="<ACCESS_TOKEN>"

Step 2: Get Available Digital Quantities (DQ)

A digital quantity is the unit prices and balances are counted in. Fetch the available ones:

curl "https://pay.m.todaq.net/v4/dq"

On production, your response should look like this:

{
  "digital_quantities": [
    "41a9d3f9d1b412cc0075971c05fca49b8ce1ef0dcc621babad92379eda793c8894"
  ],
  "metadata": {
    "41a9d3f9d1b412cc0075971c05fca49b8ce1ef0dcc621babad92379eda793c8894": {
      "name": "USD TDN",
      "shortcode": "USD",
      "shortdescription": "US Dollar Todaized Digital Quantity"
    }
  }
}

Set the hash of the one you will price in:

DQ="<DQ_HASH>"

Step 3: Create a Twin

A Twin is your digital wallet and merchant account in one: it owns your commodities and receives their payments.

Create a twin that holds your digital quantity:

curl -X POST "https://pay.m.todaq.net/v4/twin" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"dq\": \"$DQ\"}"

Your response should look like this:

{
  "id": 1001,
  "hostname": "00000000000000000000000000000000.micro.biz.todaq.net",
  "key": "<TWIN_KEY>",
  "balances": {
    "<DQ_HASH>": 0
  }
}

Save the id: you need it to create commodities. The key authenticates operations on the twin, so treat it as a secret: keep it on your server, never put it in a page, and never share it.

Step 4: Create Your Commodity

A Commodity represents a sellable item (like an article, download, or service) that belongs to your Twin. twin_id is the id of the twin from step 3: when someone buys this commodity, the payment goes to that twin’s balance. One twin can own many commodities.

cost is the price, counted in the digital quantity’s own unit. For the USD digital quantity that is US dollars, so 0.25 is twenty-five cents, and the pay button shows it as $0.250. A cost of 0 makes the item free.

TWIN_ID=1001
curl -X POST "https://pay.m.todaq.net/v4/commodity" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"descriptor\": \"Premium article\", \"cost\": 0.25, \"dq\": \"$DQ\", \"twin_id\": $TWIN_ID}"

Your response should look like this:

{
  "id": 2001,
  "catalog_item_id": 3001,
  "hash": "00000000-0000-4000-8000-000000000000",
  "descriptor": "Premium article",
  "dq": "<DQ_HASH>",
  "cost": 0.25,
  "hostname": "00000000000000000000000000000000.micro.biz.todaq.net"
}

Congratulations! You’ve created a commodity that’s owned by your Twin. Save the hash: the payment element in step 5 uses it.

How twins, commodities and catalog items fit together

Because every sale is recorded against the catalog item, you can read your takings with GET /v4/catalog/revenue (pass catalog_item_id for one item) and look up a single sale with GET /v4/catalog/purchases/{transaction_id}. To give the item a name and description, call POST /v4/catalog/items with the commodity’s commodity_id: while the plain item is untouched, that updates it instead of adding a second one.

For the full request and response schemas, see the Twins, Commodities and Catalog sections of the API reference.

4. Integrating Micropayments Library into Your Project

Load payment-js, Qatom’s browser library, in the way that suits your project.

From the CDN:

<script type="module" crossorigin="anonymous" src="https://cdn.m.todaq.net/micropay.js"></script>

Note: type="module" and crossorigin="anonymous" are required attributes. The script sets window.loadMicroPayments.

Or install it from npm and let your bundler include it:

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

5. Generating Payment Element on Page Load

Create the payment element when the page loads. It is the button your shoppers press to pay.

const micro = await loadMicroPayments(
  // Replace <PUBLIC_SECRET> with your account's public secret.
  "<PUBLIC_SECRET>",
  { apiVersion: "main" }
);

const elements = micro.elements();
const element = await elements.create("payment", {
  // Replace <HASH> with the commodity's hash.
  hash: "<HASH>",
  theme: "light",
});

Replace <PUBLIC_SECRET> with your account’s public secret from step 1, and <HASH> with the commodity hash from step 3. Always pass { apiVersion: "main" }. For every option, including styles, see the payment element reference.

6. Mounting Payment Element on Your Webpage

Put an empty element where the button should appear:

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

Then mount the payment element into it:

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

mount takes a CSS selector or an HTMLElement. create() resolves to null when the commodity cannot be loaded, for example when the hash does not exist, so check for it before mounting.

7. Listening for Purchase Events

When a payment completes, payment-js dispatches a payment event on document. Its detail says what was paid: { hash, hostname, nonce, timestamp }.

document.addEventListener("payment", (event) => {
  const { hash, nonce, timestamp } = event.detail;
  // Send hash, nonce and timestamp to your server, which confirms the payment
  // (step 8) before you show the content.
});

8. Validating Purchases

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 access token, and redeem it so it cannot be used twice. The payment element reference shows both calls: Confirm each payment on your server.

9. Complete Working Example

See a real-world implementation of a donation page with multiple payment options in our T.R.I.E. Donation Example.

For a Vite + React + TypeScript implementation guide, see our Vite + React Donation Example.