Testing in the Sandbox - Dwolla Developer Portal

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Overview

The Sandbox environment is a complete replica of the Dwolla production environment, supporting all of the same API endpoints. Applications should be tested against the Sandbox environment before being used in production.

Differences from production environment

Real financial data should never be used in the Sandbox.

Transfer behavior in the Sandbox

Unlike transfers that are sourced from a Dwolla balance, which are processed instantaneously, bank-sourced transfers exist in the pending state for a few business days until they are processed, failed, or cancelled.The Sandbox environment does not replicate any ACH processes, so a pending transfer will not clear or fail automatically after a few business days as it would in production. It will simply remain in the pending state indefinitely. Reference the testing transfers section for more information on how to simulate bank transfer processing in the Sandbox environment.

Sandbox account setup

To set up your Sandbox account, all you will need is a valid email address. Once you agree to the Dwolla Developer Terms and Service, you will receive an email asking to verify your email address.

Failure to verify your email will result in a 401 HTTP status for all API calls with an error code of InvalidAccountStatus.

After email verification, your Sandbox account will be created and you’ll be redirected to our Sandbox Dashboard at https://dashboard-sandbox.dwolla.com/. Here you can view your API key and secret and generate an OAuth access token. Dwolla will also create an application for your account, associate a funding source named ‘Superhero Savings Bank’, and add $5000 to the account balance for testing.

Testing Customers

Manage Customers in the Dashboard

The Sandbox Dashboard allows you to manage Customers, as well as transfers associated with the Customers that belong to your Sandbox account. Once your application has created its Customers, you can access the Sandbox Dashboard to validate that the request was recorded properly in our test environment.

Simulate identity verification statuses

There are various reasons a Verified Customer may have a status other than verified after the initial Customer creation. You will want your app to be prepared to handle these alternative statuses. In production, Dwolla will place the Verified Customer in either the retry, kba, document, verified, or suspended state of verification after an initial identity verification check. For personal Verified Customers: Reference the guide on customer verification for more information on handling identity verification for Verified Customers. To simulate the various statuses in the Sandbox, supply either verified, retry, kba, document, or suspended in the firstName parameter in order to create a new Verified Customer with that status. For business Verified Customers: Reference the guide on customer verification that goes over information on properly verifying a business’s Controller, the business, and associated Beneficial Owners.

Simulate KBA verified and failed events

If a Personal Verified Customer isn’t systematically identity-verified after their second attempt to retry their information, the Customer may be placed in a kba status and will be required to successfully answer at least three out of four knowledge based authentication (KBA) questions in order to pass verification.

To simulate the customer_kba_verification_passed event as the result of KBA success in Sandbox, answer all four questions with either “None of the above” or “I have never been associated with this vehicle”. As a result, the Customer will be placed in a verified status and the customer_verified event is triggered. To simulate the customer_kba_verification_failed event as the result of KBA failure in Sandbox, answer the questions with any answer choices other than “None of the above” or “I have never been associated with this vehicle”. As a result, the Customer will be placed in a document status and the customer_verification_document_needed event is triggered.

Simulate document upload approved and failed events

If a Verified Customer isn’t systematically identity-verified, the Customer may be placed in a document status and will require an identifying document to be uploaded and reviewed. Reference either the personal customer verification or business customer verification guide for acceptable forms of identifying documents for Verified Customers. Since the document review process requires interaction from Dwolla, sample test documents can be uploaded in the Sandbox environment to simulate the customer_verification_document_approved and customer_verification_document_failed events.

Simulate verification directives

You can test how your application handles specific embedded error codes (Verification Directives) in the Sandbox environment using the /sandbox-simulations endpoint. This allows you to simulate the Dwolla API returning a particular verification directive for a business Verified Customer.

This simulation can only be performed for customers that are in either retry or document status.

Learn more about the structure and meaning of these directives in the Understanding Verification Directives section.

Testing Funding Sources

Test bank account numbers

Dwolla requires a valid U.S. routing number and a random account number between 4-17 digits to add a bank account. For testing purposes, you can use the routing number 222222226 or refer to the list of routing numbers from the Federal Reserve Bank Services website.

Test micro-deposit verification

If your application leverages the micro-deposit method of bank verification, Dwolla will transfer two deposits of less than $0.10 to your customer’s linked bank or credit union account after calling the API to initiate micro-deposits. Since the Sandbox environment doesn’t replicate any bank transfer processes, any two amounts below$0.10 will allow you to verify the funding source immediately. In Production, when the micro-deposits have finished processing, you will receive a customer_microdeposits_completed event.

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.