# 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](https://docs.swarmbyte.com/field-reference.md). Shared errors: [Errors overview](https://docs.swarmbyte.com/errors-overview.md).

Source: https://docs.swarmbyte.com/integration