> ## 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.

# Supplier payments quickstart

> Prepare a supplier payment for an invoice, have an authorized user approve it in Broco and mark the invoice as paid.

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`.

**1. Find the beneficiary**

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

```bash Request theme={null}
curl "https://api.broco.example/v1/beneficiaries/ben_4Qs8Tn2v?payer_connection=conn_biz_2Pk7Lm" \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"
```

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

**2. Prepare the payment**

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

```bash Request theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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"
}
```

**3. 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.

**4. 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.

```json Event (excerpt) theme={null}
{
  "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

> [card] [Authorization & payment lifecycle](https://docs.broco.app/supplier-payments/authorization-and-lifecycle.md)
>
> Approval rights, statuses, and what to do after a timeout.


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