Cash payments

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.

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.

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

Request

curl https://api.broco.example/v1/cash_payments/cpay_5Rt8Wn3k \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"

Response

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

Request

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.

Get started

Product

Developer

API Reference

The cash payment object

Create a cash payment

Retrieve a cash payment

Cancel a cash payment

Events

Errors

​The cash payment object

​Create a cash payment

​Retrieve a cash payment

​Cancel a cash payment

​Events

​Errors

The cash payment object

Create a cash payment

Retrieve a cash payment

Cancel a cash payment

Events

Errors