# Collection transaction status

Resolve a collection by `transactionId` returned from `POST /v1/collect`, or by provider reference where applicable. Requires **collections** scope.

## Headers

```http
Authorization: Bearer <collections_access_token>
```

## Responses

- **200** — `data.type` must be `COLLECTION` for this route.
- **403** — Token scope is disbursements-only, or row exists but is not a collection.
- **404** — Unknown id for this merchant.

## HTTP status codes (API reference)

Shared auth errors (401, wrong-scope 403, IP 403, 429): [Errors overview](https://docs.swarmbyte.com/errors-overview.md).

| HTTP | When |
| --- | --- |
| **200** | `status: "success"` and `data` with full transaction fields (`type`, `status`, amounts, `failureReason`, timestamps). `data.type` must be `COLLECTION` for this route. |
| **403** | Row exists but is not a collection: `This transaction is not a collection; use GET /v1/disburse/transactions/:transactionId with a disbursements-scoped token.` |
| **404** | `Transaction not found` |
| **401** / **403** / **429** | See [Errors overview](https://docs.swarmbyte.com/errors-overview.md) for auth, scope, IP, and rate-limit errors. |

## Status values

Transaction `status` enum in the API includes `PENDING`, `SUCCESS`, `FAILED`, `AMBIGUOUS`.

## Example request

```bash
curl -sS 'https://core.swarmbyte.com/v1/collect/transactions/COL_d77d719fb8a02101' \
  -H 'Authorization: Bearer YOUR_COLLECTIONS_ACCESS_TOKEN'
```

## Example response (200)

```json
{
  "status": "success",
  "data": {
    "transactionId": "COL_d77d719fb8a02101",
    "walletAddress": "main",
    "providerRef": "PROVIDER_REF_OR_NULL",
    "amount": 50000,
    "fee": 1500,
    "netAmount": 48500,
    "type": "COLLECTION",
    "status": "SUCCESS",
    "provider": "AIRTEL",
    "msisdn": "256701234567",
    "reference": "ORDER-12345",
    "failureReason": null,
    "createdAt": "2026-04-28T10:30:00.000Z",
    "updatedAt": "2026-04-28T10:31:05.000Z"
  }
}
```

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