Initiate collection

Start an STK-style collection to a Ugandan MSISDN from one of your wallets. Requires a collections-scoped Bearer token.

Headers

Authorization: Bearer <collections_access_token>
Content-Type: application/json
X-Idempotency-Key: <required, non-empty>

See Field reference for what each header means.

Body

{
  "walletAddress": "main",
  "msisdn": "256701234567",
  "amount": 50000,
  "reference": "ORDER-12345",
  "webhookUrl": "https://your-server.example/webhooks/swarmbyte"
}

Field meanings: Field reference → POST /v1/collect.

• msisdn — Uganda national format: 256 + 9 digits starting with 7, or 0 prefix form (validated server-side).
• webhookUrl — HTTPS URL for asynchronous lifecycle callbacks for this transaction (e.g. collection.initiated, collection.success; see Webhooks (incoming). Validated per environment.

Responses

• 202 Accepted — Payload includes status: "success", a human-readable message (depends on immediate provider outcome), and data with transactionId, amount, fee, netAmount, status, provider, createdAt.
• 400 — Missing idempotency key, validation errors, invalid webhook URL, amount outside bounds, inactive wallet, etc.
• 401 / 403 — Invalid or expired token; wrong scope; IP allowlist; ineligible merchant. See Errors overview for shared auth errors.

HTTP status codes (API reference)