Micro Documentation

Getting Started

[TOC]

Environment URLs

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

1. Obtain Your Account Details

Before diving into setting up your online micropayment, you need to ensure you have the necessary account details from TODAQ Micro. This includes obtaining account keys: public secret, client secret, client secret ID.

You can obtain your account details by sending a POST request to the account management endpoint:

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

You will receive the following JSON object which contains everything you will need:

{
   "id": 44,
   "created_at": "1755529706",
   "updated_at": "1755529706",
   "secrets": [
       {
           "public_secret": "mp_4ce48bb7ad3242a49b587f9f24e6b7de",
           "created_at": "1755529706",
           "updated_at": "1755529706"
       },
       {
           "client_id": "mid_6c9e2550dc8148aba3e8569de696125d",
           "client_secret": "mc_ef1e1579f7c04fa2b3ee1451c5c0af3b",
           "created_at": "1755529706",
           "updated_at": "1755529706"
       }
   ]
}

Make note of the public_secret, client_secret, and client_id as you’ll need these for subsequent steps.

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. Pricing Strategy

Decide on your pricing strategy, whether it’s dynamic or static pricing.

3.a. Static Pricing: Set fixed prices for your products or services.

Static pricing is the easiest route and eliminates extra back and forth network requests. Follow these steps to create a commodity with a fixed price:

Step 1: Get an Access Token

First, obtain an access token using your client credentials:

curl -X POST "https://pay.m.todaq.net/v2/account/oauth/token" \ 
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials"

Your response should look like this (access token expires in 1 hour):

{
  "access_token": "tqmt_7c34728f23b244eda907847982408b92",
  "expires_at": "1755546848",
  "refresh_token": "tqmt_5849fa5adc124e919a778ad228099363",
  "refresh_expires_at": "1755546848"
}

Step 2: Get Available Digital Quantities (DQ)

Fetch available digital quantities:

curl -X GET "https://pay.m.todaq.net/v3/dq"

Your response should look like this:

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

Step 3: Create a Twin

A Twin is your digital wallet/merchant account that will own commodities and receive payments. Think of it as your business account in the TODAQ Micro system.

Use the DQ to create a Twin and get a Twin ID:

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

Your response should look like this (save this for future reference):

{
  "id": 3992,
  "hostname": "41b6fd6082ecbb5b6eab63c6a0317fcd.micro.biz.todaq.net",
  "key": "7bf70690-bd62-48f8-ae69-396ca0628534",
  "balances": {
    "412964f209c966234250eba05d1a118da128925084df9f5459eb9243157e452e73": 0
  }
}

Step 4: Create Your Commodity

A Commodity represents a sellable item (like an article, download, or service) that belongs to your Twin. The twin_id links the commodity to your digital wallet - when someone purchases this commodity, the payment will go to your Twin’s balance.

You can create multiple commodities with the same Twin ID (one Twin can own many products):

curl -X POST "https://pay.m.todaq.net/v2/commodity/" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"descriptor": "VEGEMITE.SANDWICH", "dq": "412964f209c966234250eba05d1a118da128925084df9f5459eb9243157e452e73", "cost": 15.00, "twin_id": 3992 }'

Your response should look like this:

{                                            
  "hash": "e3bd5945-851f-43de-b487-a9706576c905",
  "descriptor": "VEGEMITE.SANDWICH",
  "dq": "412964f209c966234250eba05d1a118da128925084df9f5459eb9243157e452e73",
  "cost": 15,
  "hostname": "41b6fd6082ecbb5b6eab63c6a0317fcd.micro.biz.todaq.net"
}

Congratulations! You’ve successfully created a commodity that’s owned by your Twin. Save the hash value as you’ll need it for the payment element in step 5.

Twin-Commodity Relationship Summary

For more details, see the Twins API reference and Commodities API reference.

3.b. Dynamic Pricing: Adjust prices based on market demand, customer behavior, or other factors.

TBA. Check out the Payment Node.JS SDK.

4. Integrating Micropayments Library into Your Project

Choose an import mechanism that suits your project requirements and integrate it into your website or application.

You can use either from a CDN:

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

Note: type="module" and crossorigin="anonymous" are required attributes.

Or through npm and have the bundler of your choice include it in the build files.

npm install --save @todaqmicro/payment-js

5. Generating Payment Element on Page Load

Implement code to generate the payment element dynamically when the page loads. This element will allow users to initiate purchases directly from your website or application.

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

const elements = micro.elements();
const element = await elements.create('payment', {
  // Replace <HASH> with the commodities hash.
  hash: '<HASH>',
  theme: "light",
  styles: {
    colorPrimary: '#000000',
    colorBackground: '#FDB902',
    borderRadius: '0',
  },
});

Replace <PUBLIC_SECRET> with your account’s public secret obtained in step 1, and <HASH> with the commodity hash from step 3a.

6. Mounting Payment Element on Your Webpage

Designate a suitable location on your webpage to mount the payment element. Consider user experience and accessibility when placing the payment interface to maximize conversion rates.

if (element) {
  element.mount("#signup-submit");
}

The mount function takes a string and is fed into the querySelector function so anything that works there will work when given to the mount function.

7. Listening for Purchase Events

Set up event listeners to detect when users initiate purchases or interact with the payment interface. This functionality will enable you to track user actions and respond accordingly to the purchase.

When a payment has been made a payment event is emitted on the HTML document DOM element. Simply add an event listener and then you can validate the payment with the validatePayment function on the server side.

document.addEventListener('payment', async (nonce) => {
  // Validate payment and then provide content to the user.
});

8. Validating Purchases

Implement validation logic to verify the legitimacy of purchases and ensure that transactions meet your business rules and requirements. This step is essential for preventing fraudulent activities and maintaining the integrity of your payment system.

Check out the Node.JS SDK reference guide for validating payments.