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

<Steps>
  <Step title="Retry with the same key">
    Send the same request with the same `Idempotency-Key`. Broco returns the existing payment if it was created.
  </Step>

  <Step title="Or look up the invoice">
    List payments for the invoice with `GET /v1/supplier_payments?invoice_reference=INV-2026-0147`.
  </Step>

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

## Next steps

<CardGroup cols={2}>
  <Card title="Supplier payments API" href="/api-reference/supplier-payments">
    The supplier payment object and its operations.
  </Card>

  <Card title="Errors & retries" href="/developer/errors-and-retries">
    Error codes and retry rules.
  </Card>
</CardGroup>


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