Link and Verify a Bank Account in Cleo Pay

Before you can send ACH payments, you need at least one verified bank account linked to your Cleo Pay account. The API uses a micro-deposit verification flow: you submit your account details, Cleo Pay sends two small test deposits to the account, and you confirm those amounts to complete verification.

accountNumber and routingNumber are write-only fields. After submission, the API never returns the full account number or routing number — only the last 4 digits of the account number are included in responses. Store your account credentials securely before submitting them.

Link and verify a bank account

Submit your bank account details

Call POST /v1/bank-accounts with your account information. All five fields are required.

Field	Type	Description
`holderName`	string	Legal name of the account holder (business or individual).
`name`	string	A friendly label for this account (e.g., “Main Operating Account”).
`accountNumber`	string	Full account number. Write-only — not returned after submission.
`routingNumber`	string	9-digit ABA routing number. Write-only — not returned after submission.
`type`	string	Account type: `checking` or `savings`.

Add a bank account

curl --request POST \
  --url https://api.cleo-pay.com/v1/bank-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "holderName": "Acme Corp",
    "name": "Main Operating Account",
    "accountNumber": "123456789012",
    "routingNumber": "021000021",
    "type": "checking"
  }'

The response shows the new bank account with a status of pending_verification. Note that accountNumber and routingNumber are write-only and are not returned:

Bank account created

{
  "id": "ba_01hwxyz456",
  "holderName": "Acme Corp",
  "name": "Main Operating Account",
  "accountNumberLast4": "9012",
  "type": "checking",
  "status": "pending_verification",
  "isDefault": false,
  "createdAt": "2024-06-01T10:00:00Z"
}

Save the id — you’ll need it for the verification step and for all payment requests.

Wait for micro-deposits

After the account is created, Cleo Pay initiates two small ACH deposits to your bank account. These typically appear within 1–2 business days.Check your bank statement for two separate deposits from Cleo Pay, each less than

1.00 (for example, `

0.05and$0.07`). You’ll need the exact amounts for the next step.

Verify the micro-deposit amounts

Once the deposits appear, call POST /v1/bank-accounts/{id}/verify-micro-deposits with the two amounts as decimal strings in dollars.

You have a maximum of 3 verification attempts. If all three attempts fail (amounts don’t match), the bank account status permanently becomes unverified and the account cannot be used. You will need to add a new bank account.

Verify micro-deposits

curl --request POST \
  --url https://api.cleo-pay.com/v1/bank-accounts/ba_01hwxyz456/verify-micro-deposits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount1": "0.05",
    "amount2": "0.07"
  }'

On success, the account status updates to verified:

Bank account verified

{
  "id": "ba_01hwxyz456",
  "holderName": "Acme Corp",
  "name": "Main Operating Account",
  "accountNumberLast4": "9012",
  "type": "checking",
  "status": "verified",
  "isDefault": false,
  "createdAt": "2024-06-01T10:00:00Z"
}

Your account is ready to fund payments

With status: verified, you can now supply this account’s id as the bankAccountId field in any POST /v1/payments request.

Bank account statuses

Status	Meaning
`pending_verification`	Account has been added; waiting for micro-deposit confirmation.
`verified`	Micro-deposits confirmed; account is ready to use.
`unverified`	All 3 verification attempts were exhausted with incorrect amounts.
`removed`	Account has been deleted via `DELETE /v1/bank-accounts/{id}`.

Remove a bank account

To remove a bank account, send a DELETE request. A successful deletion returns 204 No Content and sets the account’s status to removed.

Remove a bank account

curl --request DELETE \
  --url https://api.cleo-pay.com/v1/bank-accounts/ba_01hwxyz456 \
  --header 'Authorization: Bearer <token>'

Removing a bank account that is currently the default or is linked to pending payments may affect in-flight transactions. Confirm no payments are in pending or scheduled status against the account before deleting it.

Get Started

Core Concepts

How-To Guides

Reference

Link and Verify a Bank Account in Cleo Pay