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

> Pay a 320 000 DZD supplier invoice from a Broco balance.

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

<Steps>
  <Step title="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"
    }
    ```
  </Step>

  <Step title="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"
    }
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next step

<Card title="Authorization & payment lifecycle" href="/supplier-payments/authorization-and-lifecycle" horizontal>
  Approval rights, statuses, and what to do after a timeout.
</Card>


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