Cash checkout quickstart

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.

Create the cash payment

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

Request

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"
  }'

Response

{
  "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"
}

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.

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.

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.

Event (excerpt)

{
  "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.

Reconcile

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

Next step

Cash payment lifecycle

Handle unpaid, expired and canceled requests, and edge cases at the cash point.

Get started

Product

Developer

API Reference

Next step

Cash payment lifecycle

​Next step

Cash payment lifecycle

Next step