# Initiate collection

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

## Headers

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

See [Field reference](https://docs.swarmbyte.com/field-reference.md) for what each header means.

## Body

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

Field meanings: [Field reference](https://docs.swarmbyte.com/field-reference.md) → 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)](https://docs.swarmbyte.com/webhooks.md). 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](https://docs.swarmbyte.com/errors-overview.md) for shared auth errors.

## HTTP status codes (API reference)

| HTTP | When |
| --- | --- |
| **202** | Request accepted. Response includes `transactionId` and current `data.status` (`PENDING`, `SUCCESS`, or `FAILED` depending on the provider). |
| **400** | Validation or business rule failure — e.g. missing `X-Idempotency-Key`, invalid `walletAddress`, amount below 500 UGX or above the per-transaction maximum, inactive wallet, invalid `webhookUrl` (HTTPS required in production), invalid Ugandan MSISDN, unsupported provider prefix, or MSISDN not eligible for collection. |
| **403** | Account not allowed to move money: `Your account has been disabled.`; `Your account is in view-only mode. This action is not allowed.`; `Your account is not verified. Please complete KYC.` |
| **404** | `Wallet with address "…" not found for merchant` |
| **409** | Idempotency wait timeout: `The same Idempotency-Key is still being processed. Retry after a few seconds with the same key, or wait for the in-flight request to finish.` |
| **429** | Rate limit exceeded. |
| **500** | Unexpected server error — `An unexpected error occurred.` Retry or contact support with the `requestId` from the response. |

## Example request

```bash
curl -sS -X POST 'https://core.swarmbyte.com/v1/collect' \
  -H 'Authorization: Bearer YOUR_COLLECTIONS_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{
    "walletAddress": "main",
    "msisdn": "256701234567",
    "amount": 50000,
    "reference": "ORDER-12345",
    "webhookUrl": "https://your-server.example/webhooks/swarmbyte"
  }'
```

## Example response (202)

```json
{
  "status": "success",
  "message": "Collection initiated; awaiting payer confirmation.",
  "data": {
    "transactionId": "COL_d77d719fb8a02101",
    "walletAddress": "main",
    "amount": 50000,
    "fee": 1500,
    "netAmount": 48500,
    "status": "PENDING",
    "provider": "AIRTEL",
    "createdAt": "2026-04-28T10:30:00.000Z"
  }
}
```

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