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.

There are multiple Customer types within the Dwolla API. Use our concept article for a more in-depth overview of each Customer type and its capabilities.

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.

Here's how to simulate the different statuses and verification links for business Verified Customers in Sandbox:

retry status:

• For the business - Supply retry in the businessName parameter. This action will return a retry-verification link in the Customer resource.

• For both the Controller and business - Supply retry in the controller firstName parameter. This action will return both a retry-verification link and a retry-with-full-ssn link in the Customer resource.

document status:

• For the controller - Supply document in the controller firstName parameter. This action will return a verify-with-document linkin the Customer resource.

• For the business - Supply document in the businessName parameter. This action will return a verify-business-with-document link in the Customer resource.

• For both the Controller and the business - Submit document in both the controller firstName and the businessName parameters. This action will return a verify-controller-and-business-with-document link in the Customer resource.

suspended:

• Supply suspended in the controller firstName parameter to create a new Verified Customer with that status.

For beneficial owners: To simulate different verification statuses for Beneficial Owners, submit either incomplete or document in the beneficial owner firstName parameter.

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.

More information on KBA status for Personal Verified Customers and the related endpoints.

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.

Sample document approved image #

Sample document failed image #

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.

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

The following error codes can be triggered:

• ControllerNonResidential
• POBoxNotAllowed
• AddressNotAssociatedWithBusiness
• EINDocumentRequired

To simulate one of these error codes:

1. Create a business Verified Customer in the Sandbox.
2. Make a POST request to the /sandbox-simulations endpoint with a request body like the following:

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": "customer-verification",
    "_links": {
        "customer": {
            "href": "https://api-sandbox.dwolla.com/customers/{customer-id}"
        }
    },
    "errorCode": "AddressNotAssociatedWithBusiness"
}

Replace {customer-id} with the ID of your Sandbox customer, and set errorCode to one of the supported values (e.g., ControllerNonResidential, POBoxNotAllowed, AddressNotAssociatedWithBusiness, or EINDocumentRequired).

After making this request, retrieve the Customer resource using the API. The specified error code will appear in the _embedded.errors array of the response, allowing you to test your application's handling of these verification directives.