Get started

Quickstart

Four steps. One token. A working webhook. Welcome to the API.

This walkthrough takes you from I have a Theyutes account to I have a verified webhook responding in production. No SDK needed — the four code snippets below run against your live data the moment your token is minted.

1. Get an API token

Open the merchant dashboard, head to Developers → API tokens, and click New token. Pick the smallest set of scopes that covers what you're building — you can mint as many tokens as you want, so use a dedicated one per integration.

Show once

The full token string (tyk_…) is only displayed once at creation. Copy it into your secrets manager immediately — Theyutes stores only a hash and can't recover it for you.

2. Make your first request

Export your token and call GET /api/v1/orders. Pick a language below — the snippets are auto-generated from the same registry that powers the API itself, so they'll always match the live shape.

curl 'https://theyutes.com/api/v1/orders' \
  -H 'Authorization: Bearer tyk_••••••••••••••••••••••••••••••••'

Response (200 OK)

json

{
  "data": [
    {
      "id": "cl9j4k2l3000001jx8h2zfb1m",
      "number": "TY-X9K2QF",
      "status": "processing",
      "totalKobo": 4500000,
      "currency": "NGN",
      "createdAt": "2025-11-20T14:22:31.000Z",
      "customer": {
        "name": "Adaeze Okonkwo",
        "email": "adaeze.okonkwo12@gmail.com"
      }
    }
  ],
  "pagination": {
    "cursor": "c1a2b3c4",
    "limit": 25,
    "hasMore": false
  }
}

Every list endpoint returns a { data, pagination } envelope. To page, pass the previous pagination.cursor back as the cursor query param. See the pagination guide for the loop.

3. Set up a webhook

In the dashboard, open Developers → Webhooks and add a new endpoint. Point it at your server (a temporary tunnel like ngrok works for local dev) and subscribe to the events you care about — start with order.created.

After you save, Theyutes shows the signing secret for that endpoint. Store it as THEYUTES_WEBHOOK_SECRET in your env. Every delivery is signed with HMAC-SHA256 over the raw request body, with a timestamp baked in so replay attacks fail cleanly.

Note

Need to test before any real orders come in? Developers → Test webhook fires realistic Naija-shaped sample payloads at your endpoint on demand.

4. Verify the signature

Theyutes sends a Theyutes-Signature header on every delivery, formatted as t=<unix>,v1=<hex>. To verify: split it, recompute HMAC-SHA256 of <t>.<body>using your secret, and compare with a timing-safe equality check. Reject anything where the timestamp is more than five minutes off — that's your replay window.

Here's a complete Node implementation. The webhooks guide has Python / PHP / Go versions of the same function.

javascript

// Node 18+. No deps — uses built-in crypto + the HTTP framework
// of your choice (Express shown here).
import crypto from "node:crypto";

const SECRET = process.env.THEYUTES_WEBHOOK_SECRET;

app.post("/webhooks/theyutes", (req, res) => {
  const header = req.header("Theyutes-Signature") ?? "";
  const raw = req.rawBody.toString("utf8"); // capture before JSON parse
  if (!verify(SECRET, header, raw, 5 * 60)) {
    return res.status(400).send("invalid signature");
  }
  // Safe to parse and act on the event.
  const evt = JSON.parse(raw);
  console.log(evt.event, evt.id);
  res.status(200).end();
});

function verify(secret, header, body, toleranceSeconds) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

That's it. Return a 2xx within ten seconds and Theyutes marks the delivery succeeded. Return anything else (or time out) and the retry curve kicks in: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, 24 hours. Six failures in a row and the endpoint auto-disables — you'll get a notification in the dashboard.

What's next

Authentication — scope vocabulary, IP allowlists, rotation cadence.
Webhooks — the full lifecycle, retry semantics, and verifier code in four languages.
API reference — every endpoint, with sample request bodies and responses.
Events — every webhook payload we ship, with a sample envelope per event.