> ## 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.
# Payments: Send and Track ACH Transfers in Cleo Pay
> Understand Cleo Pay payment statuses, clearing speeds, scheduling, partial payments, and how payments relate to payables and contacts.
Payments in Cleo Pay execute as ACH (Automated Clearing House) transfers — the standard electronic funds transfer network used for US bank-to-bank payments. When you create a payment, Cleo Pay initiates a debit from your verified bank account and a credit to the recipient's account. You can send a payment against a specific payable (invoice) or directly to a contact without referencing an invoice.
## Two payment modes
Every payment must reference **exactly one** of the following — but not both:
| Mode | Required field | Use case |
| -------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
| **Pay a payable** | `payableId` | Apply the payment to an approved invoice. Tracks progress against the payable's balance. |
| **Pay a contact directly** | `contactId` | Send funds to a vendor without an associated invoice. |
You cannot specify both `payableId` and `contactId` in the same request. Choose the mode that matches your workflow.
## Payment status lifecycle
| Status | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending` | The payment has been created and is being prepared for submission. |
| `scheduled` | The payment is confirmed and queued for the next ACH processing window. |
| `processing` | The ACH transfer has been submitted to the network. Funds are in transit. |
| `held` | The payment is waiting because the contact does not have a bank account on file. It will proceed automatically once the contact's bank account is added. |
| `completed` | The funds have settled successfully. |
| `failed` | The transfer failed (e.g. insufficient funds, invalid account, or bank rejection). |
| `cancelled` | The payment was cancelled before processing. |
| `refunded` | The payment was processed but the funds have been returned. |
The standard happy path is: `pending` → `scheduled` → `processing` → **`completed`**
If a contact doesn't have a bank account on file when you send a payment, the payment enters `held` status rather than failing immediately. As soon as the contact's bank account is added, the payment proceeds automatically.
## Clearing speeds
The `clearing` field controls how quickly the ACH transfer is processed.
| Value | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `STANDARD` | Standard ACH timing. Funds typically settle within 1–3 business days. Available to all accounts. |
| `NEXT_AVAILABLE` | Expedited processing using the next available ACH window. **Requires a feature flag** to be enabled on your account — contact Cleo Pay to enable this. |
## Scheduling payments
By default, payments are processed as soon as possible. To send a payment on a future date, include the `scheduledAt` field:
* **Format:** `YYYY-MM-DD`
* **Minimum value:** Tomorrow's date (same-day scheduling is not supported)
* **Execution time:** `9:00 AM New York time` on the scheduled date
* **Constraint:** Must fall within a valid business window
```json theme={null}
{
"contactId": "con_01hq9r2m7tuvwxyz",
"amountCents": 100000,
"bankAccountId": "ba_01hq2k5r8e4vabc123",
"clearing": "STANDARD",
"scheduledAt": "2025-04-01"
}
```
Scheduling payments for a specific date is useful for aligning disbursements with your payroll cycle, invoice due dates, or cash flow planning.
## Partial payments
When paying a payable (`payableId`), the `amountCents` field is optional:
* **If omitted:** Cleo Pay defaults to the payable's full `remainingAmountCents`, paying the invoice in full.
* **If specified:** Only that amount is paid, and the payable's `remainingAmountCents` is reduced accordingly. You can send additional payments later until the balance reaches zero.
When paying a contact directly (`contactId`), `amountCents` is required.
## Large payment splitting
For very large payment amounts, Cleo Pay may automatically split the transfer into multiple `Payment` objects whose amounts sum to your requested total. This is handled transparently — your single API request may result in an array of payments in the response.
Always iterate over the `payments` array in the response rather than assuming a single payment object.
## Example: pay a payable
```bash theme={null}
curl --request POST \
--url https://api.cleo-pay.com/v1/payments \
--header "Authorization: Bearer $CLEO_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"payableId": "pbl_01hrx3t7k2abcdef",
"amountCents": 175000,
"bankAccountId": "ba_01hq2k5r8e4vabc123",
"clearing": "STANDARD"
}'
```
## Example: pay a contact directly
```bash theme={null}
curl --request POST \
--url https://api.cleo-pay.com/v1/payments \
--header "Authorization: Bearer $CLEO_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"contactId": "con_01hq9r2m7tuvwxyz",
"amountCents": 50000,
"bankAccountId": "ba_01hq2k5r8e4vabc123",
"clearing": "STANDARD",
"scheduledAt": "2025-04-15"
}'
```
## CreatePaymentResponse
The response always includes a `payableId` (if applicable) and a `payments` array. Even when a single payment is created, the result is wrapped in this array.
```json theme={null}
{
"payableId": "pbl_01hrx3t7k2abcdef",
"payments": [
{
"id": "pay_01hrx5t9k2mnopqr",
"status": "scheduled",
"amountCents": 100000,
"contactId": "con_01hq9r2m7tuvwxyz",
"payableId": "pbl_01hrx3t7k2abcdef",
"bankAccountId": "ba_01hq2k5r8e4vabc123",
"scheduledAt": "2025-03-18T14:00:00Z",
"processedAt": null,
"failureReason": null,
"createdAt": "2025-03-17T11:05:00Z",
"updatedAt": "2025-03-17T11:05:00Z"
},
{
"id": "pay_01hrx5t9k2mnopqs",
"status": "scheduled",
"amountCents": 75000,
"contactId": "con_01hq9r2m7tuvwxyz",
"payableId": "pbl_01hrx3t7k2abcdef",
"bankAccountId": "ba_01hq2k5r8e4vabc123",
"scheduledAt": "2025-03-18T14:00:00Z",
"processedAt": null,
"failureReason": null,
"createdAt": "2025-03-17T11:05:00Z",
"updatedAt": "2025-03-17T11:05:00Z"
}
]
}
```
In this example, a $1,750.00 payment was split into two transfers of $1,000.00 and \$750.00, both scheduled for processing.
## Next steps
* [Payables](/concepts/payables) — understand how payment status maps back to invoice tracking.
* [Contacts](/concepts/contacts) — ensure your contact is `paymentReady` before initiating a payment.
* [Bank Accounts](/concepts/bank-accounts) — verify your funding account before sending funds.