Developer docs
Merchant dashboard

Swarmbyte programmatic merchant API — OAuth tokens, collect, disburse, status, webhooks

Integration guide

The programmatic API is for backend systems only. A typical collection integration looks like this:

  1. Obtain a collections access token via POST /v1/oauth/collections/token (cache until shortly before expiry).
  2. Call POST /v1/collect with Authorization: Bearer, X-Idempotency-Key, and a publicly reachable HTTPS webhookUrl where your service accepts POSTs from SwarmByte.
  3. Save the returned data.transactionId and correlate it with your order or reference.
  4. Wait for asynchronous callbacks on webhookUrl, and/or poll GET /v1/collect/transactions/:transactionId using the same collections token.
  5. Acknowledge webhooks with any 2xx response. Implement handlers so the same transactionId can be delivered more than once without breaking your ledger (idempotent updates).

Webhook URL must match where you listen

The hostname in webhookUrl must be the same public endpoint that actually exposes your HTTPS route (for example, if callbacks are served on a dedicated notifications or USSD gateway host, register that origin — not an unrelated API hostname that returns 404). Use TLS with a valid certificate.

Phone number (MSISDN) format

Collect and disburse accept Ugandan mobile numbers in national form (07XXXXXXXX, 10 digits) or international form (2567XXXXXXXX, 12 digits). Normalize consistently in your codebase.

Disbursements

Use POST /v1/oauth/disbursements/token with the same API key and secret as collections, then POST /v1/disburse with the required pin (set in the merchant dashboard). Flow mirrors collections: webhook callbacks + optional status polling with the disbursements token.

Disbursement amounts (fee-on-top)

amount is the exact UGX the recipient receives. The platform withdrawal fee is charged on top from your wallet (total debit = amount + fee). In API responses, netAmount equals amount for disbursements — it is not reduced by the fee. Your wallet must have enough available balance to cover amount + fee before the request succeeds.

Exact headers and JSON keys: Field reference. Shared errors: Errors overview.