• Getting Started
    Generate an OAuth Access Token
    Send Money to Users
    Receive Money from Users
    Transfer Money Between Users
    Transfer Money Me-to-Me
    Building With Drop-in Components
  • Customers
    Create a Business Verified Customer
    Create a Personal Verified Customer
  • Funding Sources
    Add a Debit Card Using Dwolla-cards.js
    Add a Bank Using Dwolla.js
    Add a Bank Using Dwolla.js + IAV
    Verify Bank with Micro-deposits
    Add Bank via Dwolla + Plaid Integration
  • Webhooks
    Working with Webhooks

Testing Transfers #

The Sandbox environment does not replicate any bank transfer processes, so a pending transfer will not clear or fail automatically after a few business days as it would in production. The transfer will simply remain in the pending state indefinitely.

Simulate bank transfer processing #

There are two options available for processing or failing bank transfers in the Sandbox environment.

  • Option 1: your application will call the "sandbox-simulations" endpoint (referenced below) which will process or fail the last 500 bank transfers that occurred on the authorized application or Sandbox account.
  • Option 2: you'll use the "Process bank transfers button" in the Sandbox Dashboard, which will process or fail the last 500 bank transfers that occurred on your Sandbox account or any API Customers you manage.
Sandbox simulations request and response
bash
POST https://api-sandbox.dwolla.com/sandbox-simulations
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer {Your access token}

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/sandbox-simulations",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "sandbox-simulation"
    }
  },
  "total": 8
}

Process bank transfers button #

A “Process bank transfers” button is available in the Sandbox Dwolla Dashboard and Admin. This button performs the same function as the "sandbox-simulations" endpoint (mentioned above) and allows you to simulate bank transfer processing in the Sandbox. Once the button is clicked, Dwolla will process or fail (see below for how-to trigger ACH failures) the last 500 bank transfers that occurred on your Sandbox account or the API Customer accounts you manage.

process bank transfers

Test RTP transfers #

To create a Real-time payment (RTP) transfer, you need to attach a funding-source that is RTP enabled to your Customer. The Clearing House maintains lists of all financial institutions in the RTP® Network and all RTP-enabled Routing/Transit Numbers. Use one of the routing numbers from the list to create an RTP-enabled funding-source in your Sandbox account. The account number can be any random number of 4-17 digits.

Use our concept article for a more in-depth overview of Dwolla’s Real-Time Payments product (RTP).

Test Virtual Account Number transfers #

External transfers can be simulated in the Dwolla Sandbox by using the sandbox-simulations endpoint with a request body that includes: a type field set to virtual and a transfers field with a list of transfers to process (see example below). Up to 10 transfers at a time can be included in one call to the sandbox simulations endpoint. Transfers will be created in an initial status of pending and will be updated to processed based on the times outlined below. A failed status can occur when the virtual account number (VAN) has been removed, the Customer has been deactivated or suspended, or when an ACH return code is assigned. Reference the Testing Virtual Account Transfer Failures section for more information on how to replicate a failed status.

Use our concept article for a more in-depth overview of Virtual Account Numbers (VANs) with Dwolla.

Pending transfers will be processed automatically during the following times (all in Central Time):

  • 2 a.m.
  • 5 a.m.
  • 8 a.m.
  • 11 a.m.
  • 1:15 p.m.
  • 5:45 p.m.
  • 8 p.m.
Optional fields and default values for VAN transfers
Optional FieldDefault Value
companyEntryDescriptionNote: The default value is an empty string "" . To simulate how a reversal transaction would look, set companyEntryDescription to "REVERSAL".
routingNumber"222222226"
addenda"addenda"
beneficiaryName"Fake name"
companyDiscretionaryData"Fake discretionary data"
companyId"random integer value"
companyName"Fake company name"
Example VANs transfer processing
bash
POST https://api-sandbox.dwolla.com/sandbox-simulations
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer {Your access token}

{
    "type": "virtual",
    "transfers": [
        {
            "_link": {
                "destination": {
                    "href": "https://api-sandbox.dwolla.com/funding-sources/5880e310-675a-4ce3-87d9-a475cc565e09"
                }
            },
            "amount": {
                "currency": "USD",
                "value": "1.11"
            },
            "achDetails": {
                "companyEntryDescription": "AUTOENROLL",
                "companyName": "Test Business Name",
                "companyDiscretionaryData": "Test discretionary data",
                "beneficiaryName": "Test Name",
                "routingNumber": "012256789",
                "addenda": "addenda example",
                "companyId": "0012422"
            }
        }
    ]
}

...

HTTP/1.1 202 Accepted

Test bank transfer failures #

Transfers to or from a bank account can fail for a number of reasons (e.g. insufficient funds, invalid account number, etc.). When a bank transfer fails, the associated financial institution that rejected the transaction assigns an ACH return code and a transfer failure event is then triggered in Dwolla. Dwolla allows you to trigger various bank transfer failures by specifying an “R” code in the funding source name parameter when creating or updating a funding source for a Dwolla Account or API Customer. When a transfer is initiated using a funding source that has an “R” code assigned to its name, a transfer failure event will trigger and the status will update to failed when you simulate bank transfer processing (as mentioned above).

Dwolla allows you to pass in a few different sentinel values that are used to test different bank transfer failure scenarios. The list of available sentinel values cover the most common uses cases where ACH return codes can be triggered in production.

List of codes for testing bank transfer failures
Return codeDescription
R01Insufficient Funds: This value is used to simulate funds failing from the source bank account (ACH debit).
R03No Account/Unable to Locate Account: This value is primarily used to simulate funds failing to the destination bank account (ACH credit). The funding source will be automatically removed from Dwolla when this return code is triggered.
R01-lateThis value is used to simulate funds failing from the source bank account post-settlement. Note: You must click “Process bank transfers” twice in order to test this scenario.
R03-lateThis value is primarily used to simulate funds failing to the destination bank post-settlement. The funding source will be automatically removed from Dwolla when this return code is triggered. Note: You must click “Process bank transfers” twice in order to test this scenario.

Our concept article has more information on bank transfer failures, and a list of common return codes and actions.
Example of using a sentinel value for testing bank transfer failures

This example assumes that a funding source has already been attached to an account. Once the funding source name has been updated to reflect the ACH failure scenario you want to test, then you can initiate a transfer to or from that funding source via the API.

JavaScript
var fundingSourceUrl =
  "https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c";
var requestBody = {
  name: "R03",
};

dwolla.post(fundingSourceUrl, requestBody).then((res) => res.body.name); // => "R03"

Test Virtual Account Number transfer failures #

Similar to testing ACH bank transfer failures, you can test a transfer failure with a virtual account number by specifying an "R" code in the "name" parameter when creating a VAN (e.g. “R08 Failure Test VAN”). The return code must be at the beginning of the VAN funding source’s name. Note that it is not case sensitive.

List of codes for testing VAN transfer failures
CodeDescriptionWhen is the failure triggered?
R01Insufficient Funds: This value is used to simulate funds failing from the source bank account (ACH debit).During processing of pending transactions.
R02No Account/Unable to Locate Account: This value is primarily used to simulate funds failing to the destination bank account (credit). The funding source will be automatically removed from Dwolla when this return code is triggered.During processing of pending transactions.
R08Payment Stopped: The person who owns the account has placed a stop payment with their bank.“Immediately” triggered upon transfer creation by funding source naming convention.
R10Customer Advises Unauthorized, Improper, Ineligible, or Part of an Incomplete Transaction: The person who owns the bank account has told their bank account that the transaction was unauthorized.“Immediately” triggered upon transfer creation by funding source naming convention.

Test Push-to-debit transfer failures #

Push-to-debit transfers can fail for a number of reasons (e.g. LostOrStolenCard, SuspectedFraud, etc.). When a transfer is created to a debit card that is ineligible to receive funds, a transfer failed event is triggered in Dwolla, and the transfer's status is updated from pending to failed in a matter of seconds without having to simulate bank transfer processing.

You can trigger various push-to-debit transfer failure scenarios by specifying a specific amount when creating a transfer to a debit card.

List of amounts for testing Push-to-debit transfer failures
AmountDescription
$0.11InvalidInstrument
$0.21ExceedsIssuerAmountLimit
$0.31ExceedsIssuerCountLimit
$0.41CallIssuer
$0.51Unknown
$0.61LostOrStolenCard
$0.71SuspectedFraud
$0.81ComplianceViolation

Use our concept article for more information on Push to Debit transfer failures, and a list of common failure reasons.

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys
2022 All Rights Reserved
Financial institutions play an important role in our network.

All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.