TQ API · for developers

Sell from your own app.
We’ll handle the money.

Your website, booking system or WhatsApp bot takes the order. One API call sends a mobile-money prompt to the buyer’s phone — and TQ collects, issues the tickets and pays you out.

Create a free account → See how it works

No licenceTQ is merchant of record
One requestto start a payment
Signed webhooksthe moment it lands

POST /checkout

curl -X POST https://tqcodes.com/api/v1/checkout \
  -H "Authorization: Bearer $TQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publication_id": 101,
    "buyer": {"name": "Jane Doe", "email": "[email protected]",
              "phone": "0772123456"},
    "items": [{"type": "ticket", "item_id": 24, "quantity": 2}]
  }'

201 Created

{
  "reference": "TQ-OR-101-1788843738-5456",
  "status": "pending",
  "amount": 50000,
  "currency": "UGX",
  "prompt_sent_to": "256772123456",
  "message": "Approval prompt sent to the buyer."
}

One payment, end to end

Your app

site · bot · till

POST /checkout ▶

checkout · fulfilment

approve on phone ▶

Buyer’s phone

approves the prompt

back to you: signed webhook · tickets emailed · payout

What people build with it

If it can make an HTTPS request from a server, it can sell through TQ.

Your event website

Sell tickets on your own site, in your own design. TQ issues the QR tickets and emails them.

A WhatsApp or USSD bot

Take the order in the chat, send one request, and the buyer approves on the same phone.

A till or booking system

Charge at the counter or the gate without a card machine — the buyer pays from their phone.

Contributions & dues

Schools, churches and associations collect any amount into a TQ donation page.

Digital products

Sell downloads, or unlock a whole audio or flipbook page, from inside your own app.

Products & merch

Sell from your shop catalogue with stock kept in step across your app and your TQ page.

How it works

1

Create a key

API Keys in your dashboard. Tick only the scopes you need — the one that takes payments is never granted by default.
2

Set up what you sell

Create the event, shop or download in TQ. Prices and stock live there, so nobody can change a price from the outside.
3

Start the payment

POST /checkout with the buyer and the items. The buyer gets an approval prompt on their phone.
4

Get told

A signed order.completed webhook reaches your server the moment it lands. No polling needed.
5

Nothing else to do

Tickets, receipts and download links go out automatically, and the sale joins your normal payout.

An example, in shillings

An organiser’s website sells two early-bird tickets to a jazz night.

2 × Early bird at UGX 25,000: UGX 50,000
Platform fee (5%): − UGX 2,500
Joins your payout: UGX 47,500

Jane approves UGX 50,000 plus the 4.9% service fee on her phone.
Two QR tickets land in her inbox, ready to scan at the gate.
The organiser’s server gets order.completed with the net amount.

Know the moment it lands

Payment is asynchronous — the buyer has to reach for their phone — so TQ tells you when it’s done. Every delivery is signed with your secret and retried for more than a day if your server is down.

order.completed Payment confirmed for an order
order.fulfilled Tickets issued / download links minted
order.failed Payment attempt failed or was declined

webhook.php — verify, then acknowledge

$body = file_get_contents('php://input');
parse_str(strtr($_SERVER['HTTP_TQ_SIGNATURE'] ?? '', ',', '&'), $sig);

$expected = hash_hmac('sha256', $sig['t'] . '.' . $body, getenv('TQ_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1'] ?? ''))  { http_response_code(400); exit; }
if (abs(time() - (int)$sig['t']) > 300)         { http_response_code(400); exit; }

http_response_code(200);           // acknowledge fast, then do the work
$event = json_decode($body, true); // order.completed, order.fulfilled, order.failed

What it costs

200

credits per API key, per month

platform fee per sale

No setup fee, no contract. The fee is the same one every sale on your TQ page carries, and buyers pay a 4.9% service fee on top, never more than UGX 5,000. We email you before a key’s monthly charge if your balance is running low.

See credit prices →

Good to know first

TQ is the merchant of record. Money is collected into the TQ account and paid out to you. It can’t collect into your own merchant account.
Your catalogue lives in the dashboard. The API sells what you’ve set up there, at the price stored there.
Server to server. Keep the key on your backend, never in a browser or app bundle.
Mobile money, in UGX. The buyer approves on their own phone.

Questions developers ask

No. TQ is the merchant of record: the money is collected into the TQ platform account and paid out to you like any other sale on your TQ page. You never handle mobile-money credentials.

No. The API starts sales on your TQ storefront; it is not a way to collect into another account. If you need your own processor, you can still use TQ for QR codes, hosted pages and analytics alongside it.

With mobile money. Your request sends an approval prompt to the buyer's phone; they confirm it there, and the result reaches you by webhook. Amounts are in Ugandan shillings.

Event tickets, shop products, downloads, contributions of any amount, and access to a whole audio or flipbook page — anything you have set up on a TQ page. Items and prices are managed in the dashboard, and the API always charges the price stored there.

Each active API key costs 200 credits a month, and each sale carries the standard 5% platform fee, taken from the sale. There is no setup fee. If your balance can't cover a key on the 1st, the key pauses until you top up — we email you well before that happens.

No — call it from your server. An API key in front-end code or an app bundle can be read by anyone, and this one can take payments. Your app talks to your server; your server talks to TQ.

There is no separate sandbox. Create a low-priced test item, buy it with your own phone, and you will see the whole flow end to end — prompt, webhook, ticket email and the order in your dashboard.

Ready when your code is.

Create a key, set up what you sell, and take your first payment today. The full reference is in your dashboard under API Docs.

Create a free account → Read the API reference

Sell from your own app.We’ll handle the money.