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

> Retrieve beneficiaries and create, retrieve, list and cancel 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](/supplier-payments/overview).

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

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

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

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

```bash Request theme={null}
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](/developer/errors-and-retries).


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