Overview

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

{
  "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`, `returned`.
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`, `returned`.
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`, `returned`.
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.

Rejection Reasons

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.

Core Fields

id
created_at
updated_at
status
amount
account_id
direction
transaction_type
sec_code
currency_code
statement_descriptor (may be NULL)

record_details (object)

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

iat_details (object)

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)

counterparty (object)

name
routing_number

returns (array of objects)

type
status
return_code
return_reason
trace_number

correction (object)

At least one of the following fields will be included:

account_number
routing_number
account_type

Foundations

API Guides

ACH Object

Attributes

record_details (object)

International ACH Transactions (Originating)

iat_details (object)

iat_details.originator (object)

iat_details.originating_financial_institution (object)

International ACH Transactions (Receiving)

iat_details.receiver (object)

iat_details.receiving_financial_institution (object)

iat_details.foreign_correspondent_banks (array of objects)

record_details (object)

counterparty (object)

returns (array of objects)

reversal (object)

rejection (object)

correction (object)

metadata (object)

Incoming ACH Transfers

Foundations

API Guides

​ACH Object

​Attributes

​record_details (object)

​International ACH Transactions (Originating)

​iat_details (object)

​iat_details.originator (object)

​iat_details.originating_financial_institution (object)

​International ACH Transactions (Receiving)

​iat_details.receiver (object)

​iat_details.receiving_financial_institution (object)

​iat_details.foreign_correspondent_banks (array of objects)

​record_details (object)

​counterparty (object)

​returns (array of objects)

​reversal (object)

​rejection (object)

​correction (object)

​metadata (object)

​Incoming ACH Transfers

ACH Object

Attributes

record_details (object)

International ACH Transactions (Originating)

iat_details (object)

iat_details.originator (object)

iat_details.originating_financial_institution (object)

International ACH Transactions (Receiving)

iat_details.receiver (object)

iat_details.receiving_financial_institution (object)

iat_details.foreign_correspondent_banks (array of objects)

record_details (object)

counterparty (object)

returns (array of objects)

reversal (object)

rejection (object)

correction (object)

metadata (object)

Incoming ACH Transfers