Skip to main content

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.

​
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:
  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 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
  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 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:
  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‘reversestheoriginaldeposit4.A20 `withdrawal` reverses the original deposit 4. A 20 hold_release balances the account
OrderTransaction TypeAmount
1deposit20
2hold-20
3withdrawal-20
4hold_release20

​
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
OrderTransaction TypeAmount
1withdrawal20
2deposit-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.
CodeReasonDescription
R01Insufficient fundsAvailable balances is not sufficient to cover the dollar amount of the debit entry.
R02Account closedA previously open account is now closed.
R03No account or unable to locate accountThe account number does not correspond to the individual identified in the entry or a valid account.
R04Invalid account number structureThe account number fails the check digit validation or may contain an incorrect number of digits.
R05Unauthorized debit to consumer account using a corporate SEC codeA ccd or ctx business debit entry was transmitted to a consumer account, and was not authorized by the recipient.
R06Returned per ODFI’s requestThe ODFI has requested that the RDFI return the entry.
R07Authorization revoked by customerA receipient who previously authorized an entry has revoked authorization with the originator.
R08Payment stoppedThe recipient has placed a stop payment order on this debit Entry.
R09Uncollected fundsA sufficient balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit Entry.
R10Customer advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s AccountThe 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.
R11Customer Advises Entry Not in Accordance with the Terms of AuthorizationThe 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.
R12Branch sold to another DFIA financial institution received an Entry to an account that was sold to another financial institution maintained at a branch sold to another financial institution.
R13Invalid ACH routing numberEntry contains an invalid ACH routing number.
R14Representment payee deceased or unable to continue in that capacityRepresentative payee is deceased or unable to continue in that capacity. The beneficiary is not deceased.
R15Beneficiary of account holder deceasedEither the beneficiary or account holder is deceased.
R16Account 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.
R17File 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.
R18Improper 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.
R19Amount field errorImproper formatting of the amount field, or the allowed amounts of the SEC code used does not match the dollar value of the entry.
R20Non-transaction accountPolicies or regulations (such as Regulation D) prohibit or limit activity to the receiving account based on its type.
R21Invalid company identificationThe company ID information is not valid.
R22Invalid individual ID numberThe recipient has indicated to the RDFI that the number with which the Originator was identified is not correct.
R23Credit entry refused by receiverAny credit entry that is refused by the recipient may be returned by the RDFI.
R24Duplicate entryRDFI has received what appears to be a duplicate entry.
R25Addenda errorImproper formatting of the addenda record information.
R26Mandatory field errorErroneous data or missing data in a mandatory field.
R27Trace number errorOriginal entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record.
R28Routing number check digit errorThe check digit for a routing number is not valid.
R29Corporate customer advises not authorizedRDFI has been notified by business account holder that a specific transaction is unauthorized.
R30RDFI not participant in check truncation programFinancial institution not participating in automated check safekeeping application.
R31Permissible return entryThe RDFI may return a CCD or CTX entry that the ODFI agrees to accept.
R32RDFI nonsettlementRDFI is not able to settle the entry.
Early ACH Posting Testing ACH