Cleo Pay balance

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`	`balance:read`	Reads the balance, same-day ACH settings and the linked bank.
`GET /v1/balance/transactions`	`balance:read`	Lists balance transactions, newest first.
`POST /v1/balance/deposits`	`balance:transfer`	Pulls money from the linked bank into the balance. Not available through the API yet.
`POST /v1/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

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.

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

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

Get Started

Core Concepts

How-To Guides

Reference

Reading the balance

Adding money

Withdrawing

Same-day ACH

Refusals

​Reading the balance

​Adding money

​Withdrawing

​Same-day ACH

​Refusals

Reading the balance

Adding money

Withdrawing

Same-day ACH

Refusals