> ## Documentation Index
> Fetch the complete documentation index at: https://docs.broco.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Create and retrieve cash collections, their deposit and their settlement.

A collection follows cash collected on delivery for an order, from the recipient to the carrier, to the cash point, to the wholesaler's balance. Guide: [Marketplace cash reconciliation](/marketplaces/overview).

| Operation | Method and path |
| - | - |
| Create a collection | `POST /v1/collections` |
| Retrieve a collection with its deposit and settlement | `GET /v1/collections/{id}` |

## The collection object

| Field | Type | Description |
| - | - | - |
| `id` | string | Identifier, such as `col_3Fk9pQ2w` |
| `object` | string | Always `collection` |
| `status` | string | `awaiting_collection`, `collected_awaiting_deposit`, `deposit_under_review` or `settled` |
| `amount` | integer | Amount to collect, in minor units |
| `currency` | string | Currency code: `DZD`, `MAD`, `TND` or `XOF` |
| `order_reference` | string | Your order identifier |
| `beneficiary_connection` | string | Connection of the wholesaler receiving the funds |
| `collected_at` | string or null | When the recipient confirmed the handover |
| `deposit` | object or null | Deposit details, from collection onwards |
| `settlement` | object or null | Settlement details, once `settled` |
| `created_at` | string | Creation time |

### `deposit`

| Field | Type | Description |
| - | - | - |
| `point` | string | Assigned Broco cash point |
| `due_at` | string | 24 hours after `collected_at` |
| `overdue` | boolean | `true` while the deadline has passed and no deposit is validated |
| `deposited_late` | boolean | `true` if the deposit was validated after `due_at` |
| `amount_expected` | integer | Amount of the collection |
| `amount_received` | integer or null | Amount confirmed by the cash agent at final validation |
| `validated_at` | string or null | Time of final validation |

### `settlement`

| Field | Type | Description |
| - | - | - |
| `gross_amount` | integer | Amount collected and deposited |
| `fee_amount` | integer | Fees |
| `net_amount` | integer | Amount credited to the wholesaler |
| `currency` | string | Currency code: `DZD`, `MAD`, `TND` or `XOF` |
| `settled_at` | string | Time of the credit, equal to `deposit.validated_at` |

## Create a collection

`POST /v1/collections`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `amount` | integer | Yes | Amount to collect in minor units. 50 000 DZD is `5000000`. |
| `currency` | string | Yes | Currency code: `DZD`, `MAD`, `TND` or `XOF`. The wholesaler balance credited uses this currency. |
| `order_reference` | string | Yes | Your order identifier |
| `beneficiary_connection` | string | Yes | Connection of the wholesaler |

```bash Request theme={null}
curl -X POST https://api.broco.example/v1/collections \
  -H "Authorization: Bearer $BROCO_SECRET_KEY" \
  -H "Idempotency-Key: ORD-58213-collection" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000000,
    "currency": "DZD",
    "order_reference": "ORD-58213",
    "beneficiary_connection": "conn_ben_7Lw2cR"
  }'
```

```json Response theme={null}
{
  "id": "col_3Fk9pQ2w",
  "object": "collection",
  "status": "awaiting_collection",
  "amount": 5000000,
  "currency": "DZD",
  "order_reference": "ORD-58213",
  "beneficiary_connection": "conn_ben_7Lw2cR",
  "collected_at": null,
  "deposit": null,
  "settlement": null,
  "created_at": "2026-10-12T08:30:00Z"
}
```

## Retrieve a collection

`GET /v1/collections/{id}`

```bash Request theme={null}
curl https://api.broco.example/v1/collections/col_3Fk9pQ2w \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"
```

```json Response theme={null}
{
  "id": "col_3Fk9pQ2w",
  "object": "collection",
  "status": "settled",
  "amount": 5000000,
  "currency": "DZD",
  "order_reference": "ORD-58213",
  "beneficiary_connection": "conn_ben_7Lw2cR",
  "collected_at": "2026-10-12T10:24:00Z",
  "deposit": {
    "point": "pt_ALG_0142",
    "due_at": "2026-10-13T10:24:00Z",
    "overdue": false,
    "deposited_late": false,
    "amount_expected": 5000000,
    "amount_received": 5000000,
    "validated_at": "2026-10-12T17:05:12Z"
  },
  "settlement": {
    "gross_amount": 5000000,
    "fee_amount": 50000,
    "net_amount": 4950000,
    "currency": "DZD",
    "settled_at": "2026-10-12T17:05:12Z"
  },
  "created_at": "2026-10-12T08:30:00Z"
}
```

Fee values are examples.

## Events

| Event | Sent when |
| - | - |
| `collection.collected` | The recipient confirmed the cash handover |
| `settlement.completed` | The deposit was validated and the wholesaler credited |

## Errors

`invalid_request`, `invalid_amount`, `unsupported_currency`, `currency_mismatch`, `connection_not_authorized`, `idempotency_key_reused`, `resource_not_found`. See [Errors & retries](/developer/errors-and-retries).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.