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

> Take an 8 400 DZD order from checkout to cash payment validated at a Broco point.

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

<Steps>
  <Step title="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"
    }
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Reconcile">
    Use `order_reference` and `receipt_number` to match the payment with the order and with the merchant's Broco history.
  </Step>
</Steps>

## Next step

<Card title="Cash payment lifecycle" href="/cash-checkout/payment-lifecycle" horizontal>
  Handle unpaid, expired and canceled requests, and edge cases at the cash point.
</Card>


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