Payments: Send and Track ACH Transfers in Cleo Pay

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

{
  "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

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

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.

{
  "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 — understand how payment status maps back to invoice tracking.
Contacts — ensure your contact is paymentReady before initiating a payment.
Bank Accounts — verify your funding account before sending funds.

Get Started

Core Concepts

How-To Guides

Reference

Payments: Send and Track ACH Transfers in Cleo Pay

Two payment modes

Payment status lifecycle

Clearing speeds

Scheduling payments

Partial payments

Large payment splitting

Example: pay a payable

Example: pay a contact directly

CreatePaymentResponse

Next steps

​Two payment modes

​Payment status lifecycle

​Clearing speeds

​Scheduling payments

​Partial payments

​Large payment splitting

​Example: pay a payable

​Example: pay a contact directly

​CreatePaymentResponse

​Next steps

Two payment modes

Payment status lifecycle

Clearing speeds

Scheduling payments

Partial payments

Large payment splitting

Example: pay a payable

Example: pay a contact directly

CreatePaymentResponse

Next steps