> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cleo Pay balance

> Read the Cleo Pay balance and its transactions, add money from the linked bank, and withdraw to the linked bank or a verified bank account.

A business on the Cleo Pay rail has a balance it can pay vendors from. The balance endpoints read it and move money in and out of it.

| Call | Scope | Does |
| - | - | - |
| [`GET /v1/balance`](/api-reference/balance/get) | `balance:read` | Reads the balance, same-day ACH settings and the linked bank. |
| [`GET /v1/balance/transactions`](/api-reference/balance/transactions) | `balance:read` | Lists balance transactions, newest first. |
| [`POST /v1/balance/deposits`](/api-reference/balance/deposits) | `balance:transfer` | Pulls money from the linked bank into the balance. Not available through the API yet. |
| [`POST /v1/balance/withdrawals`](/api-reference/balance/withdrawals) | `balance:transfer` | Sends money from the balance to a bank. |

The scopes are checked on the key itself. A `payments:initiate`, `payments:read` or `payables:read` key cannot read or move the balance, and a balance-only key cannot send, cancel, retry or read payments.

## Reading the balance

| Field | Meaning |
| - | - |
| `availableCents` | What the business can spend or withdraw now. |
| `cashCents` | Everything in the account, including money set aside for payments on their way. |
| `reservedCents` | The part of `cashCents` promised to payments on their way to vendors. |
| `pendingInboundCents` | Deposits and payments on their way in. |
| `pendingInboundPassThroughCents` | The part of `pendingInboundCents` passing straight through to a vendor. It never becomes available. |
| `pendingOutboundCents` | Money on its way out. |
| `canSendPayments` | The balance can fund payments now. |
| `isReady` | The account has its own account and routing numbers, so it can receive money. |
| `sameDayAch` | `inbound` and `outbound` say whether deposits and payouts run same-day ACH. Amounts above `maxAmountCents` run standard ACH. |
| `linkedBank` | `bankName` and `last4` of the bank linked to the balance, or `null`. |
| `dashboardUrl` | The balance page in the Cleo web app, where banks are linked. |

Full account and routing numbers are never returned.

## Adding money

<Note>
  **Not available through the API yet.** `POST /v1/balance/deposits` answers `403 feature_unavailable` until Cleo turns partner bank funding on. Your user can add money in the Cleo web app.
</Note>

When it is on, a deposit pulls $1 to $50,000 from the linked bank. It needs an `Idempotency-Key` and `achAuthorizationAccepted: true`, sent only after your user accepted the ACH debit authorization. Cleo records your API key and the request's IP address with it.

## Withdrawing

```bash theme={null}
curl -X POST https://api.stg.cleo-pay.com/v1/balance/withdrawals \
  --header "Authorization: Bearer $CLEO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e" \
  --data '{ "amountCents": 250000, "destination": "linked_bank" }'
```

`destination` is `"linked_bank"` or the id of a verified bank account from `GET /v1/bank-accounts` that has full account and routing numbers on file. You cannot send raw account numbers. New destinations are added in the Cleo web app. A withdrawal can be up to \$50,000 and runs standard ACH.

## Same-day ACH

Cleo decides whether a transfer runs same-day ACH. You cannot ask for it. Transfer responses report the `speed` Cleo chose (`same_day` or `standard`) and the expected date.

## Refusals

| Code | When |
| - | - |
| `feature_unavailable` | The business has no Cleo Pay balance, or the feature is not on. |
| `setup_required` | The business has no Cleo Pay account yet, or a deposit needs a linked bank. `details.actionUrl` links to the web. |
| `insufficient_balance` | The balance does not cover the amount. `details` has `availableCents` and `reservedCents`. |
| `payments_locked`, `setup_incomplete` | The business cannot move money yet. See [Errors](/reference/errors). |
| `validation_error` | For example, a destination that is not verified or has no full numbers on file. |
| `payment_unconfirmed` | The transfer may have started. Look for it in `GET /v1/balance/transactions` before you send it again with a new key. |

Deposits and withdrawals are money writes. A failure that may have moved money is final for its key. See [Idempotency](/reference/idempotency).


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