ACH Returns

Return timeframes

The Receiving Depository Financial Institution (RDFI) has 2 business days to return most ACH payments. For unauthorized transactions on consumer accounts, the RDFI has up to 60 calendar days to initiate a return. When the Originating Depository Financial Institution (ODFI) receives a return, Treasury Prime updates the ACH object status to returned and populates the error field with the appropriate return code.

ACH return flow

This example shows the flow when an ACH debit is returned due to insufficient funds:

You originate an ACH debit using the Treasury Prime API
The RDFI receives the ACH but the account has insufficient funds
The RDFI issues an ACH return with return code R01 (Insufficient Funds)
The ODFI (Treasury Prime partner bank) receives the return and notifies Treasury Prime
Treasury Prime updates the ACH object:
- Changes status to returned
- Populates error field with the return code
The ach.update webhook fires to notify you of the status change

Identify ACH returns

When the RDFI returns an ACH payment, Treasury Prime updates the ACH object with:

status: Set to returned
error: Populated with the return code explaining why the payment was returned

You can identify returned ACH payments in two ways:

Monitor webhooks

The ach.update webhook fires when an ACH object changes status. Use this webhook to notify your customers that their payment was not completed and may require follow-up action.

Query the API

Filter the /ach endpoint by status=returned to retrieve all returned ACH payments. This allows you to build internal dashboards or customer-facing views of returned payments.

Example Request to List Returned ACH Objects

curl -u $API_KEY_ID:$API_KEY_VALUE {% api-endpoint /%}/ach?status=returned

Return an originated ACH

To return an ACH transfer you originated, use the Update an ACH endpoint. Note: This feature must be enabled for your organization. If not enabled, contact Treasury Prime support at support@treasuryprime.com with:

The transaction id of the originated ACH
The reason for the return request
Any other relevant information

Treasury Prime will submit the return request to the ODFI. If approved, the ODFI submits the return to the RDFI. A successful return posts an additional transaction to the account to reverse the original transaction.

Incoming ACH returns availability varies by bank partner and requires bank approval. Contact your relationship manager to discuss availability and any associated costs.

Example returned ACH object

This example shows an ACH debit returned by the RDFI with return code R01 (insufficient funds):

{
    "description": "ACH DEBIT RETURN [ach_11hqstvbf3w5es][ppd][standard] Target",
    "amount": "100.00",
    "service": "standard",
    "counterparty_id": "cp_11gsczk76tqj1p",
    "bank_id": "bank_treasuryprime",
    "account_id": "acct_11hq4m9aee67ye",
    "addenda": [],
    "org_id": "org_1evy4cx2km5",
    "batch_key": null,
    "effective_date": "2022-11-22",
    "updated_at": "2022-11-22T16:00:13Z",
    "status": "returned",
    "id": "ach_11hqstvbf3w5es",
    "error": "R01",
    "sec_code": "ppd",
    "scheduled_settlement": "2022-11-25T16:20:13Z",
    "direction": "debit",
    "created_at": "2022-11-22T15:31:55Z",
    "userdata": null
}

Transactions for returned ACH payments

An ACH return reverses the funds movement from the original ACH:

ACH debits (which create a deposit): A withdrawal reverses the original deposit
ACH credits (which create a withdrawal): A deposit reverses the original withdrawal

These balance updates trigger the account.update webhook.

Scenario 1: Returned ACH debit

When you create a $20 ACH debit:

A $20 deposit is applied to the originating account
A $20 hold is placed on those funds

When the RDFI returns the ACH: 3. A

20 `withdrawal` reverses the original deposit 4. A

20 hold_release balances the account

Order	Transaction Type	Amount
1	`deposit`	20
2	`hold`	-20
3	`withdrawal`	-20
4	`hold_release`	20

Scenario 2: Returned ACH credit

When you create a $20 ACH credit:

A $20 withdrawal is made from the originating account

When the RDFI returns the ACH: 2. A $20 deposit reverses the initial withdrawal

Order	Transaction Type	Amount
1	`withdrawal`	20
2	`deposit`	-20

Return an incoming ACH

To return an incoming ACH transfer originated by a third party, use the Update an Incoming ACH endpoint with one of the supported return codes: R29, R10, or R20. For detailed information including timing requirements and example requests, see the Returning Incoming ACH guide.

ACH return codes

Below is the list of the most commonly encountered ACH return codes.

Code	Reason	Description
R01	Insufficient funds	Available balances is not sufficient to cover the dollar amount of the debit entry.
R02	Account closed	A previously open account is now closed.
R03	No account or unable to locate account	The account number does not correspond to the individual identified in the entry or a valid account.
R04	Invalid account number structure	The account number fails the check digit validation or may contain an incorrect number of digits.
R05	Unauthorized debit to consumer account using a corporate SEC code	A `ccd` or `ctx` business debit entry was transmitted to a consumer account, and was not authorized by the recipient.
R06	Returned per ODFI’s request	The ODFI has requested that the RDFI return the entry.
R07	Authorization revoked by customer	A receipient who previously authorized an entry has revoked authorization with the originator.
R08	Payment stopped	The recipient has placed a stop payment order on this debit Entry.
R09	Uncollected funds	A sufficient balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit Entry.
R10	Customer advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account	The RDFI has been notified by the recipient that the recipient does not know the identity of the originator, has no relationship with the originator, or has not authorized the originator to debit their account.
R11	Customer Advises Entry Not in Accordance with the Terms of Authorization	The RDFI has been notified by the Receiver that the Originator and Receiver have a relationship and an authorization to debit exists, but there is an error or defect in the payment such that the entry does not conform to the terms of the authorization.
R12	Branch sold to another DFI	A financial institution received an Entry to an account that was sold to another financial institution maintained at a branch sold to another financial institution.
R13	Invalid ACH routing number	Entry contains an invalid ACH routing number.
R14	Representment payee deceased or unable to continue in that capacity	Representative payee is deceased or unable to continue in that capacity. The beneficiary is not deceased.
R15	Beneficiary of account holder deceased	Either the beneficiary or account holder is deceased.
R16	Account Frozen/Entry Returned Per OFAC Instruction	(1) Access to the account is restricted due to specific action taken by the RDFI or by legal action; or (2) OFAC has instructed the RDFI or Gateway to return the Entry.
R17	File record edit criteria/Entry with invalid account number initiated under questionable circumstances	(1) Field(s) cannot be processed by RDFI; or (2) the Entry contains an invalid DFI Account Number (account closed / no account / unable to locate account / invalid account number) and is believed by the RDFI to have been initiated under questionable circumstances.
R18	Improper effective entry date	(1) The Effective Entry Date for a credit Entry is more than two Banking Days after the processing date; or (2) the Effective Entry Date for a debit Entry is more than one Banking Day after the processing date.
R19	Amount field error	Improper formatting of the amount field, or the allowed amounts of the SEC code used does not match the dollar value of the entry.
R20	Non-transaction account	Policies or regulations (such as Regulation D) prohibit or limit activity to the receiving account based on its type.
R21	Invalid company identification	The company ID information is not valid.
R22	Invalid individual ID number	The recipient has indicated to the RDFI that the number with which the Originator was identified is not correct.
R23	Credit entry refused by receiver	Any credit entry that is refused by the recipient may be returned by the RDFI.
R24	Duplicate entry	RDFI has received what appears to be a duplicate entry.
R25	Addenda error	Improper formatting of the addenda record information.
R26	Mandatory field error	Erroneous data or missing data in a mandatory field.
R27	Trace number error	Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record.
R28	Routing number check digit error	The check digit for a routing number is not valid.
R29	Corporate customer advises not authorized	RDFI has been notified by business account holder that a specific transaction is unauthorized.
R30	RDFI not participant in check truncation program	Financial institution not participating in automated check safekeeping application.
R31	Permissible return entry	The RDFI may return a `CCD` or `CTX` entry that the ODFI agrees to accept.
R32	RDFI nonsettlement	RDFI is not able to settle the entry.

Early ACH Posting Testing ACH

Documentation

Accounts

Cards

Payments

Return timeframes

ACH return flow

Identify ACH returns

Monitor webhooks

Query the API

Example Request to List Returned ACH Objects

Return an originated ACH

Example returned ACH object

Transactions for returned ACH payments

Scenario 1: Returned ACH debit

Scenario 2: Returned ACH credit

Return an incoming ACH

ACH return codes

​Return timeframes

​ACH return flow

​Identify ACH returns

​Monitor webhooks

​Query the API

Example Request to List Returned ACH Objects

​Return an originated ACH

​Example returned ACH object

​Transactions for returned ACH payments

​Scenario 1: Returned ACH debit

​Scenario 2: Returned ACH credit

​Return an incoming ACH

​ACH return codes

Return timeframes

ACH return flow

Identify ACH returns

Monitor webhooks

Query the API

Return an originated ACH

Example returned ACH object

Transactions for returned ACH payments

Scenario 1: Returned ACH debit

Scenario 2: Returned ACH credit

Return an incoming ACH

ACH return codes