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

# ACH Statuses

> ACH statuses for incoming and outgoing entries, what each one means, how an entry moves between them, where core transactions are created, and which webhooks fire.

Lead sets every ACH status. Two of your requests change an entry's status. `/cancel` moves a cancellable outgoing entry to `canceled`, and `/return` starts the return chain. Incoming and outgoing entries have different lifecycles.

## Statuses

The table lists each status.

| Status | Direction | Description | Cancellable | Terminal |
| - | - | - | - | - |
| `scheduled` | Incoming, outgoing | Lead accepted the entry and it is waiting for further processing. | Outgoing only | No |
| `under_review` | Incoming, outgoing | A validation rule sent the entry to manual review by Lead. Lead might contact you for more information. | Outgoing only | No |
| `approved` | Outgoing | Manual review passed. The entry continues processing. | Yes | No |
| `processing` | Outgoing | Lead is preparing the entry for submission to the Fed. | No | No |
| `submitted` | Outgoing | Lead submitted the entry to the Fed. | No | No |
| `posted` | Incoming, outgoing | The entry posted to the core balance. `core_transaction_id` is set. | No | No, a posted entry can be returned |
| `rejected` | Incoming, outgoing | Validation or manual review failed. See the `rejection` block. | No | Yes |
| `canceled` | Outgoing | You canceled the entry before Lead processed it. | No | Yes |
| `pending_return` | Incoming, outgoing | A return of the posted entry is in progress. | No | No |
| `returned` | Incoming, outgoing | The return posted. The matching `returns[]` entry has its `core_transaction_id` set. | No | No, a return can be dishonored |
| `pending_dishonored_return` | Incoming, outgoing | A dishonor of the return is in progress. | No | No |
| `return_dishonored` | Incoming, outgoing | The dishonored return posted. The matching `returns[]` entry has its `core_transaction_id` set. | No | No, a dishonor can be contested |
| `pending_contested_return` | Incoming, outgoing | A contest of the dishonored return is in progress. | No | No |
| `return_contested` | Incoming, outgoing | The contested return posted. The matching `returns[]` entry has its `core_transaction_id` set. | No | Yes |

## Incoming entries

The diagram shows the incoming lifecycle.

```mermaid theme={null}
graph LR
    start --> scheduled
    start --> |If required| under_review
    start --> rejected
    under_review --> scheduled
    under_review --> rejected
    scheduled --> posted
    posted -.->|If return initiated| pending_return
    pending_return -.->|Return rejected| posted
    pending_return -.->|Return posts| returned
    returned -.->|If dishonored| pending_dishonored_return
    pending_dishonored_return -.->|Dishonor posts| return_dishonored
    return_dishonored -.->|If contested| pending_contested_return
    pending_contested_return -.->|Contest posts| return_contested
    pending_contested_return -.->|Contest rejected| return_dishonored
```

An incoming entry starts in `scheduled`, or in `under_review` if a validation rule holds it, and moves to `posted` on settlement. You return a `posted` incoming entry with `POST /v2/ach/{ach_id}/return`. The entry moves to `pending_return` and then to `returned` when the return posts.

## Outgoing entries

The diagram shows the outgoing lifecycle.

```mermaid theme={null}
graph LR
    scheduled -.->|If required| under_review
    scheduled -.->|If validation fails| rejected
    scheduled --> processing
    scheduled --> canceled
    under_review --> approved
    under_review --> rejected
    under_review --> canceled
    approved --> processing
    approved --> canceled
    processing --> submitted
    submitted --> posted
    posted -.->|If returned| pending_return
    pending_return --> returned
    returned -.->|If dishonored| pending_dishonored_return
    pending_dishonored_return --> return_dishonored
    pending_dishonored_return -.->|Dishonor rejected| returned
    return_dishonored -.->|If contested| pending_contested_return
    pending_contested_return --> return_contested
```

A successful `POST /v2/ach` returns the entry in `scheduled`. An entry that passes validation moves from `scheduled` to `processing`, `submitted`, and `posted`. An entry that fails a validation rule goes to `under_review`, then to `approved` or `rejected`. You can cancel while the entry is `scheduled`, `under_review`, or `approved`. After it is `processing`, it can't be canceled.

## When a requested action is `rejected`

When an action on a `posted` entry goes to manual review and is `rejected`, the entry returns to the status it held before the action. For example, a return request on a `posted` entry moves it to `pending_return`. If Lead rejects the return, the entry moves back to `posted`. No new `ach.posted` webhook is sent.

## Where core transactions are created

Each posting creates one core transaction, and the ACH object records which event it belongs to.

| Transition | Core transaction |
| - | - |
| Entry moves to `posted` | `core_transaction_id` at the top level is set. |
| Entry moves to `returned` | `core_transaction_id` on the `returns[]` entry with `type` `return` is set. |
| Entry moves to `return_dishonored` | `core_transaction_id` on the `returns[]` entry with `type` `dishonored_return` is set. |
| Entry moves to `return_contested` | `core_transaction_id` on the `returns[]` entry with `type` `contested_return` is set. |

Every other transition changes `status` only. A `rejected` or `canceled` entry never has a core transaction.

## Observing changes

Status changes emit webhook events named `ach.<status>`. The payload is the ACH object.

| Event | Sent for |
| - | - |
| `ach.scheduled` | Incoming entries. |
| `ach.under_review` | Outgoing entries. |
| `ach.approved` | Outgoing entries. |
| `ach.submitted` | Outgoing entries. |
| `ach.posted` | Incoming and outgoing entries, except when the previous status was `pending_return`. |
| `ach.rejected` | Outgoing entries. |
| `ach.returned` | Incoming and outgoing entries. |
| `ach.return_dishonored` | Incoming and outgoing entries. |
| `ach.return_contested` | Incoming and outgoing entries. |
| `ach.corrected` | Outgoing entries, when a Notification of Change arrives. |

`processing`, `canceled`, `pending_return`, `pending_dishonored_return`, and `pending_contested_return` don't emit events. `GET /v2/ach/{ach_id}` returns the current status. What to do on each event is covered on [Sending ACH](https://docs.lead.bank/v2/products/ach/sending-ach.md) and [Receiving ACH](https://docs.lead.bank/v2/products/ach/receiving-ach.md).

## Related

* [The ACH Object](https://docs.lead.bank/v2/products/ach/ach-object.md)
* [ACH Overview](https://docs.lead.bank/v2/products/ach/overview.md)
* [Returns, reversals, and exceptions](https://docs.lead.bank/v2/products/ach/exceptions.md)
* [Webhooks & Events](https://docs.lead.bank/api-reference/using-the-api/webhooks.md)