| Event | Description |
|---|---|
| AchTransactionAccepted | When transaction is accepted |
| AchFailedTransactionExpired | When transaction has expired |
| AchFailedReturnedOrClosedAccount | When transaction is returned due to a closed account or any other return reason |
| AchFailedRejectedWithReason | When transaction is rejected for a reason |
| AchFailedGeneralError | When transaction has failed due to general error |
| AchFailedHighRiskOrPotentialFraud | When transaction is rejected as high-risk or potential fraud |
| AchFailedDueToMerchantSetup | When transaction failed because of invalid or inactive merchant id |
| AchFailedInvalidValueForField | When transaction failed due to invalid value for field |
| AchFailedAuthorizationRevoked | When transaction failed because authorization was revoked |
| AchFailedDuplicateTransaction | When transaction failed due to duplicated transaction |
| AchFailedDueToProcessorTimeout | When transaction is not successfully processed due to processor timeout |
| AchFailedTransactionNotAllowed | When transaction is not allowed by provider |
| AchBankAccountVerificationFailed | When transaction fails because the bank account verification failed |
| AchDebitResponseReceived | When response is received for a debit transaction |
| AchCreditResponseReceived | When response is received for a credit transaction |
| AchTransactionReturned | When transaction returned from bank and will be resubmitted in the next banking cycle. Note that this does not mean the transaction failed. |
| AchTransactionResubmitted | When transaction is resubmitted for processing again |
| AchCancellationFailed | When request to cancel transaction failed |
| AchCancellationFailedDueToMerchantSetup | When request to cancel transaction failed due to merchant setup |
| AchCancellationFailedRefundGreaterThanTransactionAmount | When request to cancel transaction failed as refund amount is bigger than transaction amount |
| AchCancellationFailedTransactionAlreadyCancelled | When request to cancel transaction failed because transaction is already cancelled |
| AchFailedDueToNegativeData | When transaction failed due to negative user data |
| AchFailedIneligibleBankAccount | When transaction failed because bank account is not on ACH network |
| AchFailedPaymentDeclinedByUser | When transaction is declined by user |
| AchBankAccountVerificationPending | When the bank account's verification is still pending |
| AchWaitingFundSettlement | When transaction is waiting for funds to settle |
| AchSettledIntoWallet | When funds have settled into the Zūm Wallet |
| AchNotificationOfChange | Recorded in the transaction's history when a notification of change (NOC) is received; see the NACHA Notification of Change section below for the webhook this actually triggers |
| Event | Description |
|---|---|
| SameDayAchFailedGeneralError | When transaction has failed due to general error |
| SameDayAchFailedHighRiskOrPotentialFraud | When transaction is rejected as high-risk or potential fraud |
| SameDayAchFailedDueToNegativeData | When transaction failed due to negative user data |
| SameDayAchFailedDueToMerchantSetup | When request to cancel transaction failed due to merchant setup |
| SameDayAchFailedDueToProcessorTimeout | When transaction is not successfully processed due to processor timeout |
| SameDayAchFailedTransactionExpired | When transaction has expired |
| SameDayAchFailedPaymentDeclinedByUser | When transaction is declined by user |
| SameDayAchFailedTransactionNotAllowed | When transaction is not allowed by provider |
| SameDayAchFailedInvalidValueForField | When transaction failed due to invalid value for field |
| SameDayAchFailedAuthorizationRevoked | When transaction failed because authorization was revoked |
| SameDayAchFailedDuplicateTransaction | When transaction failed due to duplicated transaction |
| SameDayAchBankAccountVerificationFailed | When transaction failed because the bank account verification failed |
| SameDayAchFailedRejectedWithReason | When transaction is rejected for a reason |
| SameDayAchFailedReturnedOrClosedAccount | When transaction is returned due to a closed account or any other return reaso |
| SameDayAchTransactionAccepted | When transaction is accepted |
| SameDayAchTransactionResubmitted | When transaction is resubmitted for processing again |
| SameDayAchTransactionReturned | When transaction returned from bank and will be resubmitted in the next banking cycle. Note that this does not mean the transaction failed. |
| SameDayAchCancellationFailed | When request to cancel transaction failed |
| SameDayAchCancellationFailedDueToMerchantSetup | When request to cancel transaction failed due to merchant setup |
| SameDayAchCancellationFailedRefundGreaterThanTransactionAmount | When request to cancel transaction failed as refund amount is bigger than transaction amount |
| SameDayAchCancellationFailedTransactionAlreadyCancelled | When request to cancel transaction failed because transaction is already cancelled |
| SameDayAchDebitResponseReceived | When response is received for a debit transaction |
| SameDayAchCreditResponseReceived | When response is received for a credit transaction |
| SameDayAchFailedIneligibleBankAccount | When transaction failed because bank account is not on ACH network |
| SameDayAchBankAccountVerificationPending | When the bank account's verification is still pending |
| SameDayAchWaitingFundSettlement | When transaction is waiting for funds to settle |
| SameDayAchSettledIntoWallet | When funds have settled into the Zūm Wallet |
| SameDayAchNotificationOfChange | Recorded in the transaction's history when a notification of change (NOC) is received; see the NACHA Notification of Change section below for the webhook this actually triggers |
```
For example, `AchSimulate:Return:R01` simulates an `R01 - Insufficient Funds` return, which resolves to the `AchFailedRejectedWithReason` event with the code and description included in the transaction's event history.
```json
{
"ZumRailsType": "AccountPayable",
"TransactionMethod": "Ach",
"Amount": 123.45,
"Memo": "This transaction will be returned with code R01",
"Comment": "AchSimulate:Return:R01",
"UserId": "1d431e8b-...85452adb4eee",
"WalletId": "8ebd932b-...b92633e14297"
}
```
{% hint style="info" %}
* `` must be one of the codes listed in the table above (case-insensitive); an unrecognized code is rejected when the transaction is created.
* This directive is only available in the sandbox environment, for `TransactionMethod` of `Ach` or `SameDayAch`.
{% endhint %}
#### Simulating a Notification of Change (NOC)
To simulate a Notification of Change instead of a return, set the transaction's `Comment` field to:
```
AchSimulate:NOC_
```
Note the underscore (`NOC_`), not a colon, before the code. For example, `AchSimulate:NOC_C01` simulates a `C01 - Incorrect DFI Account Number` notification of change. This records an `AchNotificationOfChange` (`SameDayAchNotificationOfChange` on Same-Day ACH) entry in the transaction's history, and delivers a **PaymentInstrument** webhook (`Event: NotificationOfChange`) with the change code and correction details, as shown above.
```json
{
"ZumRailsType": "AccountPayable",
"TransactionMethod": "Ach",
"Amount": 123.45,
"Memo": "This transaction will receive a notification of change with code C01",
"Comment": "AchSimulate:NOC_C01",
"UserId": "1d431e8b-...85452adb4eee",
"WalletId": "8ebd932b-...b92633e14297"
}
```
{% hint style="info" %}
* `` must be one of the codes listed in the Notification of Change table above (case-insensitive); an unrecognized code is rejected when the transaction is created.
* This directive is only available in the sandbox environment, for `TransactionMethod` of `Ach` or `SameDayAch`.
* Unlike a return, a NOC does not fail the transaction — it keeps processing normally alongside the recorded notification.
* Watch for the webhook on the **payment instrument**, not the transaction — the `AchNotificationOfChange`/`SameDayAchNotificationOfChange` event name only appears in the transaction's history, it does not trigger its own transaction webhook.
{% endhint %}
## Additional features
* **Account Verification** - Zūm Rails provides Account Verification services, allowing connection to a user's financial institution to retrieve account and routing numbers. This information is useful for tasks such as money transfers and account setup. Zūm Rails ensures account validation according to NACHA WEB debit rules.
* #### Pending verification
Some bank accounts are verified via a $0.00 prenote sent to the receiving institution rather than an instant check. While this is outstanding, the account's verification status is `Pending`. Verification normally resolves within 3 banking days; if no correction is returned in that window, the account is automatically marked `Verified`.
Any funded transaction submitted against a `Pending` account will fail fast rather than wait — retry once the status changes.
* **Balance Checks** - Balance Checks allow retrieving the available balance for an end user’s financial accounts. This service provides balance details without retrieving transaction data.
* **Owner identification** - Owner Identification retrieves information about the owner of an account, such as their name, address, and contact information. This information is crucial for verifying the identity of an end user.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.zumrails.com/payments/bank-payments/ach.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.