> ## Documentation Index
> Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ACH Returns
> ACH payments can be returned for various reasons including insufficient funds, closed accounts, or incorrect account details. This guide covers identifying returned ACH payments, handling return transactions, and initiating returns for originated and incoming ACH transfers.
## 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](/reference/ach) 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:
1. You originate an ACH debit using the Treasury Prime API
2. The RDFI receives the ACH but the account has insufficient funds
3. The RDFI issues an ACH return with [return code](#ach-return-codes) `R01` (Insufficient Funds)
4. The ODFI (Treasury Prime partner bank) receives the return and notifies Treasury Prime
5. Treasury Prime updates the ACH object:
* Changes `status` to `returned`
* Populates `error` field with the [return code](#ach-return-codes)
6. 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](#ach-return-codes) 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](/reference/ach) 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
```bash bash theme={null}
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](https://docs.treasuryprime.com/reference/patch_ach-id) endpoint.
**Note:** This feature must be enabled for your organization. If not enabled, contact Treasury Prime support at [support@treasuryprime.com](mailto: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](#ach-return-codes) `R01` (insufficient funds):
```bash bash theme={null}
{
"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:
1. A \$20 `deposit` is applied to the originating account
2. 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:
1. 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](/reference/patch_incoming_ach-id) 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](/docs/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](/docs/early-posting-for-incoming-ach-credits)
[Testing ACH](/docs/testing-ach)