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

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.

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

Example VANs transfer processing

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

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.

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

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

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