> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Receiving ACH

> Handle incoming ACH credits and debits: controls, statuses, webhooks, and returning entries you don't want.

Incoming ACH entries come from other banks, so there is no endpoint to call. Each entry arrives on one of your account numbers as an [ACH object](https://docs.lead.bank/v2/products/ach/ach-object.md) with `direction` `incoming`. Webhooks tell you when an entry arrives and posts. An incoming credit adds funds to the balance behind the account number. An incoming debit takes funds out, under an authorization your customer gave the originator.

Each incoming entry tells you where it posted. `core_transaction_id` is the ledger entry it created after it reached `posted`.

## Controlling what you accept

Each account number's [ACH controls](https://docs.lead.bank/v2/products/account-number/controls.md#ach) govern what it can receive:

* `incoming.accept_credit` and `incoming.accept_debit`, both `true` by default. When `accept_debit` is `false`, Lead automatically returns incoming debits with return code `R16`.
* `incoming.counterparty_filter`: accept all counterparties (default), an allowlist of company IDs, or reject all.

An account number receives only while it is `active`. See [Account Number Statuses](https://docs.lead.bank/v2/products/account-number/statuses.md).

## Endpoints

You don't call anything to receive an entry, but these endpoints are how you observe and act on incoming activity:

| Endpoint | Description |
| - | - |
| `GET /v2/ach?direction=incoming` | List incoming entries. Also filterable by `account_number_id`, `core_transaction_id`, `status`, and `created_at`. |
| `GET /v2/ach/{ach_id}` | Retrieve a single entry, for example when a webhook delivers its ID. |
| `POST /v2/ach/{ach_id}/return` | Return an incoming entry you don't want. |

## Statuses

Incoming entries have a shorter lifecycle than outgoing. They move from `scheduled` to `posted`, with a manual review step when a validation rule requires it. Incoming entries can't be canceled. This table is an excerpt. [ACH Statuses](https://docs.lead.bank/v2/products/ach/statuses.md) is the canonical reference, including the return chain.

| Status | Description | Webhook |
| - | - | - |
| `scheduled` | Lead accepted the incoming entry; it is waiting to post. | `ach.scheduled` |
| `under_review` | A validation rule triggered manual review by Lead. | `ach.under_review` |
| `rejected` | The entry failed validation or manual review and doesn't post. Terminal. | None for incoming |
| `posted` | The entry posted: a credit was deposited, or a debit was withdrawn. `core_transaction_id` is set. | `ach.posted` |

## Events

The table lists each event and what to do when it arrives.

| Event | What happened | Recommended action |
| - | - | - |
| `ach.scheduled` | An incoming entry arrived and was accepted. | Record it. If it's an unexpected debit, evaluate whether to return it after it posts. |
| `ach.posted` | Funds moved. | Update balances in your system from `core_transaction_id`. For debits, confirm the pull was authorized. |
| `ach.returned` | A return of this entry completed. | Reconcile the reversal of funds using the `core_transaction_id` on the `returns[]` entry. |
| `ach.return_dishonored`, `ach.return_contested` | The originating bank disputed your return, or you contested their dishonor. | Reconcile per the latest `returns[]` entry. |

## Returning entries you don't want

You can return any incoming entry, most commonly an unauthorized or erroneous debit, with `POST /v2/ach/{ach_id}/return` and an appropriate return code. Deadlines are strict. Standard returns have two business days (weekdays that aren't Federal Reserve holidays) from settlement. Unauthorized debit returns have 60 calendar days and need a signed WSUD. See [Returns, reversals, and exceptions](https://docs.lead.bank/v2/products/ach/exceptions.md) for codes, deadlines, and cutoffs.

You can submit the return before the entry reaches `posted`. Lead holds it and sends it to the Fed after the original posts.

## Testing in sandbox

Create an incoming entry with `POST /v2/simulate/ach/incoming_ach`. It starts in `scheduled`, and you advance it to `posted` with `POST /v2/simulate/ach/{ach_id}/advance`.

## Related

* [The ACH Object](https://docs.lead.bank/v2/products/ach/ach-object.md)
* [ACH Statuses](https://docs.lead.bank/v2/products/ach/statuses.md)
* [Sending ACH](https://docs.lead.bank/v2/products/ach/sending-ach.md)
* [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md)