Programmatic merchant API
Server-to-server flows for collections (STK push) and disbursements (B2C). Authenticate with your merchant API key and API secret only on the two OAuth-style token endpoints; all other calls use a short-lived Authorization: Bearer token with the matching scope.
Endpoint summary
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/oauth/collections/token | Issue Bearer token (collections scope) |
| POST | /v1/oauth/disbursements/token | Issue Bearer token (disbursements scope) |
| POST | /v1/collect | Initiate collection (collections token) |
| POST | /v1/disburse | Initiate disbursement (disbursements token) |
| GET | /v1/collect/transactions/:transactionId | Collection status |
| GET | /v1/disburse/transactions/:transactionId | Disbursement status |
Production URLs: API https://core.swarmbyte.com, merchant hub https://pay.swarmbyte.com, and this documentation site https://docs.swarmbyte.com.
New to the API? Read Integration guide next, then open Field reference for header and JSON definitions. Shared error shape, validation, limits, and error handling: Errors overview. Detailed HTTP tables for each route are on the matching tab (Token (collections), Token (disbursements), Collect, Collection status, Disburse, Disbursement status).
Credentials
Use your merchant API Key as client_id and API Secret as client_secret (from the dashboard). The same pair works for both token endpoints — the URL path selects collections or disbursements scope.
Programmatic POST /v1/disburse also requires API disbursements to be enabled on your account and a disbursement PIN configured in the dashboard.
Scopes
- collections — use only for
POST /v1/collectandGET /v1/collect/transactions/:transactionId. - disbursements — use only for
POST /v1/disburseandGET /v1/disburse/transactions/:transactionId. - Calling an endpoint with the wrong scope returns 403 Forbidden with a message that the route requires the other scope.
IP allowlist
Token exchange and every Bearer request must come from an IP address on your merchant programmatic allowlist (configured in the merchant dashboard, max three entries). If the allowlist is empty, requests are rejected with 403. Responses may include a clientIp field to aid debugging.
Idempotency
POST /v1/collect and POST /v1/disburse require the X-Idempotency-Key header (non-empty; max 200 characters). A duplicate request with the same key can receive 409 Conflict if the first call is still processing and the duplicate times out while waiting; once the first call has finished, the same key typically replays the stored outcome (202). See Field reference for full semantics.
Amounts
Minimum amount per collect/disburse: 500 UGX. A maximum per transaction is also enforced server-side.
HTTP status codes (typical)
| Code | Meaning |
|---|---|
| 200 | Token issued; GET transaction succeeded |
| 202 | Collect or disburse accepted for processing |
| 400 | Validation, missing idempotency key, invalid webhook URL, amount bounds |
| 401 | Invalid credentials or Bearer token; merchant not eligible (KYC, suspended, etc.) |
| 403 | Wrong scope; IP not allowed; API disbursements disabled; wrong transaction type for GET path |
| 404 | Transaction not found |
| 409 | Idempotency: same key still in-flight (wait timeout); retries after completion replay with 202 |
| 429 | Rate limited |
| 503 | Service temporarily unavailable — retry later |
Error responses use JSON with statusCode, message, error, and usually requestId for support.
Security (integrators)
- Keep API secrets, Bearer tokens, and disbursement PINs on the server only — never in mobile apps, frontends, or public repos.
- Use HTTPS for every call to SwarmByte and for your
webhookUrl. - Rotate API credentials from the merchant dashboard if they may have been exposed.
- Log request metadata (transaction id, HTTP status) — avoid logging full PINs, secrets, or Bearer tokens.