ACH Origination

ACH transfers created using the /ach endpoint are referred to as “API originated” ACH transfers as they are originated by the Treasury Prime platform. They support both credit and debit transfers, allowing funds to be sent (credited) to a recipient's account, or pulled (debited) from another account. Beyond this, originated ACH transfers support two levels of service—sameday and standard—which impacts the amount of time required for the transfer to settle.

Creating an ACH Transfer

Below is a sample request for creating an ACH transfer. For a more detailed overview of this process, please see the guide How to Transfer Funds Between Accounts Using ACH.

$ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/ach \
    -H 'Content-Type: application/json' \
    -d '{
          "account_id": "acct_1234567890",
          "amount": "100.00",
          "counterparty_id": "cp_0987654321",
          "direction": "credit",
          "sec_code": "ppd"
        }'

Required Fields Explained

For a complete list of fields, see the ACH object API reference here.

Types of ACH Transfers

ACH supports two types of transfers: credit and debit. Also referred to as the “direction” of the transfer, the type of transfer selected determines whether the funds are pushed to a recipient's account, or pulled from their account.

ACH Credit

An ACH credit is used when you wish to send or “push” funds to a recipient. An example of an ACH credit transaction is payroll direct deposit, where an employer credits funds to an employee's account.

Lifecycle of an Originated ACH Credit

1. A balance check is performed on the originating account to ensure sufficient funds are available to cover the transaction.
2. The ACH object is created with an initial status of pending.
3. A hold is placed on the originating account to secure the funds for the transaction.
4. The ACH status transitions to processing, the initial hold is released, and a withdrawal is made from the funding account.
5. The status of the ACH transitions to sent and the NACHA file containing the ACH is sent to the bank for processing.
6. Finally, the funds are deposited into the recipient's bank account.

ℹ️

Note that the timing of status changes and funds availability varies by bank and by ACH service. See the the section on ACH timing below for more detail.

ACH Debit

An ACH debit is used when you wish to “pull” funds from an external account. Bill Payments, where a merchant is given permission to pull funds from their customer's account, is one example of where an ACH debit might be used.

Lifecycle of an originated ACH Debit

1. The ACH object is created with an initial status of pending.
2. The ACH status transitions to processing.
3. The status of the ACH is updated to sent and the scheduled_settlement value is set.
4. The NACHA file containing the ACH is sent to the bank for processing.
5. Finally, the funds are deposited into the originating bank account.

How Long Does an ACH Take?

The topic of how long it will take for funds to be received when sending an ACH is a bit complex and often ends in statements like “it depends”. To help clarify this, let’s look at the key factors that determine just how long it will take for the funds from an ACH to be received.

Service Level

ACH supports two levels of service—standard and sameday—which ultimately determine how fast the ACH will settle. While the type of ACH (credit or debit), and the processes defined by the Receiving Depository Financial Institution (RDFI) also play a role in settlement time, the general timelines for standard and sameday ACH processing are as follows:

ℹ️

Note that ACH transactions are only processed during business banking days, so you will need to keep this in mind when assessing transfer timelines.

Submission Time

As a matter of practice, ACH transfers are processed in batches by the ODFI (Originating Depository Financial Institution) at set intervals throughout the day. The times at which these batches are processed, known as “processing windows,” are defined by each ODFI, so it is recommended you speak with your Customer Success Manager or Bank Partner(s) to understand the specific timings defined by your partner bank(s). It’s also worth noting that there are separate processing windows for standard and sameday ACH transfers. In order for an ACH to be included in a specific processing window, it needs to be submitted prior to the cut-off time for that window. Treasury Prime defines cut-off times as being 30 minutes prior to the scheduled start of the processing window.

To bring this all together, let’s look at the example of a made-up ODFI, Prime Bank.

Prime Bank ACH Processing Windows

Prime Bank offers three ACH processing windows each day: one for standard ACH transfers, and two for sameday ACH transfers. In order for a sameday ACH to be included in the 12:30 processing window, the ACH would need to be created prior to the 12:00 cut-off time. If the cut-off window is missed, then the ACH will be included in the next processing window, which in this case would be 11:30 the following business day (as 12:30 is the final processing window for sameday transfers).

Direction

The direction of the ACH also plays a role in determining how long the transfer will take to complete. Specifically, ACH debits tend to take a bit longer than their credit counterparts. Let’s take a quick look at why this is, and how it affects ACH processing.

As it is unknown whether sufficient funds will be available in the account when an ACH debit is initiated, there is an additional level of potential fraud risk introduced in this type of ACH payment. To counteract this, and aid in fraud prevention, ACH debits include a delayed settlement period (imposed by the ODFI) prior to releasing funds to the recipient's account. This delay provides the RDFI an opportunity to fulfill the debit request and, if necessary, respond with an error. While the length of this delay can vary de on the arrangements made with your bank partner, funds for sameday ACHs are generally released to the recipient after 48 business hours, and standard ACHs after 72 business hours.

For ACH debit transfers originating from Treasury Prime ledger accounts, the ACH object will be populated with a scheduled_settlement value defining when the funds are expected to become available in the recipient's account. This value is set when the ACH reaches a status of processed and will take into account the service level selected and any other variables involved in the ACH settlement timing.

Limits on Total ACH Transaction Amounts

A set of velocity limits exists for debit and credit ACH transfers which limit the total dollar amount that can be transacted for each transfer type within a rolling 24-hour period. These limits are defined by your bank partner and can be adjusted with approval from the bank. While separate limits exist for debit and credit ACHs, there is no differentiation among service levels, so both sameday and standard ACHs will count against the daily limit for each type. The timestamp supplied in the created_at property of the ACH object is used to determine which transactions are included within the rolling 24-hour limit. Canceled ACH transactions do not count toward this limit.

What Data Will Be Shown to ACH Recipients?

The short answer to this question is “it depends”. There are a number of parties involved in the processing of ACH transfers, and each plays a role in determining what information is or is not displayed to the end user.

For ACH transfers initiated on the Treasury Prime platform, the description and addenda fields are passed with the transaction; however, whether this information is displayed to the recipient is solely up to the RDFI. As shown in the example below, the recipient of the ACH might see “Test ACH” show up in their banking application, or they might not. It’s up to the RDFI.

{
      "description": "Test ACH",
      "amount": "15.00",
      "service": "sameday",
      "counterparty_id": "cp_11gsczk76t1234",
      "bankdata": {
          "hold_id": "ttx_11hq81f9ef1234"
      },
      "bank_id": "bank_treasuryprime",
      "account_id": "acct_11hq4m9aee1234",
      "addenda": [],
      "org_id": "org_1evy4cx1234",
      "batch_key": null,
      "effective_date": "2022-11-15",
      "updated_at": "2022-11-15T21:36:38Z",
      "status": "sent",
      "id": "ach_11hq81f9ef1234",
      "error": null,
      "sec_code": "web",
      "scheduled_settlement": null,
      "direction": "credit",
      "created_at": "2022-11-15T21:34:33Z",
      "userdata": {
          "scheduled_settlement": 15
      }
  }

Monitoring the Status of an ACH

The status field of the ACH object represents the current status of the ACH transfer. You can monitor changes to this status (and thus the processing of the ACH) by subscribing to the ach.update webhook. It’s important to note that unless an ACH is returned or encounters an error during processing then sent will be its terminal status. This is because the ACH network does not support sending updates to confirm the receipt of funds or the successful completion of a transfer after it has been sent for processing. If an error is encountered or an ACH is returned, then the status will be updated accordingly. Otherwise, a successful ACH will end in a status of sent.

Canceling an ACH

An ACH originated on the Treasury Prime platform may be canceled while it is in a status of pending. Once the ACH transitions from pending to processing, then it may no longer be canceled. To cancel an ACH, update its status to canceled as outlined below.

$ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/ach/ach_1029384756 \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{
          "status": "canceled"
        }'

Canceling a pending ACH can also be done directly in the Treasury Prime Dashboard app for users with the required permissions.

Identifying Transactions Related to an ACH

There are two fields that are used to map an ACH to the related transaction(s) that are generated as part of the payment flow. The first, trace_id, can be used to surface all transactions related to a particular ACH (including hold, hold_release, withdrawal, and deposit transactions).

The second field, ach_id is used to identify only transactions that resulted in the movement of funds (a withdrawal or deposit). For transactions that did not result in funds movement (such as a hold, or hold_release) the ach_id field will be null.

ℹ️

Note that the values for both of the trace_id and ach_id fields will be the id of the originating ACH object.

Example ACH Debit and Resulting Transactions

Let's run through an example of what transactions might result from the creation of an ACH. Say you create an ACH debit for $100 and you get the response below, including its id of “ach_1234”.

{
    "description": null,
    "amount": "100.00",
    "service": "standard",
    "counterparty_id": "cp_11gsczk76tqabc",
    "bankdata": null,
    "bank_id": "bank_treasuryprime",
    "account_id": "acct_11hq4m9aee6123",
    "addenda": [],
    "org_id": "org_1evy4cx2abc",
    "batch_key": null,
    "effective_date": "2022-11-22",
    "updated_at": "2022-11-22T15:31:55Z",
    "status": "",
    "id": "ach_1234",
    "error": null,
    "sec_code": "ppd",
    "scheduled_settlement": null,
    "direction": "debit",
    "created_at": "2022-11-22T15:31:55Z",
    "userdata": null
}

The ACH is processed and ultimately results in three transactions being posted to the originating account: a deposit, a hold, and a hold_release. Reviewing these three transactions, we can see that:

• The deposit transaction (which deposits $100 into the account) contains both a trace_id and ach_id each with the same value of “ach_1234”.
• The hold and hold_release (which do not result in funds movement) have a trace_id of “ach_1234”.
  In all three instances, the value “ach_1234” matches the id the originating ACH, allowing us to map these objects.

Returning Related Transactions Via the API

To find the transactions related to an ACH, you can use the /transaction endpoint to return all transaction results, then filter on either trace_id or ach_id depending on which result set you are looking for. In both cases, the value supplied will be the id of originating ACH (ex: ach_1234).

Filtering Transactions by trace_id

This will return all transactions that are related to ach_1234:

https://api.treasuryprime.com/transaction?trace_id=ach_1234

Filtering Transactions by ach_id

This will return only transactions that rsesulted in the movement of funds from ach_1234:

https://api.treasuryprime.com/transaction?ach_id=ach_1234

The Resulting Transaction Details

The deposit Transaction

This first transaction deposits funds from the ACH debit into the originating account.

ach_id = “ach_1234”

trace_id = “ach_1234”

{
  "check_id": null,
  "type_source": null,
  "amount": "100.00",
  "issued_check_id": null,
  "date": "2022-11-22",
  "wire_id": null,
  "desc": "ACH DEBIT [ach_1234][ccd][standard]",
  "wire": null,
  "book_id": null,
  "type": "deposit",
  "incoming_wire": null,
  "summary": null,
  "balance": "5184.80",
  "billpay_payment_id": null,
  "id": "ttx_11hqswj6f400d9",
  "card_id": null,
  "trace_id": "ach_1234",
  "incoming_wire_id": null,
  "extended_timestamp": "2022-11-22T16:01:10Z",
  "extended_timestamp_precise": "2022-11-22T16:01:10.709Z",
  "ach_id": "ach_1234",
  "fingerprint": "ttx_11hqswj6f400d9",
  "check_number": null,
}

The hold Transaction

This transaction places a hold on the newly deposited funds. This will remain in place until the transaction has been fully settled.

trace_id = “ach_1234”

{
  "check_id": null,
  "type_source": null,
  "amount": "-100.00",
  "issued_check_id": null,
  "date": "2022-11-22",
  "wire_id": null,
  "desc": "ACH debit settlement hold",
  "wire": null,
  "book_id": null,
  "type": "hold",
  "incoming_wire": null,
  "summary": null,
  "balance": "5184.80",
  "billpay_payment_id": null,
  "id": "ttx_11hqswj6f400db",
  "card_id": null,
  "trace_id": "ach_1234",
  "incoming_wire_id": null,
  "extended_timestamp": "2022-11-22T16:01:10Z",
  "extended_timestamp_precise": "2022-11-22T16:01:10.012Z",
  "ach_id": null,
  "fingerprint": "ttx_11hqswj6f400db",
  "check_number": null,
}

The hold_release Transaction

This transaction fully releases the prior hold, making the funds deposited from the ACH fully available to the account holder.

trace_id = “ach_1234”

{
  "check_id": null,
  "type_source": null,
  "amount": "100.00",
  "issued_check_id": null,
  "date": "2022-11-22",
  "wire_id": null,
  "desc": "Release hold ttx_11hqswj6f400db",
  "wire": null,
  "book_id": null,
  "type": "hold_release",
  "incoming_wire": null,
  "summary": null,
  "balance": "5184.80",
  "billpay_payment_id": null,
  "id": "ttx_11hqswj7f4abcd",
  "card_id": null,
  "trace_id": "ach_1234",
  "incoming_wire_id": null,
  "extended_timestamp": "2022-11-22T16:01:11Z",
  "extended_timestamp_precise": "2022-11-22T16:01:11.432Z",
  "ach_id": null,
  "fingerprint": "ttx_11hqswj7f400dh",
  "check_number": null,
}