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
- Twin = your digital wallet and merchant account (receives payments)
- Commodity = your product listing (what customers buy), with its price and its
twin_id - Catalog item = the sales record behind the commodity. Creating a commodity also creates a plain catalog item for it (
catalog_item_idin the response), and points the commodity’s twin at that item before the call answers. If the twin refuses the price, the call fails with502and nothing is created. - Payment flow: a customer buys the commodity, the payment goes to the owning twin’s balance, and the sale is recorded against the catalog item, whether it was made through the payment element or another route.
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.