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

# ACH Overview

This guide covers ACH payment processing through the ECRYPT API. It explains how bank account data is represented, how ACH transactions are submitted and settled, and what actions you can take after a transaction is created.

***

## How ACH Works

ACH (Automated Clearing House) is a bank-to-bank payment network operated by Nacha that moves funds electronically between U.S. financial institutions. Unlike card transactions, ACH payments are not authorized in real time. Transactions are submitted in batches throughout the day, processed overnight by the ACH network, and settled within 1-3 business days.

ACH supports two directions of money movement:

* **Debit:** Funds are pulled from a customer's bank account into your merchant account. This is the most common flow for collecting payments.
* **Credit:** Funds are pushed from your merchant account into a recipient's bank account. Typically used for refunds, payouts, or disbursements.

***

## Bank Account Data

Two fields are required to tokenize a bank account. Additional fields can be included for record-keeping and statement clarity.

### Required

**`accountNumber`:** The number that identifies the specific account at the financial institution. Raw account numbers should never be stored in your system. Use tokenization instead.

**`routingNumber`:** A 9-digit number that identifies the financial institution. Routing numbers appear at the bottom-left of a paper check.

### Optional

**`name`:** The name of the individual or business that owns the account. Included in the ACH transaction record transmitted to the network.

**`accountType`:** Indicates whether the account is checking (`0`) or savings (`1`).

**`checkNumber`:** The check number associated with the transaction, if applicable.

***

## Tokenization

Before initiating an ACH transaction, tokenize the bank account details. Tokenization replaces the routing number and account number with a non-sensitive token that is safe to store and reuse.

To tokenize a bank account, send the account details to `POST /v1/tokens` using the `check` object. Only `accountNumber` and `routingNumber` are required:

```bash theme={null} theme={null}
curl --request POST \
     --url https://api.ecrypt.com/v1/tokens \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "check": {
    "account_number": "123123123",
    "routing_number": "123123123",
    "name": "Jane Smith",
    "check_number": "001",
    "account_type": "Checking"
  }
}
'
```

```json theme={null} theme={null}
{
  "token": "200625bb-7c38-40af-b3cf-4b9d4304d80c",
  "metadata": {
    "accountNumber": "1*****3123"
  },
  "requestId": "0HNK1A7BLRLH00000005E"
}
```

The token string is what you pass in all subsequent transaction requests. The raw account number is never stored or returned after this point.

***

## Transaction Lifecycle

ACH transactions do not use an authorization and capture model. There is no real-time approval step and no hold placed on funds. When you submit an ACH transaction, it is queued for processing and settlement begins asynchronously.

### Submitting a Transaction

To initiate an ACH transaction, send a request to `POST /v1/transactions/sale` with the token from the tokenization step and the desired amount.

```bash theme={null} theme={null}
curl --request POST \
     --url https://api.ecrypt.com/v1/transactions/sale \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "payment": {
    "token": "200625bb-7c38-40af-b3cf-4b9d4304d80c"
  },
  "amount": {
    "value": 100
  }
}
'
```

A successful submission returns a `transactionId` that you use for all subsequent operations (void, refund, etc.).

### Pending

Once submitted, the transaction enters a `pending` state. ECRYPT batches ACH transactions and submits them to the ACH network on a regular processing schedule.

### Settlement

After the batch is submitted to the network, settlement typically completes within 1-3 business days depending on the receiving bank and the time of submission. The transaction status changes from `pending` to `settled` once funds have transferred.

Because there is no real-time authorization, a submitted transaction does not guarantee that funds are available. Insufficient funds, closed accounts, and invalid account data are discovered only during settlement or in the form of a return.

### Returns

A return occurs when the receiving bank rejects the transaction after it has been submitted. Returns are identified by a standardized R-code. Common return reasons include:

| Return Code | Description                               |
| ----------- | ----------------------------------------- |
| R01         | Insufficient funds                        |
| R02         | Account closed                            |
| R03         | No account or unable to locate            |
| R04         | Invalid account number                    |
| R10         | Customer advises not authorized           |
| R29         | Corporate customer advises not authorized |

Returns can arrive up to 2 banking days after settlement for most codes. Unauthorized transaction claims (R05, R07, R10, R29) have an extended return window of up to 60 days for consumers.

ECRYPT delivers return notifications via webhook. See [Event Types](/docs/event-types) for the relevant event payload.

For a complete list of ACH return codes, see [ACH Response Codes](/docs/ach-response-codes).

***

## Managing Transactions

Once a transaction exists, the actions available to you depend on whether it has settled. All actions reference the `transactionId` returned at submission.

### Pre-Settlement

**Void:** Cancels the transaction before it settles. No funds are transferred.

```bash theme={null} theme={null}
curl --request POST \
     --url https://api.ecrypt.com/v1/transactions/void \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "transaction_id": "{{transaction_id}}"
}
'
```

### Post-Settlement

**Refund:** Returns funds to the originating account after settlement has completed. A refund initiates a new ACH credit in the opposite direction of the original debit.

```bash theme={null} theme={null}
curl --request POST \
     --url https://api.ecrypt.com/v1/transactions/refund \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "transaction_id": "{{transaction_id}}",
  "amount": 100
}
'
```

Partial refunds are supported. You can issue multiple partial refunds against a single settled transaction as long as the total refunded amount does not exceed the original transaction amount.

| Timing          | Action                   | Funds Move?    |
| --------------- | ------------------------ | -------------- |
| Pre-settlement  | Void                     | No             |
| Post-settlement | Refund (full or partial) | Yes (returned) |

***

## Next Steps

* [ACH Response Codes](/docs/ach-response-codes) - Full list of return codes and their meanings
* [Subscriptions](/docs/subscriptions) - Set up recurring ACH billing
* [Retry Logic](/docs/retry-logic) - Handle returns and failed transactions automatically
* [Webhooks Setup](/docs/webhooks-setup) - Receive return and settlement notifications
* [Customer Wallet](/docs/customer-wallet) - Store tokenized bank accounts for returning customers