> ## 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.

# Cash payments

> Create, retrieve and cancel cash payments paid at Broco cash points.

A cash payment lets a customer pay an online order in cash at a Broco cash point. The merchant is credited when the cash agent validates the cash. Guide: [Cash checkout](/cash-checkout/overview).

| Operation | Method and path |
| - | - |
| Create a cash payment | `POST /v1/cash_payments` |
| Retrieve a cash payment | `GET /v1/cash_payments/{id}` |
| Cancel a cash payment | `POST /v1/cash_payments/{id}/cancel` |

## The cash payment object

| Field | Type | Description |
| - | - | - |
| `id` | string | Identifier, such as `cpay_5Rt8Wn3k` |
| `object` | string | Always `cash_payment` |
| `status` | string | `awaiting_payment`, `succeeded`, `expired` or `canceled` |
| `amount` | integer | Exact amount to pay, in minor units |
| `currency` | string | Currency code: `DZD`, `MAD`, `TND` or `XOF` |
| `order_reference` | string | Your order identifier |
| `merchant_connection` | string | Connection of the merchant receiving the funds |
| `payment_reference` | string | Reference the customer gives at the cash point |
| `qr_code_url` | string | Image of the QR code to show the customer |
| `instructions_url` | string | Broco page with the payment instructions and cash points |
| `expires_at` | string | Payment deadline |
| `cash_point` | string or null | Cash point where the cash was validated |
| `receipt_number` | string or null | Number printed on the customer's receipt |
| `fee_amount` | integer or null | Fees, once `succeeded` |
| `net_amount` | integer or null | Amount credited to the merchant, once `succeeded` |
| `paid_at` | string or null | Time the agent validated the cash |
| `created_at` | string | Creation time |

## Create a cash payment

`POST /v1/cash_payments`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `amount` | integer | Yes | Amount in minor units. 8 400 DZD is `840000`. |
| `currency` | string | Yes | Currency code: `DZD`, `MAD`, `TND` or `XOF`. The merchant balance credited uses this currency. |
| `order_reference` | string | Yes | Your order identifier |
| `merchant_connection` | string | Yes | Connection of the merchant |
| `expires_at` | string | No | Payment deadline. Broco applies a default when omitted. |

```bash Request theme={null}
curl -X POST https://api.broco.example/v1/cash_payments \
  -H "Authorization: Bearer $BROCO_SECRET_KEY" \
  -H "Idempotency-Key: ORD-20731-cash-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 840000,
    "currency": "DZD",
    "order_reference": "ORD-20731",
    "merchant_connection": "conn_mrc_4f7Kp2",
    "expires_at": "2026-10-14T21:00:00Z"
  }'
```

```json Response theme={null}
{
  "id": "cpay_5Rt8Wn3k",
  "object": "cash_payment",
  "status": "awaiting_payment",
  "amount": 840000,
  "currency": "DZD",
  "order_reference": "ORD-20731",
  "merchant_connection": "conn_mrc_4f7Kp2",
  "payment_reference": "BR-7Q4M-2K9D",
  "qr_code_url": "https://pay.broco.example/cash/cpay_5Rt8Wn3k/qr.png",
  "instructions_url": "https://pay.broco.example/cash/cpay_5Rt8Wn3k",
  "expires_at": "2026-10-14T21:00:00Z",
  "cash_point": null,
  "receipt_number": null,
  "fee_amount": null,
  "net_amount": null,
  "paid_at": null,
  "created_at": "2026-10-12T09:00:00Z"
}
```

## Retrieve a cash payment

`GET /v1/cash_payments/{id}`

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

```json Response theme={null}
{
  "id": "cpay_5Rt8Wn3k",
  "object": "cash_payment",
  "status": "succeeded",
  "amount": 840000,
  "currency": "DZD",
  "order_reference": "ORD-20731",
  "merchant_connection": "conn_mrc_4f7Kp2",
  "payment_reference": "BR-7Q4M-2K9D",
  "qr_code_url": "https://pay.broco.example/cash/cpay_5Rt8Wn3k/qr.png",
  "instructions_url": "https://pay.broco.example/cash/cpay_5Rt8Wn3k",
  "expires_at": "2026-10-14T21:00:00Z",
  "cash_point": "pt_ALG_0087",
  "receipt_number": "RCP-0087-551204",
  "fee_amount": 0,
  "net_amount": 840000,
  "paid_at": "2026-10-13T16:42:10Z",
  "created_at": "2026-10-12T09:00:00Z"
}
```

Fee values are examples.

## Cancel a cash payment

`POST /v1/cash_payments/{id}/cancel`

Cancels an `awaiting_payment` request, for example when the order is canceled. The reference can no longer be paid. Fails with `invalid_status` if the payment is final.

```bash Request theme={null}
curl -X POST https://api.broco.example/v1/cash_payments/cpay_5Rt8Wn3k/cancel \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"
```

## Events

| Event | Sent when |
| - | - |
| `cash_payment.succeeded` | The agent validated the cash and the merchant is credited |
| `cash_payment.expired` | The deadline passed without a validated payment |

## Errors

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


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