Authentication

Every request to AptaPay is signed. There is no login call and no token endpoint — you do not trade credentials for a session. You compute a signature per request, and it is valid for seconds.

If you are debugging a stubborn 401, jump straight to 401 triage. The server can only ever answer 401 for any signing failure, so the cause is never in the response body.

Your credentials

A tenant credential set is four values, issued together, per mode:

Value	Secret?	What it is
`app_id`	No	Names your application.
`key_id`	No	Names which signing-secret generation you are using.
`api_key`	Yes	Proves who is calling. Looks like `ak_live_…`.
`signing_secret`	Yes	64 hex characters. Signs requests to us.

You are also issued an outbound signing secret, which is a separate value used only to verify webhooks we send you. See Webhooks.

Live and test are completely separate credential sets. A tenant gets two. Never put either set in source control — store them in your secret manager.

The four headers

Every request except /v1/webhooks/* carries these:

X-AptaPay-Key:       <app_id>.<key_id>.<api_key>
X-AptaPay-Timestamp: <unix seconds>
X-AptaPay-Nonce:     <random string, 16-64 chars, [A-Za-z0-9_-]>
X-AptaPay-Signature: v1=<hex HMAC-SHA256, 64 chars>

X-AptaPay-Key packs three values with . as the separator. Only the third is secret.

The canonical string

The signature is an HMAC-SHA256, hex-encoded, over ten fields joined with newlines, in exactly this order:

v1
{APP_ID}
{KEY_ID}
{HOST}
{METHOD}
{PATH}
{CANONICAL_QUERY}
{TIMESTAMP}
{NONCE}
{SHA256_HEX(RAW_BODY)}

Field by field:

v1 — the scheme version, literally the string v1.
APP_ID, KEY_ID — the same values you sent in X-AptaPay-Key.
HOST — the Host header, lowercased, with no port unless your base URL includes one.
METHOD — uppercase (GET, POST, PUT, PATCH, DELETE).
PATH — the URL path only. No query string. Use the undecoded path exactly as it goes on the wire.
CANONICAL_QUERY — every query parameter, RFC3986-encoded, sorted by name then value, joined k=v&k=v. Empty string when there is no query.
TIMESTAMP — Unix seconds as a 10-digit string, matching the header.
NONCE — matching the header. Fresh and unpredictable per request.
SHA256_HEX(RAW_BODY) — SHA-256 hex digest of the exact raw bytes of the body. For a GET or DELETE with no body this is the well-known empty-string digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

A GET whose query differs from what you signed will not verify. This is deliberate: a captured read signature must not be replayable against a different query, so ?limit=1 and ?limit=100000 do not share a signature.

Reference implementation

This is the same primitive the gateway uses internally, so signing and verification are provably one scheme rather than two implementations that happen to agree today. It needs nothing but Node’s built-in crypto.

signing.ts

import { createHash, createHmac, randomUUID } from "node:crypto";

const APP_ID = process.env.APTAPAY_APP_ID!;
const KEY_ID = process.env.APTAPAY_KEY_ID!;
const API_KEY = process.env.APTAPAY_API_KEY!;
const SIGNING_SECRET = process.env.APTAPAY_SIGNING_SECRET!;
const BASE_URL = "https://api.pay.aptahq.com";

function rfc3986(s: string): string {
  return encodeURIComponent(s).replace(
    /[!'()*]/g,
    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
  );
}

/** Sorted, RFC3986-encoded query string. "" when there are no params. */
function canonicalQuery(params: URLSearchParams): string {
  const pairs = [...params.entries()].map(
    ([k, v]) => [rfc3986(k), rfc3986(v)] as const,
  );
  pairs.sort(([ak, av], [bk, bv]) =>
    ak !== bk ? (ak < bk ? -1 : 1) : av < bv ? -1 : av > bv ? 1 : 0,
  );
  return pairs.map(([k, v]) => `${k}=${v}`).join("&");
}

/** Sign one request. Returns the four headers to attach. */
export function signRequest(
  method: string,
  path: string,
  query: URLSearchParams,
  body: Buffer,
) {
  const host = new URL(BASE_URL).host.toLowerCase();
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = randomUUID().replace(/-/g, "");
  const bodyHash = createHash("sha256").update(body).digest("hex");

  const canonical = [
    "v1",
    APP_ID,
    KEY_ID,
    host,
    method.toUpperCase(),
    path,
    canonicalQuery(query),
    timestamp,
    nonce,
    bodyHash,
  ].join("\n");

  const signature = createHmac("sha256", SIGNING_SECRET)
    .update(canonical)
    .digest("hex");

  return {
    "X-AptaPay-Key": `${APP_ID}.${KEY_ID}.${API_KEY}`,
    "X-AptaPay-Timestamp": timestamp,
    "X-AptaPay-Nonce": nonce,
    "X-AptaPay-Signature": `v1=${signature}`,
  };
}

Using it for a charge:

charge.ts

const body = Buffer.from(
  JSON.stringify({
    amount_minor: 500000,
    currency: "UGX",
    country: "UG",
    method: "momo",
    payer: { msisdn: "+256700000000" },
    metadata: { order_id: "ord_123" },
  }),
);

const res = await fetch("https://api.pay.aptahq.com/v1/collections", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
    ...signRequest("POST", "/v1/collections", new URLSearchParams(), body),
  },
  body,
});

Two secrets, never one. The secret that signs your outbound requests to AptaPay and the secret AptaPay uses to sign callbacks to you are separate values, so a leak in one direction does not compromise the other.

Timestamp window

Your timestamp must be within −120s to +30s of AptaPay’s clock. The window is intentionally asymmetric: there is no legitimate reason for a client to sign meaningfully into the future.

A skewed clock reads exactly like a bad secret. If signing worked yesterday and fails today on an unchanged integration, check NTP before you check credentials.

Nonces and replay

A nonce cannot be reused inside the freshness window. Use a fresh, unpredictable value per request — a UUID with dashes stripped works well. Replaying a captured raw request is rejected. The nonce is claimed only after the HMAC verifies, so unauthenticated traffic cannot force writes on our side.

Body size

Signed request bodies are capped at 256 KB. Anything larger is rejected with body_too_large before the HMAC is even computed.

401 triage

Every signing failure returns 401 with no detail, by design. Work down this list in order:

Check your clock

Run date -u on the calling machine and compare to real UTC. Outside −120s/+30s, nothing else matters.

Confirm you signed the raw bytes

The body hash must cover the exact bytes you transmit. Serializing the object twice — once to sign, once to send — produces different bytes if key order or whitespace differs. Serialize once into a Buffer, sign that buffer, send that buffer.

Check the host field

Lowercased, and the port is included only when your base URL has one. Signing api.pay.aptahq.com:443 will not verify.Sign the host you actually dial. The host is part of the canonical string, so it must match your base URL exactly. A mismatch produces a 401 invalid_signature that looks like a bad key and is not one.

Check the query string

Sorted by name then value, RFC3986-encoded, and empty string when there is no query — not omitted, not a ?.

Confirm the nonce is fresh

A duplicated nonce inside the window is a replay rejection, which also surfaces as 401.

Confirm you are using the right secret for the mode

Live and test sets are separate. A test key against a live base URL fails.

The fastest way to find a mismatch is the Postman collection, which signs every request for you. Set debug_signing to true and it prints the canonical string to the Postman console, so you can diff it against yours. See Testing.

Rate limits

Requests are rate limited per tenant per minute. Exceeding the limit returns rate_limited, which is retriable — back off and retry with the same idempotency key. See Errors.

Getting started

Core concepts

Integration

Your credentials

The four headers

The canonical string

Reference implementation

Timestamp window

Nonces and replay

Body size

401 triage

Rate limits

​Your credentials

​The four headers

​The canonical string

​Reference implementation

​Timestamp window

​Nonces and replay

​Body size

​401 triage

​Rate limits

Your credentials

The four headers

The canonical string

Reference implementation

Timestamp window

Nonces and replay

Body size

401 triage

Rate limits