Transfer Failures - Dwolla Developer Portal

Overview

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

"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 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

HTTP

retrieve_transfer_failure.rb

retrieve_transfer_failure.php

retrieve_transfer_failure.py

retrieveTransferFailure.js

GET https://api-sandbox.dwolla.com/transfers/8997ebed-69be-e611-80ea-0aa34a9b2388/failure
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
    "_links": {
        "self": {
            "href": "https://api.dwolla.com/transfers/8997ebed-69be-e611-80ea-0aa34a9b2388/failure",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "failure"
        },
        "failed-funding-source": {
            "href": "https://api.dwolla.com/funding-sources/285ea6f4-c45d-4e15-ad33-21f51461f437",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "customer": {
            "href": "https://api.dwolla.com/customers/be2d2322-fdee-4361-8722-4289f5601604",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        }
    },
    "code": "R03",
    "description": "No Account/Unable to Locate Account",
    "explanation": "The account number does not correspond to the individual identified in the entry or a valid account."
}

transfer_url = 'https://api-sandbox.dwolla.com/transfers/8997ebed-69be-e611-80ea-0aa34a9b2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
failure = app_token.get "#{transfer_url}/failure"
failure.code # => "R01"

<?php
$transfer = '8997ebed-69be-e611-80ea-0aa34a9b2388';

$TransfersApi = new DwollaSwagger\TransfersApi($apiClient);

$failureReason = $TransfersApi->failureById($transfer);
print($failureReason->code); # => "R01"
?>

transfer_url = 'https://api-sandbox.dwolla.com/transfers/8997ebed-69be-e611-80ea-0aa34a9b2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
failure = app_token.get('%s/failure' % transfer_url)
failure.body['code'] # => 'R01'

var transferUrl =
  "https://api-sandbox.dwolla.com/transfers/8997ebed-69be-e611-80ea-0aa34a9b2388";

dwolla.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

Systematic actions taken against the bank funding source

Why does Dwolla automatically take these actions?

Being able to catch and take action on 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 suspended status, thereby not allowing them to initiate or receive more transfers. This gives you the ability to investigate the Customer to determine if they are a valid party without worrying about them sending funds. Other return codes may result in the Customer being deactivated, or 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 are tables of the most common return codes we see involved in transactions, organized by category. For a full list of return codes, you can check out the ACH return code list on our blog.

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 tables below. These tables are solely meant to be a reference for you to be aware of actions Dwolla may take on common transfer failures.

Administrative Returns

Administrative returns occur when there’s an issue with the account itself—such as insufficient funds, a closed account, or invalid account information. These are typically returned within 2 banking days and generally don’t indicate fraudulent activity.

Unauthorized Returns

Unauthorized returns occur when the account holder claims they did not authorize the transaction. These are more serious and can be returned up to 60 calendar days after the settlement date. Due to the nature of these returns, Dwolla takes protective actions on the Customer account.

Unauthorized returns may indicate potential fraud or disputes. Dwolla automatically suspends or deactivates the Customer to protect against further unauthorized activity.

General Returns

These returns are initiated by the originating or receiving financial institution or relate to specific transaction types like source documents or permissible returns. Return time frames vary.