Dwolla Developers Logo
Back
Concepts
  • Customers
    Customer Types
  • Features
  • Funding Sources
  • Transfers
  • Webhooks
API DocsOpen in new tabChangelog
Get API Keys
API DocsOpen in new tabChangelog
JavaScript
Get API Keys

Transfer Failures

There are several reasons bank transfers can fail, a few of which are outlined below. When a transfer fails it is usually a result of an ACH failure which is assigned an ACH return code after being rejected from the financial institution. A few common failure examples include:

  • Insufficient Funds (R01): Pending transfers can fail due to insufficient funds from the source bank account.
  • No Account/Unable to Locate Account (R03): The recipient of a transfer has closed their bank account or has incorrectly entered their bank account/routing number when attaching their funding source.
  • Customer Advises Not Authorized (R10): The owner of a bank account has told their bank that this transfer was unauthorized.

Retrieving the transfer

You can check the status of a transfer at any time by retrieving the transfer via the API. When a bank transfer is unable to be completed, its status will be updated to failed. The response from the API when retrieving the transfer should contain a "failure" link that your application will follow to retrieve the transfer failure reason in the next step.

Example failure link
json
"failure": {
    "href": "https://api-sandbox.dwolla.com/transfers/a1e58cd8-11ec-e811-8111-bec1f96924ed/failure",
    "type": "application/vnd.dwolla.v1.hal+json",
    "resource-type": "failure"
}

Retrieving the reason for a failed bank transfer

If your application is subscribed to webhooks, you’ll receive either the transfer_failed event if the transfer belongs to a Dwolla account or the customer_transfer_failed/customer_bank_transfer_failed(Verified Customer only) event if the transfer belongs to an API Customer. The event contains a links to the associated account as well as the transfer resource. When retrieving the failed bank transfer reason, the response will contain information on the ACH return code and description, as well as _links to the Funding Source and Customer that triggered the bank transfer failure.

Request and response (view schema in 'raw')
JavaScript
var transferUrl =
  "https://api-sandbox.dwolla.com/transfers/8997ebed-69be-e611-80ea-0aa34a9b2388";

appToken.get(`${transferUrl}/failure`).then((res) => res.body.code); // => 'R01'

What occurs in the Dwolla system when a bank transfer fails?

When a bank transfer failure occurs there is a subset of systematic actions Dwolla may take on the Customer and/or the funding source based on the ACH return code. It is recommended to have an active webhook subscription, which is used to listen for events relating to any Customer or funding source state change. Please refer to the table below to understand the systematic actions that Dwolla may take for Customer and funding source resources, as well as the events that are created.

Systematic actions taken against the Customer

Customer actionDescriptionWebhook EventNoneNo action taken against the Customer account as result of transfer failureN/ADeactivatedCustomer account has been deactivatedcustomer_deactivated

Systematic actions taken against the bank funding source

Funding Source actionDescriptionWebhook EventNoneNo action taken against the Customer bank funding sourceN/AUnverifiedA Customer's bank has been unverified, but not removedcustomer_funding_source_unverifiedRemovedA Customer's bank has been removedcustomer_funding_source_removed

Why does Dwolla automatically take these actions?

Being able to catch and take action errors can be beneficial on many levels. For instance, if your Customer initiates a transaction which fails with an R10 (Customer Advises Not Authorized) return code, Dwolla will automatically put the suspected Customer in a deactivated status, thereby not allowing them to initiate or receive more transfers. This gives you the ability investigate the Customer to determine if they are a valid party without worrying about them sending funds. Other return codes may only affect bank funding sources in which Dwolla may automatically unverify or remove a bank in response to various return codes.

List of possible return codes, descriptions, and actions

Below is a table of the most common return codes we see involved in transactions. For a full list of return codes, you can check out the ACH return code list on our blog.

Info
As a best practice, we recommend handling any systematic actions that trigger webhooks as a result of a transfer failure rather than relying on the specific actions as referenced below. We do not recommend building a workflow around each individual return code in the table below. This table solely meant to be a reference for you to be aware of actions Dwolla may take on common transfer failures.
Return CodeReason for Return & DescriptionReturn TimeframeDeactivated or SuspendedFunding Source RemovedFunding Source UnverifiedR01Insufficient Funds
Available balance is not sufficient to cover the dollar value of the debit entry.2 banking daysNoNoNoR02Bank Account Closed
Previously active account has been closed.2 banking daysNoYesYesR03No Account/Unable to Locate Account
Account number structure is valid, but doesn’t match individual identified in entry or is not an open account.2 banking daysNoYesYesR04Invalid Bank Account Number Structure
Account number structure is not valid.2 banking daysNoYesYesR05Unauthorized debit to consumer account
A debit entry was transmitted to a consumer account that was not authorized by the Receiver. Written Statement is required.60 calendar daysYesYesYesR07Authorization Revoked by Customer
Consumer who previously authorized entries has revoked authorization with the Originator. Written Statement is required.60 calendar daysYesYesYesR08Payment Stopped
The Receiver has requested the stop payment of a specific ACH debit entry.2 banking daysNoYesYesR09Uncollected Funds
Sufficient balance exists, but value of uncollected items brings available balance below amount of debit entry.2 banking daysNoNoNoR10Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account
Receiver has no relationship with the Originator or has not authorized the Originator to debit the account. Written Statement is required.60 calendar daysYesYesYesR11Customer Advises Entry Not in Accordance with the Terms of the Authorization.
The debit entry was inaccurate or improperly initiated. Other reasons include source document was ineligible, notice was not provided to the receive or amount was inaccurately obtained. Written statement is required.60 calendar daysYesYesYesR16Bank Account Frozen
Funds unavailable due to action by the RDFI or legal action.2 banking daysYesYesYesR20Non-Transaction Account
RDFI policies/regulations restrict activity to account.2 banking daysNoNoNoR29Corporate Customer Advises Not Authorized
Receiver has notified RDFI that corporate debit entry transmitted to a corporate account is not authorized.2 banking daysYesYesYes

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys
2020 All Rights Reserved

Dwolla

  • About
  • Blog
  • Pricing
  • Contact Sales
  • Terms of Service
  • Privacy Policy
Financial institutions play an important role in our network.

Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.