> ## 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.
# Overview
> Receive or send ACH transfers through the FedACH network.
**Upcoming Change**
We're expanding visibility into the ACH lifecycle by surfacing previously hidden events, introducing new statuses, and adding support for dishonored and contested returns. Partners consuming ACH statuses or webhooks will need to update their integrations before the change is enforced in Q3 2026.
👉 [View Details](/upcoming-changes#ach-status-lifecycle-expansion)
The FedACH system, operated by the Federal Reserve, is an electronic payment network that processes Automated Clearing House (ACH) transactions in the United States. FedACH ensures the timely clearing and settlement of payments through multiple processing windows each business day. Lead has a direct connection to the FedACH network, offering streamlined access to ACH transfer services as close to the payment rails as possible.
## ACH Object
```json theme={null}
{
"id": "ach_xyz001",
"created_at": "2022-06-27T11:22:33Z",
"updated_at": "2022-06-27T11:22:33Z",
"status": "submitted",
"amount": 5000,
"account_id": "account_xyz123",
"account_number_id": "account_number_xyz123",
"direction": "outgoing",
"delivery_type": "same_business_day",
"transaction_type": "credit",
"sec_code": "WEB",
"currency_code": "USD",
"statement_descriptor": "P2P Credit",
"record_details": {
"transaction_code": "checking_credit",
"company_name": "Acme Inc.",
"company_id": "1234",
"company_discretionary_data": "Acme Inc.",
"effective_date": "2022-06-27",
"settlement_date": "2022-06-27",
"individual_id": "string",
"receiver_name": "string",
"descriptive_date": "220627",
"additional_information": "string",
"trace_number": "123456789012345"
},
"iat_details": {
"transaction_type_code": "business",
"destination_country": "CA",
"originator_currency_code": "USD",
"destination_currency_code": "CAD",
"foreign_trace_number": "FRN-2024-98765-INTL",
"additional_information": "Invoice 12345 - February 2022",
"originator": {
"name": "Acme Inc.",
"street_address": "123 Main Street",
"city_state_province": "New York*NY\\",
"country_postal_code": "US*10001\\"
},
"originating_financial_institution": {
"name": "First National Bank",
"identifier_type": "business_identifier_code",
"identifier_code": "FNBUS33XXX",
"branch_country": "US"
},
"receiver": {
"reference_number": "RCV-2024-001",
"name": "Lara Smikle",
"street_address": "456 Maple Avenue",
"city_state_province": "Toronto*ON\\",
"country_postal_code": "CA*M5H 2N2\\"
},
"receiving_financial_institution": {
"name": "Royal Bank of Canada",
"identifier_type": "business_identifier_code",
"identifier_code": "ROYCCAT2XXX",
"branch_country": "CA"
},
"foreign_correspondent_banks": [
{
"name": "Citibank NA",
"identifier_type": "business_identifier_code",
"identifier_code": "CITIUS33XXX",
"branch_country": "US"
}
]
},
"counterparty": {
"name": "Lara Smikle",
"account_number": "1032345678",
"routing_number": "021000021",
"account_type": "checking"
},
"returns": [
{
"type": "return",
"status": "submitted",
"return_code": "R02",
"return_reason": "string",
"trace_number": "123456789012345",
"additional_information": "string"
}
],
"reversal": {
"reversal_reason": "duplicate",
"linked_ach_id": "string"
},
"rejection": {
"reason": "account_number_status",
"details": "Account number account_123 is inactive."
},
"correction": {
"account_number": "1032345678",
"routing_number": "021000021",
"account_type": "checking"
},
"metadata": {
"additionalProp": "string"
}
}
```
## Attributes
| **Attribute** | **Type** | **Description** |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | ID of the ACH object. |
| created\_at | date-time | The ISO-8601 timestamp at which the ACH object was created. |
| updated\_at | date-time | The ISO-8601 timestamp at which the ACH object was last updated. |
| status | string | The current status of the ACH object. Possible values: `scheduled`, `processing`, `submitted`, `posted`, `canceled`, `under_review`, `approved`, `rejected`, `pending_return`, `pending_dishonored_return` , `pending_contested_return` , `returned` , `return_dishonored` , `return_contested `. |
| amount | int64 | The amount of the transaction in cents. |
| account\_id | string | The ID of the Account object. |
| account\_number\_id | string | The ID of the Lead Bank Account Number object. |
| direction | string | Who is initiating the transaction. Possible values: - `outgoing`: You are sending an ACH transaction to a counterparty. - `incoming`: You are receiving an ACH transaction from a counterparty. |
| delivery\_type | string | How fast you want the counterparty to receive the ACH. Possible values: - `same_business_day`: If the ACH request is submitted before the cutoff window with the same business day option, funds will settle on the same day. - `next_business_day`: Standard ACH processing, for funds to settle on the next business day. |
| transaction\_type | string | ACH transaction type. Possible values: `credit`, `debit`. |
| sec\_code | string | Standard Entry Class (SEC) code to use for this ACH object. Lead currently supports `CCD`, `PPD`, `WEB`, `CIE`, `TEL`, and `IAT`. |
| currency\_code | string | A three-letter currency code as defined in ISO 4217. Possible value: `USD`. |
| statement\_descriptor | string | The description you would like to appear on your customers' statement. Maximum number of characters is 10. |
## record\_details (object)
| **Attribute** | **Type** | **Description** |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transaction\_code | string | Identifies the type of debit or credit and the account type. Possible values: `checking_credit`, `checking_credit_prenote`, `checking_debit`, `checking_debit_prenote`, `savings_credit`, `savings_credit_prenote`, `savings_debit`, `savings_debit_prenote`. |
| company\_name | string | The company that initiated the outgoing ACH. - For outgoing ACH, this value is set from the Account Number object. - For incoming ACH, this value is what we receive from the sender. |
| company\_id | string | A 10-digit unique identifier used for identifying companies collecting payments via ACH debit. - For outgoing ACH, this value is set from the Account Number object. - For incoming ACH, this value is what we receive from the sender. |
| company\_discretionary\_data | string | Additional information from the ACH sender on incoming ACH. |
| effective\_date | string | The date the ACH transaction is expected to settle with the financial institution. - For outgoing ACH, the date is set by Lead based on the `delivery_type` field. - For incoming ACH, this value is what we receive from the sender. |
| settlement\_date | string | Date by which funds must be posted to the counterparty's account. |
| individual\_id | string | The name of the individual you are sending funds to. Required for P2P payments. |
| receiver\_name | string | The name of the receiver of funds. This field is set by the counterparty and may or may not be accurate. |
| descriptive\_date | string | The date you would like displayed to the counterparty. Receiving financial institutions may utilize this field to display on the statement. |
| additional\_information | string | Additional information for the ACH recipient. Not all banks will share this message with their end customer. |
| trace\_number | string | The unique number assigned to every ACH entry by an ODFI, which identifies that entry within a specific ACH file. - For outgoing ACH, this is generated by Lead when we submit the ACH. - For incoming ACH, this value is what we receive from the sender. |
## International ACH Transactions (Originating)
### iat\_details (object)
Populated when `sec_code` is `IAT`.
| **Attribute** | **Type** | **Description** |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transaction\_type\_code | string | Code identifying the type of international transaction. Possible values: `annuity`, `business`, `deposit`, `loan`, `miscellaneous`, `mortgage`, `pension`, `rental_lease`, `salary`, `tax`, `telephone`, `internet`, `accounts_receivable`, `back_office_conversion`, `point_of_purchase`, `represented_check`. |
| destination\_country | string | A two-letter country code as defined in ISO 3166-1 alpha-2 identifying the country in which the ACH is to be received. |
| originator\_currency\_code | string | A three-letter currency code as defined in ISO 4217 identifying the currency in which the ACH was originated. |
| destination\_currency\_code | string | A three-letter currency code as defined in ISO 4217 identifying the currency in which the ACH is to be received. |
| foreign\_trace\_number | string | Trace number from the originating foreign payment system. Only present for inbound IAT entries. |
| additional\_information | string | Additional information for the ACH recipient. |
### iat\_details.originator (object)
| **Attribute** | **Type** | **Description** |
| --------------------- | -------- | ----------------------------------------------- |
| name | string | Name of the originator. |
| street\_address | string | Physical street address of the originator. |
| city\_state\_province | string | City and state/province of the originator. |
| country\_postal\_code | string | Country code and postal code of the originator. |
### iat\_details.originating\_financial\_institution (object)
| **Attribute** | **Type** | **Description** |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Name of the originating financial institution. |
| identifier\_type | string | Type of bank identifier. Possible values: `national_clearing_system`, `business_identifier_code`, `iban`. |
| identifier\_code | string | Bank identification number (national clearing system number, BIC, IBAN, etc.). |
| branch\_country | string | A two-letter country code as defined in ISO 3166-1 alpha-2 identifying the country in which the originating financial institution branch is located. |
## International ACH Transactions (Receiving)
### iat\_details.receiver (object)
| **Attribute** | **Type** | **Description** |
| --------------------- | -------- | ---------------------------------------------------- |
| reference\_number | string | Reference number for tracking this receiver/payment. |
| name | string | Name of the receiver/beneficiary of the transaction. |
| street\_address | string | Physical street address of the receiver. |
| city\_state\_province | string | City and state/province of the receiver. |
| country\_postal\_code | string | Country code and postal code of the receiver. |
### iat\_details.receiving\_financial\_institution (object)
| **Attribute** | **Type** | **Description** |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Name of the receiving financial institution. |
| identifier\_type | string | Type of bank identifier. Possible values: `national_clearing_system`, `business_identifier_code`, `iban`. |
| identifier\_code | string | Bank identification number (national clearing system number, BIC, IBAN, etc.). |
| branch\_country | string | A two-letter country code as defined in ISO 3166-1 alpha-2 identifying the country in which the receiving financial institution branch is located. |
### iat\_details.foreign\_correspondent\_banks (array of objects)
| **Attribute** | **Type** | **Description** |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Name of the foreign correspondent bank. |
| identifier\_type | string | Type of bank identifier. Possible values: `national_clearing_system`, `business_identifier_code`, `iban`. |
| identifier\_code | string | Bank identification number (national clearing system number, BIC, IBAN, etc.). |
| branch\_country | string | A two-letter country code as defined in ISO 3166-1 alpha-2 identifying the country in which the foreign correspondent bank branch is located. |
| **Attribute** | **Type** | **Description** |
| id | string | ID of the ACH object. |
| created\_at | date-time | The ISO-8601 timestamp at which the ACH object was created. |
| updated\_at | date-time | The ISO-8601 timestamp at which the ACH object was last updated. |
| status | string | The current status of the ACH object. Possible values: `scheduled`, `processing`, `submitted`, `posted`, `canceled`, `under_review`, `approved`, `rejected`, `pending_return`, `pending_dishonored_return` , `pending_contested_return` , `returned` , `return_dishonored` , `return_contested `. |
| amount | int64 | The amount of the transaction in cents. |
| account\_id | string | The ID of the Account object. |
| account\_number\_id | string | The ID of the Lead Bank Account Number object. |
| direction | string | Who is initiating the transaction. Possible values: - `outgoing`: You are sending an ACH transaction to a counterparty. - `incoming`: You are receiving an ACH transaction from a counterparty. |
| delivery\_type | string | How fast you want the counterparty to receive the ACH. Possible values: - `same_business_day`: If the ACH request is submitted before the cutoff window with the same business day option, funds will settle on the same day. - `next_business_day`: Standard ACH processing, for funds to settle on the next business day. |
| transaction\_type | string | ACH transaction type. Possible values: `credit`, `debit`. |
| sec\_code | string | Standard Entry Class (SEC) code to use for this ACH object. Lead currently supports `CCD`, `PPD`, `WEB`, `CIE`, and `TEL` for outgoing ACH. |
| currency\_code | string | A three-letter currency code as defined in ISO 4217. Possible value: `USD`. |
| statement\_descriptor | string | The description you would like to appear on your customers’ statement. Maximum number of characters is 10. |
## record\_details (object)
| **Attribute** | **Type** | **Description** |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| company\_name | string | The company that initiated the outgoing ACH. - For outgoing ACH, this value is set from the Account Number object. - For incoming ACH, this value is what we receive from the sender. |
| company\_id | string | A 10-digit unique identifier used for identifying companies collecting payments via ACH debit. - For outgoing ACH, this value is set from the Account Number object. - For incoming ACH, this value is what we receive from the sender. |
| company\_discretionary\_data | string | Additional information from the ACH sender on incoming ACH. |
| effective\_date | string | The date the ACH transaction is expected to settle with the financial institution. - For outgoing ACH, the date is set by Lead based on the `delivery_type` field. - For incoming ACH, this value is what we receive from the sender. |
| statement\_date | string | Date by which funds must be posted to the counterparty's account. |
| individual\_id | string | The name of the individual you are sending funds to. Required for P2P payments. |
| receiver\_name | string | The name of the receiver of funds. This field is set by the counterparty and may or may not be accurate. |
| descriptive\_date | string | The date you would like displayed to the counterparty. Receiving financial institutions may utilize this field to display on the statement. |
| additional\_information | string | Additional information for the ACH recipient. Not all banks will share this message with their end customer. |
| trace\_number | string | The unique number assigned to every ACH entry by an ODFI, which identifies that entry within a specific ACH file. - For outgoing ACH, this is generated by Lead when we submit the ACH. - For incoming ACH, this value is what we receive from the sender. |
## counterparty (object)
| **Attribute** | **Type** | **Description** |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| name | string | The name of the counterparty you are transacting with. |
| account\_number | string | The account number for the bank account. |
| routing\_number | string | The routing number for the bank account. This should be the ACH routing number, not the wire routing number. |
| account\_type | string | The account type for the bank account.
Possible values: `checking`, `savings`. |
## returns (array of objects)
| **Attribute** | **Type** | **Description** |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Type of the return record, determined by the respective return code. Possible values: `return`, `dishonored_return`, `contested_return`. |
| status | string | The current status of the ACH object. Possible values: `scheduled`, `processing`, `submitted`, `posted`, `canceled`, `under_review`, `approved`, `rejected`, `pending_return`, `pending_dishonored_return` , `pending_contested_return` , `returned` , `return_dishonored` , `return_contested `. |
| return\_code | string | Nacha return codes. Possible values: `R01` - `R85`. |
| return\_reason | string | Short description of the associated return code. |
| trace\_number | string | The unique number assigned to this ACH return by the ODFI, which identifies the entry within a specific ACH file. |
## reversal (object)
| **Attribute** | **Type** | **Description** |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| reversal\_reason | string | Reason you want to initiate a reversal.
`duplicate`: The ACH is a duplicate of another you've already submitted
`receiver_incorrect`: You've entered incorrect counterparty information
`amount_incorrect`: The payment amount is incorrect
`debit_too_early`: You're debiting the counterparty too early
`credit_too_late`: You're crediting the counterparty too late |
| linked\_ach\_id | string | The ID of the original ACH transaction that is being reversed. |
## rejection (object)
| **Attribute** | **Type** | **Description** |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| reason | string | Provides the reason code about why an ACH transfer was rejected before submission to the network. See rejection reason mapping below for possible values. |
| details | string | A short, human-readable string with more details about why the ACH was rejected. |
| **Reason** | **Details** |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `invalid_format` | Invalid format. Please contact Lead for details. |
| `non_sufficient_funds` | Insufficient funds. Balance result: \[BALANCERESULT]. |
| `ofac_rejection` | Please contact Lead for further details. |
| `per_transaction_limit_exceeded` | Entry would exceed per transaction limit. Current limit value \[LIMITVALUE]. |
| `previously_corrected` | A previous ACH to the same counterparty was corrected (correction id = \[ACHID]). |
| `processor_discretionary_decision` | Please contact Lead for further details. |
| `related_prenote_exception` | ACH entry cannot be created within 3 banking days of a prenote's settlement date. (prenote id = \[ACHID]). |
| `related_prenote_exception` | Previous prenote to this counterparty (id = \[ACHID]) was not accepted. |
| `return_untimely` | Return is not within the proper return timeframe. |
| `reversal_rejection` | Reversal rejected upon review. |
| `unexpected_change_code` | Unexpected change code: \[CHANGECODE]. |
| `unexpected_return_code` | Unexpected return code: \[RETURNCODE]. |
| `unexpected_routing_number` | Invalid routing number provided. |
## correction (object)
| **Attribute** | **Type** | **Description** |
| --------------- | -------- | -------------------------------------------------------------------------------------- |
| account\_number | string | The updated account number for the counterparty. |
| routing\_number | string | The updated routing number for the counterparty. |
| account\_type | string | The updated account type for the counterparty. Possible values: `checking`, `savings`. |
## metadata (object)
A set of key-value pairs that can be used to store additional information related to this object.
## Incoming ACH Transfers
Incoming ACH transfers contain a different set of fields compared to outgoing ACH transfers.
* id
* created\_at
* updated\_at
* status
* amount
* account\_id
* direction
* transaction\_type
* sec\_code
* currency\_code
* statement\_descriptor (may be `NULL`)
* transaction\_code
* company\_name
* company\_id
* company\_discretionary\_data (may be `NULL`)
* effective\_date
* settlement\_date
* individual\_id (may be `NULL`)
* receiver\_name (may be `NULL`)
* descriptive\_date
* additional\_information (may be `NULL`)
* trace\_number
Only present when `sec_code` is `IAT`.
* transaction\_type\_code (may be `NULL`)
* destination\_country (may be `NULL`)
* originator\_currency\_code (may be `NULL`)
* destination\_currency\_code (may be `NULL`)
* foreign\_trace\_number (may be `NULL`)
* originator
* name (may be `NULL`)
* street\_address (may be `NULL`)
* city\_state\_province (may be `NULL`)
* country\_postal\_code (may be `NULL`)
* originating\_financial\_institution
* name (may be `NULL`)
* identifier\_type (may be `NULL`)
* identifier\_code (may be `NULL`)
* branch\_country (may be `NULL`)
* receiver
* reference\_number (may be `NULL`)
* name (may be `NULL`)
* street\_address (may be `NULL`)
* city\_state\_province (may be `NULL`)
* country\_postal\_code (may be `NULL`)
* receiving\_financial\_institution
* name (may be `NULL`)
* identifier\_type (may be `NULL`)
* identifier\_code (may be `NULL`)
* branch\_country (may be `NULL`)
* additional\_information (may be `NULL`)
* foreign\_correspondent\_banks (may be empty array)
* name
* routing\_number
* type
* status
* return\_code
* return\_reason
* trace\_number
At least one of the following fields will be included:
* account\_number
* routing\_number
* account\_type