Supplier payments

A supplier payment transfers funds from a business’s Broco balance to an authorized supplier after approval by an authorized user. Guide: Supplier payments.

Operation	Method and path
Retrieve a beneficiary	`GET /v1/beneficiaries/{id}`
Create a supplier payment	`POST /v1/supplier_payments`
Retrieve a supplier payment	`GET /v1/supplier_payments/{id}`
List supplier payments	`GET /v1/supplier_payments`
Cancel a supplier payment	`POST /v1/supplier_payments/{id}/cancel`

The beneficiary object

Field	Type	Description
`id`	string	Identifier, such as `ben_4Qs8Tn2v`
`object`	string	Always `beneficiary`
`account_name`	string	Verified name of the supplier’s Broco account
`status`	string	`authorized` or `revoked`
`created_at`	string	When the business added the beneficiary

Beneficiaries are managed by the business in Broco.

Request

curl "https://api.broco.example/v1/beneficiaries/ben_4Qs8Tn2v?payer_connection=conn_biz_2Pk7Lm" \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"

The supplier payment object

Field	Type	Description
`id`	string	Identifier, such as `spay_6Jw4Pz1c`
`object`	string	Always `supplier_payment`
`status`	string	`awaiting_approval`, `succeeded`, `rejected`, `declined`, `canceled` or `expired`
`decline_reason`	string or null	`insufficient_balance` or `beneficiary_unavailable` when `declined`
`payer_connection`	string	Connection of the paying business
`beneficiary`	string	Authorized beneficiary
`amount`	integer	Amount in minor units of `currency`
`currency`	string	Currency code: `DZD`, `MAD`, `TND` or `XOF`
`invoice_reference`	string	Invoice being paid
`description`	string or null	Text shown to the approver and the supplier
`approval_url`	string or null	Broco page where an authorized user approves. `null` once final.
`fee_amount`	integer or null	Fees, once `succeeded`
`expires_at`	string	Approval deadline
`approved_at`	string or null	Time of approval
`succeeded_at`	string or null	Time of the debit and credit
`created_at`	string	Creation time

Create a supplier payment

POST /v1/supplier_payments

Parameter	Type	Required	Description
`payer_connection`	string	Yes	Connection of the paying business
`beneficiary`	string	Yes	Authorized beneficiary
`amount`	integer	Yes	Amount in minor units. 320 000 DZD is `32000000`.
`currency`	string	Yes	Currency code: `DZD`, `MAD`, `TND` or `XOF`. The balances debited and credited use this currency.
`invoice_reference`	string	Yes	Invoice being paid
`description`	string	No	Text shown to the approver and the supplier

Request

curl -X POST https://api.broco.example/v1/supplier_payments \
  -H "Authorization: Bearer $BROCO_SECRET_KEY" \
  -H "Idempotency-Key: INV-2026-0147-payment-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_connection": "conn_biz_2Pk7Lm",
    "beneficiary": "ben_4Qs8Tn2v",
    "amount": 32000000,
    "currency": "DZD",
    "invoice_reference": "INV-2026-0147",
    "description": "Invoice INV-2026-0147"
  }'

Response

{
  "id": "spay_6Jw4Pz1c",
  "object": "supplier_payment",
  "status": "awaiting_approval",
  "decline_reason": null,
  "payer_connection": "conn_biz_2Pk7Lm",
  "beneficiary": "ben_4Qs8Tn2v",
  "amount": 32000000,
  "currency": "DZD",
  "invoice_reference": "INV-2026-0147",
  "description": "Invoice INV-2026-0147",
  "approval_url": "https://app.broco.example/approvals/spay_6Jw4Pz1c",
  "fee_amount": null,
  "expires_at": "2026-10-22T09:00:00Z",
  "approved_at": null,
  "succeeded_at": null,
  "created_at": "2026-10-15T09:00:00Z"
}

Retrieve a supplier payment

GET /v1/supplier_payments/{id}

Response

{
  "id": "spay_6Jw4Pz1c",
  "object": "supplier_payment",
  "status": "succeeded",
  "decline_reason": null,
  "payer_connection": "conn_biz_2Pk7Lm",
  "beneficiary": "ben_4Qs8Tn2v",
  "amount": 32000000,
  "currency": "DZD",
  "invoice_reference": "INV-2026-0147",
  "description": "Invoice INV-2026-0147",
  "approval_url": null,
  "fee_amount": 0,
  "expires_at": "2026-10-22T09:00:00Z",
  "approved_at": "2026-10-15T09:31:02Z",
  "succeeded_at": "2026-10-15T09:31:05Z",
  "created_at": "2026-10-15T09:00:00Z"
}

Fee values are examples.

List supplier payments

GET /v1/supplier_payments

Query parameter	Type	Required	Description
`invoice_reference`	string	No	Return payments for this invoice
`status`	string	No	Filter by status

Use it after a timeout to check whether a payment exists for an invoice.

Request

curl "https://api.broco.example/v1/supplier_payments?invoice_reference=INV-2026-0147" \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"

Cancel a supplier payment

POST /v1/supplier_payments/{id}/cancel Cancels a payment in awaiting_approval. Fails with invalid_status if the payment is final.

Events

Event	Sent when
`supplier_payment.succeeded`	The business is debited and the supplier credited

Errors

invalid_request, invalid_amount, unsupported_currency, currency_mismatch, connection_not_authorized, beneficiary_not_authorized, idempotency_key_reused, invalid_status. See Errors & retries.

Get started

Product

Developer

API Reference

The beneficiary object

The supplier payment object

Create a supplier payment

Retrieve a supplier payment

List supplier payments

Cancel a supplier payment

Events

Errors

​The beneficiary object

​The supplier payment object

​Create a supplier payment

​Retrieve a supplier payment

​List supplier payments

​Cancel a supplier payment

​Events

​Errors

The beneficiary object

The supplier payment object

Create a supplier payment

Retrieve a supplier payment

List supplier payments

Cancel a supplier payment

Events

Errors