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

# Authorization & payment lifecycle

> Who can prepare and approve supplier payments, the statuses, and safe retries.

## Who can do what

| Actor | Can prepare a payment | Can approve a payment |
| - | - | - |
| Connected software | Yes, for authorized beneficiaries | No |
| User with approval rights in the business | Yes | Yes |
| Other users of the business | Depends on their Broco role | No |

The business manages approval rights and beneficiaries in Broco. The software never chooses an account outside the authorized beneficiaries.

## Statuses

```mermaid theme={null}
flowchart TD
  A[awaiting_approval] --> B[succeeded]
  A --> C[rejected]
  A --> D[declined]
  A --> E[canceled]
  A --> F[expired]
  classDef money fill:#158FAB,stroke:#0E6F86,color:#FFFFFF
  class B money
```

| Status | Meaning | Money moved |
| - | - | - |
| `awaiting_approval` | Prepared, waiting for an authorized user | No |
| `succeeded` | Approved. Business debited, supplier credited. | Yes |
| `rejected` | The approver rejected the payment | No |
| `declined` | Broco could not execute the payment, see `decline_reason` | No |
| `canceled` | Canceled before approval | No |
| `expired` | Not approved before `expires_at` | No |

All statuses except `awaiting_approval` are final.

| `decline_reason` | Meaning |
| - | - |
| `insufficient_balance` | The business balance did not cover the amount at approval |
| `beneficiary_unavailable` | The supplier's account could not receive funds |

## Wrong beneficiary

The approver sees the verified name of the supplier's account before approving. Reject the payment if the supplier is not the expected one. A succeeded payment is a completed transfer between Broco accounts: contact Broco and the supplier to resolve an error.

## Timeouts and uncertain results

If a creation request times out, the payment may or may not exist. Do not prepare a new payment.

**1. Retry with the same key**

Send the same request with the same `Idempotency-Key`. Broco returns the existing payment if it was created.

**2. Or look up the invoice**

List payments for the invoice with `GET /v1/supplier_payments?invoice_reference=INV-2026-0147`.

**3. Act on the status**

Wait for `awaiting_approval` to resolve, or create a new payment with a new key only after a final status other than `succeeded`.

## Next steps

> [card] [Supplier payments API](https://docs.broco.app/api-reference/supplier-payments.md)
>
> The supplier payment object and its operations.

> [card] [Errors & retries](https://docs.broco.app/developer/errors-and-retries.md)
>
> Error codes and retry rules.


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