> ## 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 checkout quickstart

> Create a cash payment for an online order, show the payment instructions and ship once a Broco cash agent validates the cash.

This quickstart follows order `ORD-20731` for **8 400 DZD**. The customer pays in cash at a Broco cash point. The merchant is connected as `conn_mrc_4f7Kp2`.

**1. Create the cash payment**

When the customer selects **Pay in cash at a Broco point**, your server creates the cash payment.

```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",
  "created_at": "2026-10-12T09:00:00Z"
}
```

**2. Show the payment instructions**

Display the `payment_reference`, the QR code, the amount and `expires_at` on the order confirmation, and send them by email or SMS. Link to `instructions_url` for the list of cash points. Keep the order on hold: it ships only after payment.

**3. The customer pays at a cash point**

The cash agent scans the QR code or enters the reference. Broco shows the agent the merchant, the order reference, the amount and the deadline. The agent counts the cash and validates the amount received. The customer receives a receipt.

**4. Receive the result on your server**

Broco sends `cash_payment.succeeded`. Check that `data.id` is the cash payment you created, then check `data.merchant_connection`, `data.order_reference`, `data.amount` and `data.currency`. Then mark the order as paid and ship it.

```json Event (excerpt) theme={null}
{
  "id": "evt_K8m3Vb6x",
  "type": "cash_payment.succeeded",
  "created_at": "2026-10-13T16:42:12Z",
  "data": {
    "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",
    "cash_point": "pt_ALG_0087",
    "receipt_number": "RCP-0087-551204",
    "fee_amount": 0,
    "net_amount": 840000,
    "paid_at": "2026-10-13T16:42:10Z"
  }
}
```

Fee values are examples.

**5. Reconcile**

Use `order_reference` and `receipt_number` to match the payment with the order and with the merchant's Broco history.

## Next step

> [card] [Cash payment lifecycle](https://docs.broco.app/cash-checkout/payment-lifecycle.md)
>
> Handle unpaid, expired and canceled requests, and edge cases at the cash point.


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