Amounts, numbers & ids

The formats every endpoint shares.

Amounts

Every amount is an integer number of minor units, sent and returned as a JSON string. Strings keep large figures exact in every language, where a JSON number might be rounded.

const DECIMALS = { UGX: 0, KES: 2, GHS: 2 };

// "500.50" KES -> "50050"
function toMinor(display, currency) {
  const [whole, frac = ""] = String(display).split(".");
  const d = DECIMALS[currency];
  return (BigInt(whole) * 10n ** BigInt(d) + BigInt((frac + "0".repeat(d)).slice(0, d) || "0")).toString();
}

An amount must be greater than zero and match ^\d{1,19}$: digits only, no sign, no decimal point, no spaces. Every amount travels with its currency.

Phone numbers

Send the wallet's number in the msisdn field. International format is safest: +256772123456. SkanPay also accepts 00256772123456, and local forms such as 0772123456 or 772123456, which are read against your account's country (or the country you send). Spaces, dashes, dots and brackets are ignored.

Resolution happens in this order:

1. The number is normalised to international (E.164) form.
2. The country comes from the dialing code.
3. The number must have the right length: 9 digits after the country code in all three countries.
4. The network comes from the number's prefix, or from the network you send.

If the prefix is not one we know, or the range is shared or ported, the request fails with network_required. SkanPay never guesses a network, because a wrong guess sends money to the wrong rail. Ask the customer which network they use and pass network: "MTN" or network: "AIRTEL". A network you pass always wins over the prefix table.

Recognised prefixes

Numbers are never returned in full. Every object carries msisdn_masked, for example +2567****456, so a leaked API response or log line does not expose your customers.

Your reference

reference is your own id for the payment, usually the order id. It is returned unchanged on the object and in every webhook, and GET /v1/charges?reference=… finds it again. It is 1 to 128 characters from A–Z a–z 0–9 . _ : -.

Metadata

Charges, payouts, deposits and withdrawals accept an optional metadata object for your own data: up to 20 keys, each key at most 64 characters, each value a string (up to 512 characters), a number, a boolean or null. It is returned on the object and in webhooks. Don't put secrets or customer ID numbers in it.

Object ids

Ids are opaque strings with a type prefix. They sort by creation time, which is what makes cursor pagination work. Store them as strings of up to 64 characters.

Timestamps

created_at and updated_at are ISO 8601 in UTC, for example 2026-09-28T09:30:08.000Z. Filters such as created_after take the same format.

Request ids

Every response carries an X-Request-Id header (req_…), and every error body repeats it as request_id. Log it with your own order; it is the fastest way for support to find a request.

Rate limits

Past the limit you get 429 rate_limit_exceeded. Back off and retry. An integration that uses webhooks instead of polling stays far below these limits.

Request format

• HTTPS only. Request and response bodies are JSON (Content-Type: application/json).
• Unknown body fields are rejected, not ignored, so typos surface immediately.
• Bodies are limited to 1 MB.