Supplier payments quickstart

This quickstart pays invoice INV-2026-0147 for 320 000 DZD. The business is connected as conn_biz_2Pk7Lm. The supplier is the authorized beneficiary ben_4Qs8Tn2v.

Find the beneficiary

Retrieve the beneficiary and show its verified name before you prepare the payment.

Request

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

Response

{
  "id": "ben_4Qs8Tn2v",
  "object": "beneficiary",
  "account_name": "Supplier account name",
  "status": "authorized",
  "created_at": "2026-09-02T08:15:00Z"
}

Prepare the payment

Use a key tied to the invoice, so a retry never creates a second payment.

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",
  "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",
  "expires_at": "2026-10-22T09:00:00Z",
  "created_at": "2026-10-15T09:00:00Z"
}

An authorized user approves

The approver opens the payment in Broco, from approval_url or the approval list. They check the supplier name, the amount and the invoice reference, then approve.

Receive the result

Broco debits the business, credits the supplier and sends supplier_payment.succeeded. Check that data.id is the supplier payment you created, then check data.payer_connection, data.invoice_reference, data.amount and data.currency. Then mark the invoice as paid.

Event (excerpt)

{
  "id": "evt_T2q9Lc5h",
  "type": "supplier_payment.succeeded",
  "created_at": "2026-10-15T09:31:07Z",
  "data": {
    "id": "spay_6Jw4Pz1c",
    "object": "supplier_payment",
    "status": "succeeded",
    "payer_connection": "conn_biz_2Pk7Lm",
    "beneficiary": "ben_4Qs8Tn2v",
    "amount": 32000000,
    "currency": "DZD",
    "invoice_reference": "INV-2026-0147",
    "fee_amount": 0,
    "approved_at": "2026-10-15T09:31:02Z",
    "succeeded_at": "2026-10-15T09:31:05Z"
  }
}

Fee values are examples.

Next step

Authorization & payment lifecycle

Approval rights, statuses, and what to do after a timeout.

Get started

Product

Developer

API Reference

Next step

Authorization & payment lifecycle

​Next step

Authorization & payment lifecycle

Next step