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

# Link and Verify a Bank Account in Cleo Pay

> Add a business bank account to Cleo Pay via the API using manual entry, then verify it with two micro-deposits before sending payments.

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.

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

***

## Link and verify a bank account

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

    ```bash title="Add a bank account" theme={null}
    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:

    ```json title="Bank account created" theme={null}
    {
      "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.
  </Step>

  <Step title="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.05`and`\$0.07\`). You'll need the exact amounts for the next step.
  </Step>

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

    <Warning>
      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.
    </Warning>

    ```bash title="Verify micro-deposits" theme={null}
    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`:

    ```json title="Bank account verified" theme={null}
    {
      "id": "ba_01hwxyz456",
      "holderName": "Acme Corp",
      "name": "Main Operating Account",
      "accountNumberLast4": "9012",
      "type": "checking",
      "status": "verified",
      "isDefault": false,
      "createdAt": "2024-06-01T10:00:00Z"
    }
    ```
  </Step>

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

***

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

```bash title="Remove a bank account" theme={null}
curl --request DELETE \
  --url https://api.cleo-pay.com/v1/bank-accounts/ba_01hwxyz456 \
  --header 'Authorization: Bearer <token>'
```

<Warning>
  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.
</Warning>