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

> The statuses of a cash payment and how cash points handle edge cases.

A cash payment starts as `awaiting_payment` and ends in one final status. Only `succeeded` means the cash was validated and the merchant credited.

```mermaid theme={null}
flowchart TD
  A[awaiting_payment] --> B[succeeded]
  A --> C[expired]
  A --> D[canceled]
  classDef money fill:#158FAB,stroke:#0E6F86,color:#FFFFFF
  class B money
```

## Statuses

| Status | Meaning | What your platform does |
| - | - | - |
| `awaiting_payment` | The customer has not paid yet | Keep the order on hold |
| `succeeded` | The agent validated the cash. The merchant is credited. | Mark the order as paid and ship it |
| `expired` | The deadline passed without a validated payment | Cancel or reissue the order |
| `canceled` | Your platform canceled the request | Do not mark the order as paid |

`succeeded`, `expired` and `canceled` are final.

## At the cash point

The agent validates a payment only when all checks pass.

| Check | If it fails |
| - | - |
| The reference or QR code matches a request | The agent does not accept cash |
| The request is `awaiting_payment` | The agent does not accept cash for an expired, canceled or already paid request |
| The merchant and order shown match the customer's order | The agent stops and the customer contacts the merchant |
| The cash counted equals `amount` | The agent does not validate the payment |

Opening or scanning the QR code only retrieves the request. It is not a payment.

## Expired requests

An expired request is never shown as paid. If the customer still wants the order, your platform creates a new cash payment with a new `Idempotency-Key`, such as `ORD-20731-cash-2`, and shares the new reference.

If cash was handed over on a request that was not payable, Broco treats it as an anomaly and resolves it with the parties. It does not become a payment automatically.

## Duplicate validation

A cash payment is validated once. Any further validation attempt is refused. If Broco sends `cash_payment.succeeded` again, your server ignores the duplicate event `id`.

## Receipt and reconciliation

| Field | Use |
| - | - |
| `receipt_number` | Printed on the customer's receipt |
| `payment_reference` | Shown to the customer and the agent |
| `order_reference` | Your order identifier |
| `cash_point` | Where the cash was paid |
| `paid_at` | When the agent validated the cash |

## Next steps

<CardGroup cols={2}>
  <Card title="Cash checkout API" href="/api-reference/cash-payments">
    The cash payment object and its operations.
  </Card>

  <Card title="Events & webhooks" href="/developer/events-and-webhooks">
    Receive `cash_payment.succeeded` and `cash_payment.expired`.
  </Card>
</CardGroup>


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