Language

Introduction

Welcome to the Dwolla API documentation. This API will give you the ability to connect your software to banking infrastructure to move money, store funds, validate customer identities, and verify bank accounts.

Making requests

All requests should supply the Accept: application/vnd.dwolla.v1.hal+json header. POST requests must specify the Content-Type: application/vnd.dwolla.v1.hal+json header. Request and response bodies are JSON encoded.

Requests must be made over HTTPS. Any non-secure requests are met with a redirect (HTTP 302) to the HTTPS equivalent URI.

  1. Dwolla has discontinued support for TLS 1.0 and TLS 1.1 across the platform as of June 30, 2018. This impacts a small number of integrations; however, to avoid service disruption, you will need to ensure that you’re connecting to the Dwolla API using TLS v1.2 or higher.

POST https://api.dwolla.com/customers
Content-Type: application/json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer myOAuthAccessToken123

{
  "foo": "bar"
}

... or ...

GET https://api.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers

Authorization

All requests require either an OAuth access token or a client_id and client_secret. OAuth access tokens are passed via the Authorization HTTP header:

Authorization: Bearer {access_token_here}

Requests that require a client_id and client_secret can be sent using the application/x-www-form-urlencoded Content-Type or via a JSON body with the application/json Content-Type.

API Host

Production: https://api.dwolla.com

Sandbox: https://api-sandbox.dwolla.com

Idempotency key

To prevent an operation from being performed more than once, Dwolla supports passing in an Idempotency-Key header with a unique key as the value. Multiple POSTs with the same idempotency key won’t result in multiple resources being created.

For example, if a request to initiate a transfer fails due to a network connection issue, you can reattempt the request with the same idempotency key to guarantee that only a single transfer is created.

If you reattempt a POST request with the same value for the Idempotency-Key, you will receive the original response. It is recommended to use a random value for the idempotency key, like a UUID (i.e. - Idempotency-Key: d2adcbab-4e4e-430b-9181-ac9346be723a). Idempotency keys are intended to prevent conflicts over a short period of time, therefore keys will expire after 24 hours. If the Dwolla server is still processing the original POST, you will receive a 409 Conflict error response on the subsequent request.

Example transfer using an Idempotency Key

curl -X POST -H "Content-Type: application/vnd.dwolla.v1.hal+json" -H "Accept: application/vnd.dwolla.v1.hal+json" -H "Authorization: Bearer asdfwXTdDQFimVQOMdn9bOGHJh8KrqnFi34sugYqgrULRCb" -H "Idempotency-Key: d2adcbab-4e4e-430b-9181-ac9346be723a" -d '{
    "_links": {
        "destination": {
            "href": "https://api-sandbox.dwolla.com/customers/d795f696-2cac-4662-8f16-95f1db9bddd8"
        },
        "source": {
            "href": "http://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "1337.00"
    }
}' "https://api-sandbox.dwolla.com/transfers" -v

Errors

Error responses use HTTP status codes to indicate the type of error. The JSON response body will contain a top-level error code and a message with a detailed description of the error. Errors will contain their own media type and will closely align with this spec.

Example HTTP 401 error

{
  "code": "InvalidAccessToken",
  "message": "Invalid access token."
}

Common errors

The following errors are common across all API endpoints.

HTTP Status Error Code Description
400 BadRequest The request body contains bad syntax or is incomplete.
400 ValidationError Validation error(s) present. See embedded errors list for more details. (See below)
401 InvalidCredentials Missing or invalid Authorization header.
401 InvalidAccessToken Invalid access token.
401 ExpiredAccessToken Generate a new access token using a valid refresh token.
401 InvalidAccountStatus Invalid access token account status.
401 InvalidApplicationStatus Invalid application status.
401 InvalidScopes Missing or invalid scopes for requested endpoint.
403 Forbidden The supplied credentials are not authorized for this resource.
403 InvalidResourceState Resource cannot be modified.
404 NotFound The requested resource was not found.
405 MethodNotAllowed (varies)
406 InvalidVersion Missing or invalid API version.
500 ServerError A server error occurred. Error ID: 63e92a2a-fb48-4a23-ab4c-24a6764f1593.
500 RequestTimeout The request timed out.

Validation errors

Responses with a top-level error code of ValidationError are returned when it’s possible to correct a specific problem with your request. The response will include a message: “Validation error(s) present. See embedded errors list for more details.” At least one, but possibly more, detailed error will be present in the list of embedded errors. Multiple errors are represented in a collection of embedded error objects.

_embedded JSON object

Parameter Description
errors An array of JSON object(s) that contain a code, message, and path.

The path field is a JSON pointer to the specific field in the request that has a problem. The message is a human readable description of the problem. The code is a detailed error code that can have one of the following values:

  • Required
  • Invalid - not a valid value for this field
  • InvalidFormat - chars in an amount field, for instance
  • Duplicate - “A customer with the specified email already exists.”
  • ReadOnly - this field is not allowed to be modified
  • NotAllowed - value, while valid/exists, is not allowed to be used
  • Restricted - account or customer restricted from this activity
  • InsufficientFunds - used on source or destination fields of transfer endpoint
  • RequiresFundingSource - used on destination field of transfer endpoint to indicate customer needs a bank
  • FileTooLarge - used on document upload

Example HTTP 400 validation error

{
    "code": "ValidationError",
    "message": "Validation error(s) present. See embedded errors list for more details.",
    "_embedded": {
        "errors": [
            {
                "code": "Required",
                "message": "FirstName required.",
                "path": "/firstName",
                "_links": {}
            }
        ]
    }
}

Relationships and available actions for a resource are represented with links. All resources have a _links attribute. At a minimum, all resources will have a self link which indicates the URL of the resource itself.

Some links, such as funding-sources, give you a URL which you can follow to access related resources. For example, the customer resource has a funding-sources link which, when followed, will list the customer’s available funding sources.

Responses which contain a collection of resources have pagination links, first, next, last, and prev.

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1"
    },
    "funding-sources": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1/funding-sources"
    },
    "transfers": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1/transfers"
    },
    "retry-verification": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1"
    }
  },
  "id": "132681FA-1B4D-4181-8FF2-619CA46235B1",
  "firstName": "Jane",
  "lastName": "doe",
  "email": "jdoe@nomail.com",
  "type": "personal",
  "status": "retry",
  "created": "2015-09-29T19:47:28.920Z"
}

Tools

The following section will outline development tools you can take advantage of to assist in your integration with the Dwolla API. The available tools can help to improve your testing and development workflow, as well as aid in solving a difficult problem (e.g. UI generation) when integrating Dwolla into your application.

Dwolla Hal-Forms

Dwolla HAL-Forms is an extension of the HAL spec and was created to describe how Dwolla represents forms in the API. The extension starts with the media type. The media type should be used as a profile link as part of the Accept header of the request in conjunction with the Dwolla HAL style media type. By including these two media-type identifiers in the Accept header, the API knows that you’re looking for a form for the given resource.

Example Accept header value

application/vnd.dwolla.v1.hal+json; profile="https://github.com/dwolla/hal-forms"

The primary benefit is the ability to dynamically generate your UI based on the state of a particular resource. Your application can easily transition state without knowing Dwolla’s business rules and what information needs to included in the actual request to transition state. When an "edit-form" link relation is returned on the resource, then your application can follow the link by making a GET request to that resource, including the header shown above. The response will include a simple JSON response body that contains information on the HTTP method, message content-type, and the request parameters used when sending the request to the Dwolla API. Note: Currently, forms are only returned for creating & editing customers, but we’re looking forward to expanding them across our existing and future endpoints.

Reference the spec for more information on the properties that can be returned in the Dwolla HAL-FORMS response. Or read a blog post from one of our developers on building out this functionality.


SDK Support

The Dwolla API has officially maintained software packages to make it easier for developers to get started with making requests. This section is here to provide basic instructions on how to install these packages and get up and running with them. We recommend you use a POSIX-standardized shell on your development machine, and assume that you are already familiar and set-up with any tools required for your specific technical ecosystem.

Officially maintained SDKs are available for Ruby, Node.js, Python, and C#.

The PHP SDKs is autogenerated by swagger-codegen and are versioned in accordance with our API schema. Each endpoint grouping is assigned a class and then an operation which you can use to make a request. You can choose which environment to target (e.g production vs sandbox) by providing the SDK a different API host value. These libraries are not actively maintained, therefore we encourage community contribution.

Base URLs

Production Sandbox
https://api.dwolla.com https://api-sandbox.dwolla.com

Ruby

dwolla_v2 is available on RubyGems with source code available on our GitHub page. More information is available on the project’s README.

Installation

gem install dwolla_v2

Quickstart

Let’s list some Customer objects:

require 'dwolla_v2'

# Navigate to https://www.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
app_key = "..."
app_secret = "..."
$dwolla = DwollaV2::Client.new(key: app_key, secret: app_secret) do |config|
  config.environment = :sandbox # optional - defaults to production
end

# create an application token
app_token = $dwolla.auths.client

customers = app_token.get "customers", limit: 10

Python

dwollav2 is available on PyPi with source code available on our GitHub page. More information is available on the project’s README.

Installation

pip install dwollav2

Quickstart

Let’s list some Customer objects:

import dwollav2

# Navigate to https://www.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
app_key = '...'
app_secret = '...'
client = dwollav2.Client(key = app_key,
                         secret = app_secret,
                         environment = 'sandbox') # optional - defaults to production

app_token = client.Auth.client()

customers = app_token.get('customers', {'limit': 10})

PHP

dwolla-swagger-php is available on Packagist with source code available on our GitHub page. More information is available on the project’s README.

Installation

composer require dwolla/dwollaswagger
composer install

Quickstart

Let’s list some Customer objects:

<?php
require('../path/to/vendor/autoload.php');

DwollaSwagger\Configuration::$access_token = 'a token';
$apiClient = new DwollaSwagger\ApiClient("https://api-sandbox.dwolla.com/");

$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$myCusties = $customersApi->_list(10);

?>

C#

Dwolla.Client is available on Nuget with source code available on our GitHub page. More information is available on the project’s README.

Installation

Install-Package Dwolla.Client

Quickstart

Let’s list some Customer objects:

var client = DwollaClient.Create(isSandbox: true);

var tokenRes = await client.PostAuthAsync<AppTokenRequest, TokenResponse>(
    new Uri($"{client.AuthBaseAddress}/token"),
    new AppTokenRequest {Key = "...", Secret = "..."});

var headers = new Headers {{"Authorization", $"Bearer {tokenRes.Content.Token}"}};
var rootRes = (await client.GetAsync<RootResponse>(new Uri(client.ApiBaseAddress), headers)).Content;

var customers = await client.GetAsync<GetCustomersResponse>(rootRes.Links["customers"].Href, headers);

Java

dwolla-swagger-java is not actively maintained by Dwolla, however source code is available on our GitHub page and community contribution is encouraged. More information is available on the project’s README.

Installation

You will be required to install from source, please have Git and mvn installed and in your path, then:

git clone https://github.com/Dwolla/dwolla-swagger-java
cd dwolla-swagger-java
mvn install package

Quickstart

Let’s list some Customer objects:

import io.swagger.client.ApiClient;
import io.swagger.client.api.*;
import io.swagger.client.model.*;

ApiClient a = new ApiClient();
a.setBasePath("https://api-sandbox.dwolla.com");
a.setAccessToken("a token");

CustomersApi c = new CustomersApi(a);
CustomerListResponse custies = c.list(10);

JavaScript

dwolla-v2 is available on NPM with source code available on our GitHub page. More information is available on the project’s README.

Installation

npm install dwolla-v2

Quickstart

Let’s fetch a page of customers:

const dwolla = require('dwolla-v2');

// Navigate to https://www.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
const appKey = '...';
const appSecret = '...';
const client = new dwolla.Client({
  key: appKey,
  secret: appSecret,
  environment: 'sandbox' // optional - defaults to production
});

// create a token
client.auth.client()
  .then(appToken => appToken.get('customers', { limit: 10 }))
  .then(res => console.log(res.body));

Authorization

Dwolla utilizes the OAuth 2 protocol to facilitate authorization. OAuth is an authorization framework that enables a third-party application to obtain access to protected resources (Transfers, Funding Sources, Customers etc.) in the Dwolla API. Access to the Dwolla API can be granted to an application either on behalf of a user or on behalf of the application itself. This section covers application auth which is meant for server-to-server applications using the Dwolla API.

Creating an application

Before you can get started with making OAuth requests, you’ll need to first register an application with Dwolla by logging in and navigating to the applications page. Once an application is registered you will obtain your client_id and client_secret (aka App Key and Secret), which will be used to identify your application when calling the Dwolla API. The Sandbox environment provides you with a created application once you have signed up for an account. Learn more in our getting started guide. Remember: Your client_secret should be kept a secret! Be sure to store your client credentials securely.

Token lifetime

Access tokens are short lived: 1 hour. To refresh authorization on an application access token, your application will simply exchange its client credentials for a new app access token. Any access tokens that have been previously initialized will not be invalidated with the creation of a new one; they will simply expire within an hour of the time of their creation.

Application authorization

The client credentials flow is the simplest OAuth 2 grant, with a server-to-server exchange of your application’s client_id, client_secret for an OAuth application access token. In order to execute this flow, your application will send a POST requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string client_id:client_secret.

Authorization: Basic Base64(client_id:client_secret)

HTTP request

Production: POST https://accounts.dwolla.com/token

Sandbox: POST https://accounts-sandbox.dwolla.com/token

Including the Content-Type: application/x-www-form-urlencoded header, the request is sent to the token endpoint with grant_type=client_credentials in the body of the request:

Request parameters

Parameter Required Type Description
client_id yes string Application key. Navigate to https://www.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key.
client_secret yes string Application secret. Navigate to https://www.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application secret.
grant_type yes string This must be set to client_credentials.

Response parameters

Parameter Description
access_token A new access token that is used to authenticate against resources that belong to the app itself.
expires_in The lifetime of the access token, in seconds. Default is 3600.
token_type Always bearer.

Request

POST https://accounts-sandbox.dwolla.com/token
Authorization: Basic YkVEMGJMaEFhb0pDamplbmFPVjNwMDZSeE9Eb2pyOUNFUzN1dldXcXUyeE9RYk9GeUE6WEZ0bmJIbXR3dXEwNVI1Yk91WmVOWHlqcW9RelNSc21zUU5qelFOZUFZUlRIbmhHRGw=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
# This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
app_token = client.Auth.client()
// Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-node
// This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
client.auth.client()
  .then(function(appToken) {
    return appToken.get('webhook-subscriptions');
  })
  .then(function(res) {
    console.log(JSON.stringify(res.body));
  });
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
# This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
app_token = $dwolla.auths.client
# => #<DwollaV2::Token client=#<DwollaV2::Client id="..." secret="..." environment=:sandbox> access_token="..." expires_in=3600 scope="...">
/**
 *  No support for this language yet. We recommend using an external REST client for making OAuth requests.
 **/

Successful response

{
  "access_token": "SF8Vxx6H644lekdVKAAHFnqRCFy8WGqltzitpii6w2MVaZp1Nw",
  "token_type": "bearer",
  "expires_in": 3600
}

Root

The “root” serves as an entry point to the API, providing your application with the ability to fetch and discover resources available based on the OAuth access_token provided in the request. If an application access token is provided in the request, the API will return links to resources that belong to the Dwolla application (i.e. “events” and “webhook-subscriptions”).

HTTP request

GET https://api.dwolla.com/

Request and response

GET https://api-sandbox.dwolla.com/
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers"
    }
  }
}
root = app_token.get "/"
root._links.account.href # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
<?php
$rootApi = new DwollaSwagger\RootApi($apiClient);

$root = $rootApi->root();
$accountUrl = $root->_links["account"]->href; # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
root = app_token.get('/')
root.body['_links']['account']['href'] # => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'
appToken
  .get('/')
  .then(res => res.body._links.account.href); // => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'

Accounts

An Account represents your Dwolla Master Account that was established on dwolla.com.

Migrating Transfer user Accounts to Dwolla API Customers

Dwolla offers a seamless process for migrating existing Transfer user Accounts managed via OAuth on your platform to Dwolla API Customers. The user Account will maintain existing functionality on dwolla.com and will act as a separate Dwolla API Customer upon completion of the migration. To learn more about upgrading to the Dwolla API, please contact Sales.

Link Description
self URL of the Account resource
receive Follow the link to create a transfer to this Account.
funding-sources GET this link to list the Account’s funding sources.
transfers GET this link to list the Account’s transfers
customers (optional) If this link exists, this account is authorized to create and manage Dwolla API Customers.
send Follow the link to create a transfer to this Account.
{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "receive": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers"
    },
    "send": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    }
  },
  "id": "ca32853c-48fa-40be-ae75-77b37504581b",
  "name": "Jane Doe"
}

Retrieve account details

This section shows you how to retrieve basic account information belonging to the authorized user Account.

HTTP request

GET https://api.dwolla.com/accounts/{id}

Request parameters

Parameter Required Type Description
id yes string Account unique identifier.

HTTP status and error codes

HTTP Status Message
403 Not authorized to get an Account by id.
404 Account not found.

Request and response

GET https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "receive": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers"
    },
    "send": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    }
  },
  "id": "ca32853c-48fa-40be-ae75-77b37504581b",
  "name": "Jane Doe"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

account = app_token.get account_url
account.name # => "Jane Doe"
<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

$accountsApi = new DwollaSwagger\AccountsApi($apiClient);

$account = $accountsApi->id($accountUrl);
print($account->name); # => "Jane Doe"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

account = app_token.get(account_url)
account.body['name']
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(accountUrl)
  .then(res => res.body.name); // => 'Jane Doe'

Create a funding source for an account

This section details how to add a bank account to a Dwolla account. The bank account will have a status of unverified upon creation. Before a Dwolla account is eligible to transfer money from their bank or credit union account they need to verify ownership of the account via micro-deposit verification.

For more information on micro-deposit verification, reference the funding source verification resource article.

HTTP request

POST https://api.dwolla.com/funding-sources

Request parameters

Parameter Required Type Description
accountNumber yes string The bank account number.
routingNumber yes string The bank account’s routing number.
bankAccountType yes string Type of bank account: checking or savings.
name yes string Arbitrary nickname for the funding source.
channels no array An array containing a list of processing channels. ACH is the default processing channel for bank transfers. Acceptable value for channels is: “wire”. e.g. “channels”: [ “wire” ]. A funding source (Bank Account) added using the wire channel only supports a funds transfer going to the bank account from a balance. Note: channels is a premium feature that must be enabled on your account and is only available to select Dwolla customers.

HTTP status and error codes

HTTP Status Message
400 Duplicate funding source or validation error.
403 Not authorized to create funding source.

Request and response

POST https://api-sandbox.dwolla.com/funding-sources
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
    "routingNumber": "222222226",
    "accountNumber": "123456789",
    "bankAccountType": "checking",
    "name": "My Bank"
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3
<?php
$fundingApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fundingApi->createFundingSource([
  "routingNumber" => "222222226",
  "accountNumber" => "123456789",
  "bankAccountType" => "checking",
  "name" => "My Bank"
]);
$fundingSource; # => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  routingNumber: '222222226',
  accountNumber: '123456789',
  bankAccountType: 'checking',
  name: 'My Bank'
}

funding_source = app_token.post "funding-sources", request_body
funding_source.response_headers[:location] # => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'bankAccountType': 'checking',
  'name': 'My Bank'
}

funding_source = app_token.post('funding-sources', request_body)
funding_source.headers['location'] # => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'
var requestBody = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'bankAccountType': 'checking',
  'name': 'My Bank'
};

appToken
  .post(`funding-sources`, requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'

List funding sources for an account

Retrieve a list of funding sources that belong to an Account. By default, all funding sources are returned unless the removed querystring parameter is set to false in the request.

HTTP request

GET https://api.dwolla.com/accounts/{id}/funding-sources

Request parameters

Parameter Required Type Description
id yes string Account’s unique identifier.
removed no boolean Filter removed funding sources. Defaults to true. Set to false to filter out removed funding sources from list (i.e. - /accounts/{id}/funding-sources?removed=false).

HTTP status and error codes

HTTP Status Message
403 Not authorized to list funding sources.
404 Account not found.

Request and response

GET https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources",
            "resource-type": "funding-source"
        }
    },
    "_embedded": {
        "funding-sources": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "funding-source"
                    },
                    "account": {
                        "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "account"
                    }
                },
                "id": "04173e17-6398-4d36-a167-9d98c4b1f1c3",
                "status": "verified",
                "type": "bank",
                "bankAccountType": "checking",
                "name": "My Account - Checking",
                "created": "2017-09-25T20:03:41.000Z",
                "removed": false,
                "channels": [
                    "ach"
                ],
                "bankName": "First Midwestern Bank"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
                    },
                    "account": {
                        "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
                    },
                    "with-available-balance": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
                    },
                    "balance": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7/balance",
                    }
                },
                "id": "b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
                "status": "verified",
                "type": "balance",
                "name": "Balance",
                "created": "2017-08-22T18:21:51.000Z",
                "removed": false,
                "channels": []
            }
        ]
    }
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

funding_sources = app_token.get "#{account_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe's Checking"
<?php
$accountUrl = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSources = $fsApi->getAccountFundingSources($accountUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Jane Doe’s Checking"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

funding_sources = app_token.get('%s/funding-sources' % account_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Jane Doe’s Checking'
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${accountUrl}/funding-sources`)
  .then(res => res.body._embedded['funding-sources'][0].name); // => 'ABC Bank Checking'

List and search transfers for an account

This section covers how to retrieve an Account’s list of transfers. Transaction search is supported by passing in optional query string parameters such as: search which represents a term to search on, correlationId, startAmount, endAmount, startDate, endDate, and status.

HTTP request

GET https://api.dwolla.com/accounts/{id}/transfers

Request parameters

Parameter Required Type Description
id yes string Account unique identifier to get transfers for.
search no string A string to search on fields: firstName, lastName, email, businessName, Customer Id, and Account Id. (/transfers?search=Doe)
startAmount no string Only include transactions with an amount equal to or greater than startAmount. Can optionally be used with endAmount to specify an amount range.
endAmount no string Only include transactions with an amount equal to or less than endAmount. Can optionally be used with startAmount to specify an amount range.
startDate no string Only include transactions created after this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with endDate to specify a date range.
endDate no string Only include transactions created before than this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with startDate to specify a date range.
status no string Filter results on transaction status. Possible values: pending, processed, failed, reclaimed, or cancelled.
correlationId no string A string value to search on if a correlationId was specified on a transfer or mass payment item.
limit no integer Number of search results to return. Defaults to 25.
offset no integer Number of search results to skip. Used for pagination.

HTTP status and error codes

HTTP Status Message
404 Account not found.

Request and response

GET https://api.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers?limit=25&offset=0"
    }
  },
  "_embedded": {
    "transfers": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/transfers/DC68A3DC-3C61-E511-80DA-0AA34A9B2388"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/accounts/CA32853C-48FA-40BE-AE75-77B37504581B"
          },
          "destination": {
            "href": "https://api-sandbox.dwolla.com/accounts/A84222D5-31D2-4290-9A96-089813EF96B3"
          }
        },
        "id": "DC68A3DC-3C61-E511-80DA-0AA34A9B2388",
        "status": "processed",
        "amount": {
          "value": "50.00",
          "currency": "USD"
        },
        "created": "2015-09-22T15:16:14.180Z"
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/transfers/D36FD9AA-6E5C-E511-80DA-0AA34A9B2388"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/2BFF2631-4006-45D6-BBBD-A7BE4853E870"
          },
          "destination": {
            "href": "https://api-sandbox.dwolla.com/accounts/A84222D5-31D2-4290-9A96-089813EF96B3"
          }
        },
        "id": "D36FD9AA-6E5C-E511-80DA-0AA34A9B2388",
        "status": "processed",
        "amount": {
          "value": "5000.00",
          "currency": "USD"
        },
        "created": "2015-09-03T18:11:53.410Z"
      }
    ]
  },
  "total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3'

transfers = app_token.get "#{account_url}/transfers"
transfers._embedded['transfers'][0].status # => "processed"
<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3';

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

$transfers = $transfersApi->getAccountTransfers($accountUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "processed"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3'

transfers = app_token.get('%s/transfers' % account_url)
transfers.body['_embedded']['transfers'][0]['status'] # => "processed"
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${accountUrl}/transfers`)
  .then(res => res.body._embedded['transfers'][0].status); // => 'processed'

List mass payments for an account

This section covers how to retrieve an Account’s list of previously created mass payments. Mass payments are returned ordered by date created, with most recent mass payments appearing first.

HTTP request

GET https://api.dwolla.com/accounts/{id}/mass-payments

Request parameters

Parameter Required Type Description
id yes string Account unique identifier to get mass payments for.
limit no integer How many results to return. Defaults to 25.
offset no integer How many results to skip.
correlationId no string A string value to search on if a correlationId was specified on a mass payment.

HTTP status and error codes

HTTP Status Code Description
403 NotAuthorized Not authorized to list mass payments.
404 NotFound Account not found.

Request and response

GET https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

....

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
    }
  },
  "_embedded": {
    "mass-payments": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/84c77e52-d1df-4a33-a444-51911a9623e9"
          },
          "items": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc/items"
          }
        },
        "id": "b4b5a699-5278-4727-9f81-a50800ea9abc",
        "status": "complete",
        "created": "2015-09-03T14:14:10.000Z",
        "metadata": {
          "UserJobId": "some ID"
        },
        "correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
      }
    ]
  },
  "total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

mass_payments = account_token.get "#{account_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"
<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3';

$masspaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);

$masspayments = $masspaymentsApi->getByAccount($accountUrl, 10, 0);
$masspayments->_embedded->{'mass-payments'}[0]->status; # => "complete"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

transfers = app_token.get('%s/mass-payments' % account_url, limit = 10)
transfers.body['_embedded']['mass-payments'][0]['status'] # => "complete"
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${accountUrl}/mass-payments`)
  .then(res => res.body._embedded['mass-payments'][0].status); // => 'complete'

Customers

A Customer represents an individual or business with whom you intend to transact with and is programmatically created and managed by a Dwolla account via the API. In order for a Dwolla Account to create and manage Customers, an application must obtain permission from Dwolla before being enabled in production.

Customer types

With a transfer of money, at least one party must complete the identity verification process, either the sender or the receiver. This can be either the Dwolla Master Account itself or a verified Customer type. Based on your business model and funds flow, it’s your decision about which party completes this process– you may even want to have both parties complete the identity verification process. A brief description of each Customer type is below, but for a more in-depth overview of each Customer type and what their capabilities are, check out our developer resource article.

Receive-only Customers

Receive-only customers are restricted to a “payouts only” funds flow. A receive-only customer maintains limited functionality in the API and is only eligible to receive transfers to an attached bank account. This Customer type can only interact with verified Customers and a Dwolla Master Account.

Unverified Customers

Unverified Customers have a default sending transaction limit of $5,000 per week. A week is defined as Monday to Sunday UTC time. As this Customer is not identity verified, they will only be able to transact with verified Customers or your Dwolla Master Account.

Verified Customers

Verified Customers are defined by their ability to both send and receive money, thus, being able to fit all funds flows. They can also interact with any Customer type and hold a balance funding source within the Dwolla network. Think of the Dwolla balance as a “wallet” which a Customer can send, receive, or hold funds to within the Dwolla network. With no weekly transfer limits, this Customer type is flexible for high transaction volumes.

A verified Customer can be created as a type of either Personal or Business.

Migrating Dwolla user Accounts to Dwolla API Customers

Dwolla offers a seamless process for migrating existing user Accounts managed via OAuth on your platform to Dwolla API Customers. The user Account will maintain existing functionality on dwolla.com and will act as a separate Dwolla API Customer upon completion of the migration. To learn more about upgrading from our V1 API or Transfer API to the current V2 Dwolla API, please contact Sales.

Link Description
self URL of the Customer resource
receive Follow the link to create a transfer to this Customer.
funding-sources GET this link to list the Customer’s funding sources.
transfers GET this link to list the Customer’s transfers
send (optional) If this link exists, this Customer can send funds. POST to this URL to create a transfer.
retry-verification If the Customer has a status of retry, POST to this link to attempt to correct their identity verification information.
verify-with-document If the Verified Customer of type personal or business has a status of document, POST to this link to upload a new photo document to verify the Customer’s identity. If type business, the controller of the business. Read about Documents.
verify-business-with-document If the Verified Customer of type business has a status of document, POST to this link to upload a new photo document to verify the identity of the business itself. Read about Documents.
verify-controller-and-business-with-document If the Verified Customer of type business has a status of document, POST to this link to upload new photo documents to verify the identity of the controller of the business as well as the business itself. Read about Documents.

Customer resource

Parameter Description
id Customer’s unique identifier.
firstName Customer’s first name.
lastName Customer’s last name.
email Customer’s email address.
type Either unverified, personal, business, or receive-only.
status If type is unverified or receive-only: status can be unverified or suspended.
If type is personal or business: status can be retry, document, verified, or suspended.
created ISO-8601 timestamp.

Customer statuses

Status Description
unverified Customers of type unverified or receive-only always have this status.
retry Verified Customers of type personal or business can have this status. The initial verification attempt failed because the information provided did not satisfy our verification check. You can make one additional attempt by changing some or all the attributes of the existing Customer with a POST request. If the additional attempt fails, the resulting status will be either document or suspended.
document Verified Customers of type personal or business can have this status. Dwolla requires additional documentation to identify the Customer in the document status. Read about Documents.
verified Verified Customers of type personal or business can have this status. The Customer is currently verified.
suspended All Customer types can have a status of suspended. The Customer is suspended and may neither send nor receive funds. Contact Dwolla support for more information.
deactivated All Customer types can have a status of deactivated. A deactivated Customer may neither send nor receive funds. A deactivated Customer can be reactivated which moves the Customer to the status they were in prior to being deactivated.
{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "receive": {
      "href": "https://api-sandbox.dwolla.com/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    },
    "edit-form": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
      "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
      "resource-type": "customer"
    },
    "edit": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce/funding-sources",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "funding-source"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    },
    "send": {
      "href": "https://api-sandbox.dwolla.com/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    }
  },
  "id": "9da3aa7c-2524-430b-a751-6dc722735fce",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "janedoe@email.com",
  "type": "personal",
  "status": "verified",
  "created": "2016-08-17T18:58:47.630Z",
  "address1": "99-99 33rd St",
  "address2": "Apt 8",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101",
  "phone": "5554321234"
}

Create a customer

This section details how to create a new Customer.

To create Receive-only Customers, you’ll provide the customer’s full name and email address, type with the value of receive-only, and businessName if applicable.

To create Unverified Customers, you will only need to provide the customer’s full name and email address, as well as a businessName if applicable.

To create Verified Customers, Dwolla will require additional information to confirm the identity of the individual or business. Verified Customers can include type business or personal. For businesses, Dwolla will need to verify information about both the business and the controller for that business. Dwolla does not identity verify the Account Admin.

HTTP request

POST https://api.dwolla.com/customers

HTTP status and error codes

HTTP Status Message
400 Duplicate customer or validation error.
403 Not authorized to create customers.

Request parameters - receive-only Customer

Parameter Required Type Description
firstName yes string Customer’s first name.
lastName yes string Customer’s last name.
email yes string Customer’s email address.
type yes string Value of receive-only.
businessName yes string Customer’s registered business name. (Optional if not a business entity)
ipAddress no string Customer’s IP address.
Request and response - receive-only Customer
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "Jane",
  "lastName": "Merchant",
  "email": "jmerchant@nomail.net",
  "type": "receive-only",
  "businessName": "Jane Corp llc",
  "ipAddress": "99.99.99.99"
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :firstName => 'Jane',
  :lastName => 'Merchant',
  :email => 'jmerchant@nomail.net',
  :type => 'receive-only',
  :businessName => 'Jane Corp llc',
  :ipAddress => '99.99.99.99'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->create([
  'firstName' => 'Jane',
  'lastName' => 'Merchant',
  'email' => 'jmerchant@nomail.net',
  'type' => 'receive-only',
  'businessName' => 'Jane Corp llc',
  'ipAddress' => '99.99.99.99'
]);
$customer; # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'firstName': 'Jane',
  'lastName': 'Merchant',
  'email': 'jmerchant@nomail.net',
  'type': 'receive-only',
  'businessName': 'Jane Corp llc',
  'ipAddress': '99.99.99.99'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
var requestBody = {
  firstName: 'Jane',
  lastName: 'Merchant',
  email: 'jmerchant@nomail.net',
  type: 'receive-only',
  businessName: 'Jane Corp llc',
  ipAddress: '99.99.99.99'
};

appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'

Request parameters - unverified Customer

Parameter Required Type Description
firstName yes string Customer’s first name.
lastName yes string Customer’s last name.
email yes string Customer’s email address.
businessName yes string Customer’s registered business name. (Optional if not a business entity)
ipAddress no string Customer’s IP address.
Request and response - unverified Customer
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "Jane",
  "lastName": "Merchant",
  "email": "jmerchant@nomail.net",
  "ipAddress": "99.99.99.99",
  "businessName": "Jane Merchant's Business"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :firstName => 'Jane',
  :lastName => 'Merchant',
  :email => 'jmerchant@nomail.net',
  :ipAddress => '99.99.99.99'
}

customer = app_token.post "customers", request_body
customer.headers[:location] # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->create([
  'firstName' => 'Jane',
  'lastName' => 'Merchant',
  'email' => 'jmerchant@nomail.net',
  'ipAddress' => '99.99.99.99'
]);

$customer; # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'firstName': 'Jane',
  'lastName': 'Merchant',
  'email': 'jmerchant@nomail.net',
  'ipAddress': '99.99.99.99'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
var requestBody = {
  firstName: 'Jane',
  lastName: 'Merchant',
  email: 'jmerchant@nomail.net',
  ipAddress: '99.99.99.99'
};

appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'

Request parameters - verified personal Customer

For an in-depth look at personal verified Customers creation and status handling, refer to our developer resource article.

Parameter Required Type Description
firstName yes string An individual Customer’s first name.
lastName yes string An individual Customer’s last name.
email yes string Customer’s email address.
ipAddress no string Customer’s IP address.
type yes string The Verified Customer type. Set to personal if creating a verified personal Customer.
address1 yes string First line of the street address of the Customer’s permanent residence. Must be 50 characters or less. Note: PO Boxes are not allowed.
address2 no string Second line of the street address of the Customer’s permanent residence. Must be 50 characters or less. Note: PO Boxes are not allowed.
city yes string City of Customer’s permanent residence.
state yes string Two letter abbreviation of the state in which the Customer resides, e.g. CA.
postalCode yes string Postal code of Customer’s permanent residence. US five-digit ZIP or ZIP + 4 code. e.g. 50314.
dateOfBirth yes string Customer’s date of birth in YYYY-MM-DD format. Must be 18 years or older.
ssn yes string Last four digits of the Customer’s Social Security Number.
phone no string Customer’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
Request and response - verified personal Customer
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@nomail.net",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "99-99 33rd St",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101",
  "dateOfBirth": "1970-01-01",
  "ssn": "1234"
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->create([
  'firstName' => 'John',
  'lastName' => 'Doe',
  'email' => 'jdoe@nomail.net',
  'type' => 'personal',
  'address1' => '99-99 33rd St',
  'city' => 'Some City',
  'state' => 'NY',
  'postalCode' => '11101',
  'dateOfBirth' => '1970-01-01',

  # For the first attempt, only the
  # last 4 digits of SSN required

  # If the entire SSN is provided,
  # it will still be accepted
  'ssn' => '1234'
]);

$customer; # => "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :firstName => 'John',
  :lastName => 'Doe',
  :email => 'jdoe@nomail.net',
  :type => 'personal',
  :address1 => '99-99 33rd St',
  :city => 'Some City',
  :state => 'NY',
  :postalCode => '11101',
  :dateOfBirth => '1970-01-01',

  # For the first attempt, only the
  # last 4 digits of SSN required

  # If the entire SSN is provided,
  # it will still be accepted

  :ssn => '1234'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'firstName': 'John',
  'lastName': 'Doe',
  'email': 'jdoe@nomail.net',
  'type': 'personal',
  'address1': '99-99 33rd St',
  'city': 'Some City',
  'state': 'NY',
  'postalCode': '11101',
  'dateOfBirth': '1970-01-01',
  # For the first attempt, only the
  # last 4 digits of SSN required
  # If the entire SSN is provided,
  # it will still be accepted
  'ssn': '1234'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
var requestBody = {
  firstName: 'John',
  lastName: 'Doe',
  email: 'jdoe@nomail.net',
  type: 'personal',
  address1: '99-99 33rd St',
  city: 'Some City',
  state: 'NY',
  postalCode: '11101',
  dateOfBirth: '1970-01-01',
  // For the first attempt, only the
  // last 4 digits of SSN required
  // If the entire SSN is provided,
  // it will still be accepted
  ssn: '1234'
};

appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'

Request parameters - verified business Customer (sole proprietorship only)

For an in-depth look at business verified Customers creation and status handling, refer to our developer resource article. Dwolla will verify the identity of both the Business Owner and the Business entity.

Parameter Required Type Description
firstName yes string The legal first name of the business owner.
lastName yes string The legal last name of the business owner.
email yes string email address of the business owner.
ipAddress no string ipAddress of registering user is recommended.
type yes string Value of: business
dateOfBirth yes string The date of birth of the business owner. Formatted in YYYY-MM-DD format. Must be 18 years or older.
ssn yes string Last four-digits of the business owner’s social security number.
address1 yes string Street number, street name of business’ physical address.
address2 no string Apartment, floor, suite, bldg. # of business’ physical address
city yes string City of business’ physical address.
state yes string Two-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode yes string Business’ US five-digit ZIP or ZIP + 4 code.
businessName yes string Registered business name.
doingBusinessAs no string Preferred business name – also known as fictitious name, or assumed name.
businessType yes string Business structure. Value of soleProprietorship.
businessClassification yes string The industry classification Id that corresponds to Customer’s business. Reference our Dev Docs to learn how to generate this Id.
ein no string Employer Identification Number. Optional for soleProprietorship business Customers
website no string Business’ website
phone no string Business’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
Request and response - verified business Customer (sole proprietorship only)
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q

{
    "firstName": "Business",
    "lastName": "Owner",
    "email": "solePropBusiness@email.com",
    "ipAddress": "143.156.7.8",
    "type": "business",
    "dateOfBirth": "1980-01-31",
    "ssn": "6789",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
    "businessType": "soleProprietorship",
    "businessName":"Jane Corp",
    "ein":"00-0000000"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = 'https://api-sandbox.dwolla.com/customers/b70c3194-35fa-49e8-9243-d55a30e06d1e';
$new_customer = $customersApi->create([
    'firstName' => 'Business',
    'lastName' => 'Owner',
    'email' => 'solePropBusiness@email.com',
    'ipAddress' => '143.156.7.8',
    'type' => 'business',
    'dateOfBirth' => '1980-01-31',
    'ssn' => '6789',
    'address1' => '99-99 33rd St',
    'city' => 'Some City',
    'state' => 'NY',
    'postalCode' => '11101',
    'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
    'businessType' => 'soleProprietorship',
    'businessName' => 'Jane Corp',
    'ein' => '00-0000000']);

?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
    :firstName => 'Business',
    :lastName => 'Owner',
    :email => 'solePropBusiness@email.com',
    :ipAddress => '143.156.7.8',
    :type => 'business',
    :dateOfBirth => '1980-01-31',
    :ssn => '6789',
    :address1 => '99-99 33rd St',
    :city => 'Some City',
    :state => 'NY',
    :postalCode => '11101',
    :businessClassification => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
    :businessType => 'soleProprietorship',
    :businessName => 'Jane Corp',
    :ein => '00-0000000'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
  'firstName': 'Business',
  'lastName': 'Owner',
  'email': 'solePropBusiness@email.com',
  'ipAddress': '143.156.7.8',
  'type': 'business',
  'dateOfBirth': '1980-01-31',
  'ssn': '6789',
  'address1': '99-99 33rd St',
  'city': 'Some City',
  'state': 'NY',
  'postalCode': '11101',
  'businessClassification': '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
  'businessType': 'soleProprietorship',
  'businessName': 'Jane Corp',
  'ein': '00-0000000'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
var requestBody = {
    firstName: 'Business',
    lastName: 'Owner',
    email: 'solePropBusiness@email.com',
    ipAddress: '143.156.7.8',
    type: 'business',
    dateOfBirth: '1980-01-31',
    ssn: '6789',
    address1: '99-99 33rd St',
    city: 'Some City',
    state: 'NY',
    postalCode: '11101',
    businessClassification: '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
    businessType: 'soleProprietorship',
    businessName: 'Jane Corp',
    ein: '00-0000000',
};

appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

Request parameters - verified business Customer (businessType=llc, corporation or partnership)

For an in-depth look at business verified Customers creation and status handling, refer to our developer resource article. A verified business Customer must input information on the controller and the Business entity for Dwolla. Dwolla will verify the identity of both the Controller and the Business Entity.

Parameter Required Type Description
firstName yes string The legal first name of the Account Admin or business owner signing up the business verified Customer.
lastName yes string The legal last name of the Account Admin or individual signing up the business verified Customer.
email yes string email address of individual creating and managing the Customer account.
ipAddress no string ipAddress of registering user is recommended.
type yes string Value of: business
address1 yes string Street number, street name of business’ physical address.
address2 no string Apartment, floor, suite, bldg. # of business’ physical address.
city yes string City of business’ physical address.
state yes string Two-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode yes string Business’ US five-digit ZIP or ZIP + 4 code.
businessName yes string Registered business name.
doingBusinessAs no string Preferred business name – also known as fictitious name, or assumed name.
businessType yes string Business structure. Possible values are corporation, llc, partnership.
businessClassification yes string The industry classification Id that corresponds to Customer’s business. Reference the next section of our docs to learn how to generate this Id.
ein yes string Employer Identification Number.
website no string Business’ website
phone no string Business’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
controller conditional object A controller JSON object.
Controller JSON object

A controller is any natural individual who holds significant responsibilities to control, manage, or direct a company or other corporate entity (i.e. CEO, CFO, General Partner, President, etc). A company may have more than one controller, but only one controller’s information must be collected.

Parameter Required Type Description
firstName yes String The legal first name of the controller.
lastName yes String The legal last name of the controller.
title yes String Job title of the business verified Customer’s controller. IE - Chief Financial Officer
dateOfBirth yes String The date of birth of the controller. Formatted in YYYY-MM-DD format. Must be 18 years or older.
ssn conditional String Last four-digits of controller’s social security number. Required for US persons.
address yes object An address JSON object. Full address of the controller’s physical address.
passport conditional object An optional passport JSON object. Required for non-US persons. Includes passport identification number and country.
Controller address JSON object
Parameter Required Type Description
address1 yes string Street number, street name of controller’s physical address.
address2 no string Apartment, floor, suite, bldg. # of controller’s physical address.
address3 no string Third line of the street address of the controller’s physical address.
city yes string City of controller’s physical address.
stateProvinceRegion yes string Two-letter US state or territory abbreviation code of controller’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode no string Controller’s’ US five-digit ZIP or ZIP + 4 code.
country yes string Country of controller’s physical address
Controller passport JSON object

A controller will only need to input Passport information if they are non-US persons and do not have a social security number.

Parameter Required Type Description
number conditional string Required if controller is a non-US person and has no Social Security number.
country conditional string Country of issued passport.

Verified Business Customer (businessType= llc, corporation or partnership)

POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q

{
    "firstName": "Account",
    "lastName": "Admin",
    "email": "accountAdmin@email.com",
    "ipAddress": "143.156.7.8",
    "type": "business",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "controller": {
        "firstName": "John",
        "lastName": "Controller",
        "title": "CEO",
        "ssn": "6789",
        "dateOfBirth": "1980-01-31",
        "address": {
            "address1": "1749 18th st",
            "address2": "apt 12",
            "city": "Des Moines",
            "stateProvinceRegion": "IA",
            "postalCode": "50266",
            "country": "US"
        }
    },
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
    "businessType": "llc",
    "businessName":"Jane Corp",
    "ein":"00-0000000"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = 'https://api-sandbox.dwolla.com/customers/b70c3194-35fa-49e8-9243-d55a30e06d1e';
$new_customer = $customersApi->create([
  'firstName' => 'Account',
  'lastName' => 'Admin',
  'email' => 'accountAdmin@email.com',
  'type' => 'business',
  'address1' => '99-99 33rd St',
  'city' => 'Some City',
  'state' => 'NY',
  'postalCode' => '11101',
  'controller' =>
  [
      'firstName' => 'John',
      'lastName'=> 'Controller',
      'title' => 'CEO',
      'dateOfBirth' => '1990-10-10',
      'ssn' => '1234',
      'address' =>
      [
          'address1' => '18749 18th st',
          'address2' => 'apt 12',
          'city' => 'Des Moines',
          'stateProvinceRegion' => 'IA',
          'postalCode' => '50265',
          'country' => 'US'
      ],
  ],
  'phone' => '5554321234',
  'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
  'businessType' => 'llc',
  'businessName' => 'Jane Corp',
  'ein' => '00-0000000']);

?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
  :firstName => 'Account',
  :lastName => 'Admin',
  :email => 'accountAdmin@email.com',
  :type => 'business',
  :address1 => '99-99 33rd St',
  :city => 'Some City',
  :state => 'NY',
  :postalCode => '11101',
  :controller => {
      :firstName => 'John',
      :lastName => 'Controller',
      :title => 'CEO',
      :dateOfBirth => '1980-01-31',
      :ssn => '1234',
      :address => {
        :address1 => '1749 18th st',
        :address2 => 'apt 12',
        :city => 'Des Moines',
        :stateProvinceRegion => 'IA',
        :postalCode => '50266',
        :country => 'US',
      }
  },
  :businessClassification => '9ed38155-7d6f-11e3-83c3-5404a6144203',
  :businessType => 'llc',
  :businessName => 'Jane Corp',
  :ein => '12-3456789'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
  'firstName': 'Account',
  'lastName': 'Admin',
  'email': 'accountAdmin@email.com',
  'type': 'business',
  'address1': '99-99 33rd St',
  'city': 'Some City',
  'state': 'NY',
  'postalCode': '11101',
  'controller': {
      'firstName': 'John',
      'lastName': 'Controller',
      'title': 'CEO',
      'dateOfBirth': '1980-01-31',
      'ssn': '1234',
      'address': {
        'address1': '1749 18th st',
        'address2': 'apt12',
        'city': 'Des Moines',
        'stateProvinceRegion': 'IA',
        'postalCode': '50266',
        'country': 'US'
      }
  },
  'businessClassification': '9ed38155-7d6f-11e3-83c3-5404a6144203',
  'businessType': 'llc',
  'businessName': 'Jane Corp',
  'ein': '12-3456789'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
var requestBody = {
  firstName: 'Account',
  lastName: 'Admin',
  email: 'accountAdmin@email.com',
  type: 'business',
  address1: '99-99 33rd St',
  city: 'Some City',
  state: 'NY',
  postalCode: '11101',
  controller: {
      firstName: 'John',
      lastName: 'Controller',
      title: 'CEO',
      dateOfBirth: '1980-01-31',
      ssn: '1234'
      address: {
        address1: '1749 18th st',
        address2: 'apt 12',
        city: 'Des Moines',
        stateProvinceRegion: 'IA',
        postalCode: '50266',
        country: 'US',
      }
  },
  businessClassification: '9ed38155-7d6f-11e3-83c3-5404a6144203',
  businessType: 'llc',
  businessName: 'Jane Corp',
  ein: '12-3456789'
};
appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

List business classifications

Retrieve a list of industry classifications to identify the Customer’s business. An industry classification is required by Dwolla when verifying a business in order to better analyze the nature of a business.

HTTP request

GET https://api.dwolla.com/business-classifications

Request and response

GET https://api-sandbox.dwolla.com/business-classifications
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {},
  "_embedded": {
    "business-classifications": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/business-classifications/9ed3f669-7d6f-11e3-b545-5404a6144203"
          }
        },
        "_embedded": {
          "industry-classifications": [
            {
              "id": "9ed3f671-7d6f-11e3-803c-5404a6144203",
              "name": "Gourmet foods"
            },
            {
              "id": "9ed3f66c-7d6f-11e3-86ae-5404a6144203",
              "name": "Distilleries"
            },
            {
              ...........
            }
          ]
        },
        "id": "9ed3f669-7d6f-11e3-b545-5404a6144203",
        "name": "Food retail and service"
      }
      ...........
    ]
  },
  "total": 27
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
business_classifications = app_token.get "business-classifications"
business_classifications._embedded['business-classifications'][0].name # => "Food retail and service"
<?php
$businessClassificationsApi = new DwollaSwagger\BusinessclassificationsApi($apiClient);

$busClassifications = $businessClassificationsApi->_list();
$busClassifications->_embedded->{'business-classifications'}[0]->name; # => "Food retail and service"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
business_classifications = app_token.get('business-classifications')
business_classifications.body['_embedded']['business-classifications'][0]['name'] # => 'Food retail and service'
appToken
  .get('business-classifications')
  .then(res => res.body._embedded['business-classifications'][0].name); // => 'Food retail and service'

Retrieve a business classification

This section shows you how to retrieve a business classification from a list of industry classifications. An industry classification id is needed in order to verify a business Customer.

HTTP request

GET https://api.dwolla.com/business-classifications/{id}

Request parameters

Parameter Required Type Description
id yes string Business classification unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203"
    }
  },
  "_embedded": {
    "industry-classifications": [
      {
        "id": "9ed3cf58-7d6f-11e3-81a4-5404a6144203",
        "name": "Toys and games"
      },
      {
        "id": "9ed3cf50-7d6f-11e3-8ae8-5404a6144203",
        "name": "Music"
      },
      {
        ...........
      }
    ]
  },
  "id": "9ed3a866-7d6f-11e3-a0ce-5404a6144203",
  "name": "Entertainment and media"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
business_classification_url = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203'

business_classification = app_token.get business_classification_url
business_classification.name # => "Entertainment and media"
<?php
$businessClassificationUrl = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203';

$businessClassificationsApi = new DwollaSwagger\BusinessclassificationsApi($apiClient);

$busClassifications = $customersApi->getBusinessClassification($businessClassificationUrl);
$busClassifications->name; # => "Entertainment and media"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
business_classification_url = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203'

busClassification = app_token.get(business_classification_url)
busClassification.body['name']
var businessClassificationUrl = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203';

appToken
  .get(businessClassificationUrl)
  .then(res => res.body.name); // => 'Entertainment and media'

Update a customer

This endpoint can be used to facilitate the following use cases: Update Customer information, upgrade an unverified Customer to a verified Customer, suspend a Customer, deactivate a Customer, reactivate a Customer, and update a verified Customer’s information to retry verification.

HTTP request

POST https://api.dwolla.com/customers/{id}

Update a Customer’s information

A limited set of information can be updated on an existing created Customer. Note: A Customer’s information cannot be updated when in a status of document or suspended.

Request parameters - unverified Customer and receive-only Customer
Parameter Required Type Description
firstName no string Customer’s first name.
lastName no string Customer’s last name.
email no string Customer’s email address.
businessName no string Customer’s registered business name. An empty string value will unset businessName.
Request parameters - verified Customer
Parameter Required Type Description
email no string Customer’s email address.
ipAddress no string Customer’s IP address.
address1 no string First line of the street address of the customer’s permanent residence. Note: PO Boxes are not allowed.
address2 no string Second line of the street address of the customer’s permanent residence. Note: PO Boxes are not allowed.
city no string City of customer’s permanent residence.
state no string Two letter abbreviation of the state in which the customer resides. e.g. NY.
postalCode no string Postal code of customer’s permanent residence. Should be a five digit postal code, e.g. 50314.
phone no string Customer’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
Request parameters - verified Customer with type=business

In addition to the table above, business verified Customers can update the following fields.

Parameter Required Type Description
doingBusinessAs no string Name that is different from the officially registered name of Customer’s business.
website no string www.domain.com

Upgrade an unverified Customer to verified Customer

An unverified Customer can be upgraded to a verified Customer by supplying the necessary information required to create a verified Customer. Reference this table for required information.

Suspend a Customer

Unverified and Verified Customers can be suspended by specifying a status of suspended in your request. You’ll need to contact Dwolla to unsuspend a Customer.

Request parameters
Parameter Required Type Description
status yes string Value of suspended.

Deactivate a Customer

Customers can be deactivated by specifying a status of deactivated in your request. A Customer cannot be deactivated if the Customer has a suspended verification status. Customers can be systematically deactivated by Dwolla if certain ACH return codes are triggered on bank transfer failures.

Request parameters
Parameter Required Type Description
status yes string Value of deactivated.

Reactivate a Customer

Customers can be reactivated by specifying a status of reactivated in your request. Reactivated Customers will be moved to the status they were in prior to being deactivated.

Request parameters
Parameter Required Type Description
status yes string Value of reactivated.

Retry verification

If the verified Customer has a status of retry, some information may have been miskeyed. You have one more opportunity to correct any mistakes using this endpoint. This time, you’ll need to provide the Customer’s full SSN. If the additional attempt fails, the resulting status will be either document or suspended.

Customer must be in the retry state:

{
    "_links": {
        "deactivate": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "edit-form": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
            "resource-type": "customer"
        },
        "edit": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "funding-sources": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/funding-sources",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "retry-verification": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "transfers": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        }
    },
    "id": "53863b11-1758-47c8-821f-00e6a126f97f",
    "firstName": "retry",
    "lastName": "doe",
    "email": "jdoe@nomail.com",
    "type": "personal",
    "status": "retry",
    "created": "2017-11-06T20:11:13.430Z",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101"
}

Request and response

POST https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@nomail.com",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "221 Corrected Address St.",
  "address2": "Apt 201",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94104",
  "dateOfBirth": "1970-07-11",
  "ssn": "123-45-6789"
}

...

{
    "_links": {
        "deactivate": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "receive": {
            "href": "https://api-sandbox.dwolla.com/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "edit-form": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
            "resource-type": "customer"
        },
        "edit": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "funding-sources": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/funding-sources",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "transfers": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "send": {
            "href": "https://api-sandbox.dwolla.com/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        }
    },
    "id": "53863b11-1758-47c8-821f-00e6a126f97f",
    "firstName": "John",
    "lastName": "Doe",
    "email": "jdoe@nomail.com",
    "type": "personal",
    "status": "verified",
    "created": "2017-11-06T20:11:13.430Z",
    "address1": "221 Corrected Address St.",
    "address2": "Apt 201",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94104"
}
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customerUrl = 'https://api.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f';
$customer = $customersApi->updateCustomer(array (
  'firstName' => 'John',
  'lastName' => 'Doe',
  'email' => 'jdoe@nomail.com',
  'ipAddress' => '10.10.10.10',
  'type' => 'personal',
  'address1' => '221 Corrected Address St.',
  'address2' => 'Apt 201',
  'city' => 'San Francisco',
  'state' => 'CA',
  'postalCode' => '94104',
  'dateOfBirth' => '1970-07-11',
  'ssn' => '123-45-6789',
), $customerUrl);

$customer->id; # => "53863b11-1758-47c8-821f-00e6a126f97f"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f'
request_body = {
      "firstName" => "John",
       "lastName" => "Doe",
          "email" => "jdoe@nomail.com",
      "ipAddress" => "10.10.10.10",
           "type" => "personal",
       "address1" => "221 Corrected Address St.",
       "address2" => "Apt 201",
           "city" => "San Francisco",
          "state" => "CA",
     "postalCode" => "94104",
    "dateOfBirth" => "1970-07-11",
            "ssn" => "123-45-6789"
}

customer = app_token.post customer_url, request_body
customer.id # => "53863b11-1758-47c8-821f-00e6a126f97f"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f'
request_body = {
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@nomail.com",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "221 Corrected Address St.",
  "address2": "Apt 201",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94104",
  "dateOfBirth": "1970-07-11",
  "ssn": "123-45-6789"
}

customer = app_token.post(customer_url, request_body)
customer.body.id # => '53863b11-1758-47c8-821f-00e6a126f97f'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f';
var requestBody = {
  firstName: "John",
  lastName: "Doe",
  email: "johndoe@dwolla.com",
  ipAddress: "10.10.10.10",
  type: "personal",
  address1: "221 Corrected Address St.",
  address2: "Fl 8",
  city: "Ridgewood",
  state: "NY",
  postalCode: "11385",
  dateOfBirth: "1990-07-11",
  ssn: "202-99-1516"
};

appToken
  .post(customerUrl, requestBody)
  .then(res => res.body.id); // => '53863b11-1758-47c8-821f-00e6a126f97f'

If you try more than once, or Customer is not in retry state:

{
  "code": "InvalidResourceState",
  "message": "Resource cannot be modified."
}

Request parameters - retry verified Customer

Parameter Required Type Description
firstName yes string Customer’s first name.
lastName yes string Customer’s last name.
email yes string Customer’s email address.
ipAddress no string Customer’s IP address.
type yes string Either personal or business. If business, see above for additional required information.
address1 yes string First line of the street address of the Customer’s permanent residence. Note: PO Boxes are not allowed.
address2 no string Second line of the street address of the Customer’s permanent residence. Note: PO Boxes are not allowed.
city yes string City of Customer’s permanent residence.
state yes string Two letter abbreviation of the state in which the customer resides, e.g. CA.
postalCode yes string Postal code of Customer’s permanent residence. Should be a five digit postal code, e.g. 50314.
dateOfBirth yes string Customer’s date of birth in YYYY-MM-DD format. Must be 18 years or older.
ssn yes string Customer’s full Social Security Number.
phone no string Customer’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.

HTTP status and error codes

HTTP Status Message
400 Duplicate customer or validation error.
403 Not authorized to create customers.

List and search customers

This section outlines how to retrieve your list of created Customers.

HTTP request

GET https://api.dwolla.com/customers

Request parameters

Parameter Required Type Description
limit no integer How many results to return.
offset no integer How many results to skip.
search no string Searches on firstName, lastName, and email fields. (/customers?search=Doe)
status no string Filter by Customer status or multiple Customer statuses. Possible values: unverified, retry, document, verified, suspended, or deactivated. (e.g. /customers?status=retry&status=document)

Request and response

GET https://api-sandbox.dwolla.com/customers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "first": {
      "href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
    }
  },
  "_embedded": {
    "customers": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
          }
        },
        "id": "FC451A7A-AE30-4404-AB95-E3553FCD733F",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "janedoe@nomail.com",
        "type": "unverified",
        "status": "unverified",
        "created": "2015-09-03T23:56:10.023Z"
      }
    ]
  },
  "total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customers = app_token.get "customers", limit: 10
customers._embedded.['customers'][0].firstName # => "Jane"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customers = $customersApi->_list(10, 0);
$customers->_embedded->{'customers'}[0]->firstName; # => "Jane"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer = app_token.get('customers', limit = 10)
customer.body['_embedded']['customers'][0]['firstName'] # => 'Jane'
appToken
  .get('customers', { limit: 10 })
  .then(res => res.body._embedded['customers'][0].firstName); // => 'Jane'

Retrieve a customer

This section shows you how to retrieve a Customer belonging to the authorized user Account. Each Customer id is a part of its location resource. The developer can pass either an id or the entire location resource to make this request.

HTTP request

GET https://api.dwolla.com/customers/{id}

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier.

HTTP status and error codes

HTTP Status Message
403 Not authorized to get a customer by id.
404 Customer not found.

Request and response

GET https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
    }
  },
  "id": "FC451A7A-AE30-4404-AB95-E3553FCD733F",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "janedoe@nomail.com",
  "type": "unverified",
  "status": "unverified",
  "created": "2015-09-03T23:56:10.023Z"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'

customer = app_token.get customer_url
customer.firstName # => "Jane"
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8';

$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->getCustomer($customerUrl);
$customer->firstName; # => "Jane"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'

customer = app_token.get(customer_url)
customer.body['firstName']
var customerUrl = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8';

appToken
  .get(customerUrl)
  .then(res => res.body.firstName); // => 'Jane'

Create an on-demand transfer authorization

This section outlines how to create an on-demand bank transfer authorization for your Customer. On-demand authorization allows Customers to authorize Dwolla to transfer variable amounts from their bank account using ACH at a later point in time for products or services delivered. This on-demand authorization is supplied along with the Customer’s bank details when creating a new Customer funding source.

When on-demand authorization is enabled for your application the Customer is presented with text on a “add bank account” screen in your user interface(UI) giving authorization to Dwolla for future variable payments. Note: On-demand payments come as part of our Dwolla API and requires additional approval before getting started. Please contact Sales for more information on enabling.

HTTP request

POST https://api.dwolla.com/on-demand-authorizations

HTTP status and error codes

HTTP Status Code Description
403 Forbidden The supplied credentials are not authorized for this resource.

Request and response

POST https://api-sandbox.dwolla.com/on-demand-authorizations
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/on-demand-authorizations/30e7c028-0bdf-e511-80de-0aa34a9b2388"
    }
  },
  "bodyText": "I agree that future payments to Company ABC inc. will be processed by the Dwolla payment system from the selected account above. In order to cancel this authorization, I will change my payment settings within my Company ABC inc. account.",
  "buttonText": "Agree & Continue"
}
on_demand_authorization = app_token.post "on-demand-authorizations"
on_demand_authorization.buttonText # => "Agree & Continue"
<?php
$onDemandApi = new DwollaSwagger\OndemandauthorizationsApi($apiClient);

$onDemandAuth = $onDemandApi->createAuthorization();
$onDemandAuth->_links["self"]->href; # => "https://api-sandbox.dwolla.com/on-demand-authorizations/30e7c028-0bdf-e511-80de-0aa34a9b2388"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
on_demand_authorization = app_token.post('on-demand-authorizations')
on_demand_authorization.body['buttonText'] # => 'Agree & Continue'
appToken
  .post('on-demand-authorizations')
  .then(res => res.body.buttonText); // => "Agree & Continue"

Create a funding source for a customer

There are two methods available for adding a bank or credit union account to a Customer. You can either collect the Customer’s bank account information and pass it to Dwolla via the new Customer funding source endpoint, or you can send the Customer through the the Instant Account Verification (IAV) flow which will add and verify a bank account within seconds.

Before a Dwolla account or Dwolla API Customer is eligible to transfer money from their bank or credit union account they need to verify ownership of the account, either via Instant Account Verification (IAV) or micro-deposits. For more information on bank account verification, reference this funding source verification resource article.

New funding source for a customer

Create a new Funding Source for a Customer. Customers can have a maximum of 6 funding sources.

HTTP request

POST https://api.dwolla.com/customers/{id}/funding-sources

Request parameters

Parameter Required Type Description
_links no object A _links JSON object containing an on-demand-authorization link relation. See example raw request and response below.
routingNumber yes string The bank account’s routing number.
accountNumber yes string The bank account number.
bankAccountType yes string Type of bank account: checking or savings.
name yes string Arbitrary nickname for the funding source. Must be 50 characters or less.
channels no array An array containing a list of processing channels. ACH is the default processing channel for bank transfers. Acceptable value for channels is: “wire”. e.g. “channels”: [ “wire” ]. A funding source (Bank Account) added using the wire channel only supports a funds transfer going to the bank account from a balance. As a result, wire as a destination funding source can only be added where the Customer account type is a Verified Customer. Note: channels is a premium feature that must be enabled on your account and is only available to select Dwolla customers.

HTTP status and error codes

HTTP Status Code Description
400 ValidationError Can be: Duplicate funding source or validation error. Authorization already associated to a funding source.
403 Forbidden Not authorized to create funding source.

Request and response

POST https://api-sandbox.dwolla.com/customers/99bfb139-eadd-4cdf-b346-7504f0c16c60/funding-sources
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
  "routingNumber": "222222226",
  "accountNumber": "123456789",
  "bankAccountType": "checking",
  "name": "Jane Doe’s Checking"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C
<?php
$fundingApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fundingApi->createCustomerFundingSource([
  "routingNumber" => "222222226",
  "accountNumber" => "123456789",
  "bankAccountType" => "checking",
  "name" => "Jane Doe’s Checking"
], "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C");
$fundingSource; # => "https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  routingNumber: '222222226',
  accountNumber: '123456789',
  bankAccountType: 'checking',
  name: 'Jane Doe’s Checking'
}

funding_source = app_token.post "#{customer_url}/funding-sources", request_body
funding_source.response_headers[:location] # => "https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'bankAccountType': 'checking',
  'name': 'Jane Doe’s Checking'
}

customer = app_token.post('%s/funding-sources' % customer_url, request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C';
var requestBody = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'bankAccountType': 'checking',
  'name': 'Jane Doe’s Checking'
};

appToken
  .post(`${customerUrl}/funding-sources`, requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31'

Instant account verification (IAV)

IAV is a simple and secure process which requires both server-side and client-side interaction. Your server requests a single-use token which is used to represent the Customer that is adding or verifying their bank. The client-side implementation includes the dwolla.js library on the page that is used to render the IAV flow.

<script src="https://cdn.dwolla.com/1/dwolla.js"></script>
<script type="text/javascript">
  var iavToken = '4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY';
  dwolla.configure('sandbox');
  dwolla.iav.start(iavToken, {
  container: 'iavContainer',
  stylesheets: [
    'https://fonts.googleapis.com/css?family=Lato&subset=latin,latin-ext',
    'https://myapp.com/iav/customStylesheet.css'
  ],
  microDeposits: false,
  fallbackToMicroDeposits: true,
  backButton: true,
  subscriber: ({ currentPage, error }) => {
      console.log('currentPage:', currentPage, 'error:', JSON.stringify(error))
    }
  }, function(err, res) {
    console.log('Error: ' + JSON.stringify(err) + ' -- Response: ' + JSON.stringify(res))
  });
</script>

Generate an IAV token

Get a single-use IAV token for a Customer.

HTTP Request

POST https://api.dwolla.com/customers/{id}/iav-token

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier.

HTTP status and error codes

HTTP Status Message
404 Customer not found.

Request and response

POST https://api-sandbox.dwolla.com/customers/99bfb139-eadd-4cdf-b346-7504f0c16c60/iav-token
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

HTTP/1.1 200 OK

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/iav-token"
    }
  },
  "token": "4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'

customer = app_token.post "#{customer_url}/iav-token"
customer.token # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var customerUrl = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6';

appToken
  .post(`${customerUrl}/iav-token`)
  .then(res => res.body.token); // => 'lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'http://api.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'

app_token.post('%s/iav-token' % customer_url)
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$iavToken = $customersApi->getCustomerIavToken("https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6");
$iavToken->token; # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
?>

Initiate IAV flow

Initiate instant account verification for a Customer.

dwolla.js

dwolla.js is a JavaScript library that gives you the ability to render the IAV flow within a specified container. Call the function dwolla.iav.start() and pass the following arguments: the container where you want IAV to render, the Customer’s single-use IAV token, and a callback to handle the response or error. This will initiate an HTTP request asking Dwolla to load IAV in the specified container. Once the Customer successfully completes the IAV flow, Dwolla sends a response that includes either an error or a link to the newly created and verified funding source resource.

Usage and configuration

Include dwolla.js

Development version: <script src="https://cdn.dwolla.com/1/dwolla.js"></script>

Production (minified) version: <script src="https://cdn.dwolla.com/1/dwolla.min.js"></script>

Configure dwolla.js
// Sandbox
dwolla.configure('sandbox');

// Production
dwolla.configure('prod');
Example
<head>
<script src="https://cdn.dwolla.com/1/dwolla.js"></script>
<!-- jQuery is used for example purposes -->
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
</head>

<div id="controls">
  <input type="button" id="start" value="Start">
</div>
<div id="iavContainer"></div>

<script type="text/javascript">
$('#start').click(function() {
  var iavToken = '4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY';
  dwolla.configure('sandbox');
  dwolla.iav.start(iavToken, {
    container: 'iavContainer',
    stylesheets: [
      'http://fonts.googleapis.com/css?family=Lato&subset=latin,latin-ext',
      'http://myapp.com/iav/customStylesheet.css'
    ],
    microDeposits: false,
    fallbackToMicroDeposits: true
  }, function(err, res) {
    console.log('Error: ' + JSON.stringify(err) + ' -- Response: ' + JSON.stringify(res));
  });
});
</script>

Response:

{
  "_links": {
    "funding-source": {
      "href": "https://api.dwolla.com/funding-sources/3daf2382-e0e4-444a-863e-544239a261e3"
    }
  }
}

Errors

Code Message
UnexpectedPage IAV navigated to an unexpected page and was cancelled.
InvalidIavToken Invalid IAV token.
UnsupportedBank The customer’s bank is not supported by the IAV flow.
RateLimitReached The customer exceeded the max # of IAV attempts.

List funding sources for a customer

Retrieve a list of funding sources that belong to a Customer. By default, all funding sources are returned unless the removed query string parameter is set to false in the request.

HTTP request

GET https://api.dwolla.com/customers/{id}/funding-sources

Request parameters

Parameter Required Type Description
id yes string Customer’s unique identifier.
removed no string Filter removed funding sources. Defaults to true. Set to false to filter out removed funding sources from list (i.e. - /customers/{id}/funding-sources?removed=false).

HTTP status and error codes

HTTP Status Message
403 Not authorized to list funding sources.
404 Customer not found.

Request and response

GET https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources"
    },
    "customer": {
      "href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
    }
  },
  "_embedded": {
    "funding-sources": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
          },
          "customer": {
            "href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
          },
          "with-available-balance": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
          }
        },
        "id": "ab9cd5de-9435-47af-96fb-8d2fa5db51e8",
        "status": "verified",
        "type": "balance",
        "name": "Balance",
        "created": "2015-10-02T21:00:28.153Z",
        "removed": false,
        "channels": []
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/98c209d3-02d6-4bee-bc0f-61e18acf0e33"
          },
          "customer": {
            "href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
          }
        },
        "id": "98c209d3-02d6-4bee-bc0f-61e18acf0e33",
        "status": "verified",
        "type": "bank",
        "bankAccountType": "checking",
        "name": "Jane Doe’s Checking",
        "created": "2015-10-02T22:03:45.537Z",
        "removed": false,
        "channels": [
            "ach"
        ],
        "fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
      }
    ]
  }
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'

funding_sources = app_token.get "#{customer_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe’s Checking"
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSources = $fsApi->getCustomerFundingSources($customerUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Jane Doe’s Checking"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'

funding_sources = app_token.get('%s/funding-sources' % customer_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Jane Doe’s Checking'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';

appToken
  .get(`${customerUrl}/funding-sources`)
  .then(res => res.body._embedded['funding-sources'][0].name); // => 'Jane Doe’s Checking'

List and search transfers for a customer

This section details how to retrieve a Customer’s list of transfers. Transaction search is supported by passing in optional querystring parameters such as: search which represents a term to search on, correlationId, startAmount, endAmount, startDate, endDate, and status.

HTTP request

GET https://api.dwolla.com/customers/{id}/transfers

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier to get transfers for.
search no string A string to be matched with firstName, lastName, email, businessName, Customer Id, and Account Id. (/transfers?search=Doe)
startAmount no string Only include transactions with an amount equal to or greater than startAmount. Can optionally be used with endAmount to specify an amount range.
endAmount no string Only include transactions with an amount equal to or less than endAmount. Can optionally be used with startAmount to specify an amount range.
startDate no string Only include transactions created after this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with endDate to specify a date range.
endDate no string Only include transactions created before than this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with startDate to specify a date range.
status no string Filter results on transaction status. Possible values: pending, processed, failed, or cancelled.
correlationId no string A string value to search on if a correlationId was specified on a transfer or mass payment item.
limit no integer Number of search results to return. Defaults to 25.
offset no integer Number of search results to skip. Used for pagination.

HTTP status and error codes

HTTP Status Message
403 Not authorized to list transfers.
404 Customer not found.

Request and response

GET http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271/transfers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "first": {
      "href": "https://api-sandbox.dwolla.com/customers/01b47cb2-52ac-42a7-926c-6f1f50b1f271/transfers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/customers/01b47cb2-52ac-42a7-926c-6f1f50b1f271/transfers?limit=25&offset=0"
    },
    "self": {
      "href": "http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271/transfers"
    }
  },
  "_embedded": {
    "transfers": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          },
          "destination": {
            "href": "https://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271"
          }
        },
        "id": "4C8AD8B8-3D69-E511-80DB-0AA34A9B2388",
        "status": "pending",
        "amount": {
          "value": "225.00",
          "currency": "USD"
        },
        "created": "2015-10-02T19:42:32.950Z",
        "metadata": {
          "foo": "bar",
          "baz": "foo"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/transfers/9DC99076-3D69-E511-80DB-0AA34A9B2388"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          },
          "destination": {
            "href": "https://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271"
          }
        },
        "id": "9DC99076-3D69-E511-80DB-0AA34A9B2388",
        "status": "pending",
        "amount": {
          "value": "225.00",
          "currency": "USD"
        },
        "created": "2015-10-02T19:40:41.437Z",
        "metadata": {
          "foo": "bar",
          "baz": "foo"
        }
      }
    ]
  },
  "total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271'

transfers = app_token.get "#{customer_url}/transfers"
transfers._embedded['transfers'][0].status # => "pending"
<?php
$customerUrl = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271';

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

$transfers = $TransfersApi->getCustomerTransfers($customerUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "pending"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271'

transfers = app_token.get('%s/transfers' % customer_url)
transfers.body['_embedded']['transfers'][0]['status'] # => 'pending'
var customerUrl = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271';

appToken
  .get(`${customerUrl}/transfers`)
  .then(res => res.body._embedded['transfers'][0].status); // => "pending"

List mass payments for a customer

This section covers how to retrieve a verified Customer’s list of previously created mass payments. Mass payments are returned ordered by date created, with most recent mass payments appearing first.

HTTP request

GET https://api.dwolla.com/customers/{id}/mass-payments

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier to get mass payments for.
limit no integer How many results to return. Defaults to 25.
offset no integer How many results to skip.
correlationId no string A string value to search on if a correlationId was specified on a mass payment.

HTTP status and error codes

HTTP Status Code Description
403 NotAuthorized Not authorized to list mass payments.
404 NotFound Customer not found.

Request and response

GET https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

....

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments?limit=25&offset=0"
    }
  },
  "_embedded": {
    "mass-payments": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/89ca72d2-63bf-4a8f-92ef-a5d00140aefa"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/e1c972d4-d8d9-4c30-861a-9081dcbaf4ab"
          },
          "items": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/89ca72d2-63bf-4a8f-92ef-a5d00140aefa/items"
          }
        },
        "id": "89ca72d2-63bf-4a8f-92ef-a5d00140aefa",
        "status": "complete",
        "created": "2016-03-21T19:27:34.000Z",
        "metadata": {
          "masspay1": "masspay1"
        },
        "correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
      }
    ]
  },
  "total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'

mass_payments = app_token.get "#{customer_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"
<?php
$customerUrl = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271';

$masspaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);

$masspayments = $masspaymentsApi->getByCustomer($customerUrl);
$masspayments->_embedded->{'mass-payments'}[0]->status; # => "complete"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'

mass_payments = app_token.get('%s/mass-payments' % customer_url)
mass_payments.body['_embedded']['mass-payments'][0]['status'] # => 'complete'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${customerUrl}/mass-payments`, { limit: 10 })
  .then(res => res.body._embedded['mass-payments'][0].status); // => "complete"

Beneficial owners

Verified Customers of type business are required to verify the identity of beneficial owners in addition to the controller of the business if they are one of the following business types:

  • Corporation
  • LLC
  • Partnership

For more information on how to add beneficial owners, or to learn more on whether certain business types are exempt, check out our beneficial owner developer resource article.

Beneficial owners resource

Parameter Description
id The beneficial owner unique identifier.
firstName The legal first name of the beneficial owner.
lastName The legal last name of the beneficial owner.
address The beneficial owner’s physical address.
verificationStatus Possible values of verified, document, or incomplete.
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/caa81a5f-ec1e-4559-8b32-d90655bfd03c",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "caa81a5f-ec1e-4559-8b32-d90655bfd03c",
    "firstName": "Joe",
    "lastName": "owner",
    "address": {
        "address1": "12345 18th st",
        "address2": "Apt 12",
        "address3": "",
        "city": "Des Moines",
        "stateProvinceRegion": "IA",
        "country": "US",
        "postalCode": "50265"
    },
    "verificationStatus": "verified"
}

Create a beneficial owner

This section details how to create a new beneficial owner. To create beneficial owners, you need to collect the beneficial owner’s full name, ssn, date of birth, and permanent address. Optionally, passport information must be included for foreign individuals that do not have a US issued SSN. Beneficial owners require additional information that will give Dwolla the ability to confirm the identity of the individual.

For more information on how to create a beneficial owner, refer to our developer resource article.

HTTP request

POST https://api.dwolla.com/customers/{id}/beneficial-owners

Request Parameters

Parameter Required Type Description
firstName yes string The legal first name of the beneficial owner.
lastName yes string The legal last name of the beneficial owner.
ssn conditional string Full nine digits of beneficial owner’s social security number. If ssn is omitted, passport is required.
dateOfBirth Yes string beneficial owner’s date of birth in YYYY-MM-DD format. Must be 18 years or older.
address Yes object An address JSON object. Full address of the controller’s physical address.
passport conditional object An optional passport JSON object. Required for non-US persons. Includes passport identification number and country.

Address JSON object

Parameter Required Type Description
address1 yes string First line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
address2 no string Second line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
address3 no string Third line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
city yes string City of beneficial owner’s permanent residence.
stateProvinceRegion yes string Two-letter US state or territory abbreviation code of beneficial owner’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
country yes string Country of beneficial owner’s permanent residence. Two digit ISO code, e.g. US.
postalCode yes string Postal code of beneficial owner’s permanent residence. Should be a five digit postal code, e.g. 50314.

Passport JSON object

Parameter Required Type Description
number conditional string Required if beneficial owner is a non-US person and has no Social Security number.
country conditional string Country of issued passport.

Request and response

POST https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "document",
  "lastName": "owner",
  "ssn": "123-46-7890",
  "dateOfBirth": "1960-11-30",
  "address": {
    "address1": "123 Main St.",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "country": "US",
    "postalCode": "10005"
  }
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$verified_customer = 'https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5';

$addOwner = $customersApi->addBeneficialOwner([
      'firstName' => 'document',
      'lastName'=> 'owner',
      'dateOfBirth' => '1990-11-11',
      'ssn' => '123-34-9876',
      'address' =>
      [
          'address1' => '18749 18th st',
          'address2' => 'apt 12',
          'address3' => '',
          'city' => 'Des Moines',
          'stateProvinceRegion' => 'IA',
          'postalCode' => '50265',
          'country' => 'US'
      ],
  ], $verified_customer);
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5'
request_body = {
  :firstName => 'John',
  :lastName => 'Doe',
  :ssn => '123-46-7890',
  :dateOfBirth => '1970-01-01',
  :address => {
    :address1 => '99-99 33rd St',
    :city => 'Some City',
    :stateProvinceRegion => 'NY',
    :country => 'US',
    :postalCode => '11101'
  }
}

beneficial_owner = app_token.post "#{customer_url}/beneficial-owners", request_body
beneficial_owner.response_headers[:location] # => "https://api-sandbox.dwolla.com/beneficial-owners/AB443D36-3757-44C1-A1B4-29727FB3111C"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  'firstName': 'John',
  'lastName': 'Doe',
  'dateOfBirth': '1970-01-01'
  'ssn': '123-46-7890'
  'address': {
    'address1': '99-99 33rd St',
    'city': 'Some City',
    'stateProvinceRegion': 'NY',
    'country': 'US'
    'postalCode': '11101'
  }
}

beneficial_owner = app_token.post('%s/beneficial-owners' % customer_url, request_body)
beneficial_owner.headers['location'] # => 'https://api-sandbox.dwolla.com/beneficial-owners/AB443D36-3757-44C1-A1B4-29727FB3111C'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8';
var requestBody = {
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1970-01-01',
  ssn: '123-56-7890',
  address: {
    address1: '99-99 33rd St',
    city: 'Some City',
    stateProvinceRegion: 'NY',
    country: 'US'
    postalCode: '11101'
  }
};

appToken
  .post(`${customerUrl}/beneficial-owners`, requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F'

Retrieve a beneficial owner

This section contains information on how to retrieve a beneficial owner which belongs to a Customer.

HTTP request

GET https://api.dwolla.com/beneficial-owners/{id}

Request parameters

Parameter Required Type Description
id yes string Beneficial owner unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY


# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8'

beneficial_owner = app_token.get beneficial_owner_url
beneficial_owner.firstName # => "Jane"
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);

$beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8';
$beneficialOwner = $beneficialOwnersApi->getById($beneficialOwnerUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8'

beneficial_owner = app_token.get(beneficial_owner_url)
beneficial_owner.body['firstName']
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';

appToken
  .get(beneficialOwnerUrl)
  .then(res => res.body.firstName); // => 'Jane'

Update a beneficial owner

This endpoint can be used to update a beneficial owner’s information to retry verification. A beneficial owner’s information can only be updated if their verification status is incomplete.

HTTP request

POST https://api.dwolla.com/beneficial-owners/{id}

Request Parameters

Parameter Required Type Description
firstName yes string The legal first name of the beneficial owner.
lastName yes string The legal last name of the beneficial owner.
ssn conditional string Full nine digits of beneficial owner’s social security number. If ssn is omitted, passport is required.
dateOfBirth Yes string beneficial owner’s date of birth in YYYY-MM-DD format. Must be 18 years or older.
address Yes object An address JSON object. Full address of the controller’s physical address.
passport conditional object An optional passport JSON object. Required for non-US persons. Includes passport identification number and country.

Address JSON object

Parameter Required Type Description
address1 yes string First line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
address2 no string Second line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
address3 no string Third line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
city yes string City of beneficial owner’s permanent residence.
stateProvinceRegion yes string Two-letter US state or territory abbreviation code of beneficial owner’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
country yes string Country of beneficial owner’s permanent residence. Two digit ISO code, e.g. US.
postalCode yes string Postal code of beneficial owner’s permanent residence. Should be a five digit postal code, e.g. 50314.

Passport JSON object

Parameter Required Type Description
number conditional string Required if beneficial owner is a non-US person and has no Social Security number.
country conditional string Country of issued passport.

Request and response

POST https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "beneficial",
  "lastName": "owner",
  "ssn": "123-54-6789",
  "dateOfBirth": "1963-11-11",
  "address": {
    "address1": "123 Main St.",
    "address2": "Apt 123",
    "city": "Des Moines",
    "stateProvinceRegion": "IA",
    "country": "US",
    "postalCode": "50309"
  }
}

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b",
    "firstName": "beneficial",
    "lastName": "owner",
    "address": {
        "address1": "123 Main St.",
        "address2": "Apt 123",
        "city": "Des Moines",
        "stateProvinceRegion": "IA",
        "country": "US",
        "postalCode": "50309"
    },
    "verificationStatus": "verified"
}
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);

$beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
$updateBeneficialOwner = $beneficialOwnersApi->update([
      'firstName' => 'beneficial',
      'lastName'=> 'owner',
      'dateOfBirth' => '1963-11-11',
      'ssn' => '123-54-6789',
      'address' =>
      [
          'address1' => '123 Main St.',
          'address2' => 'Apt 123',
          'city' => 'Des Moines',
          'stateProvinceRegion' => 'IA',
          'postalCode' => '50309',
          'country' => 'US'
      ],
  ], $beneficialOwnerUrl);

$updateBeneficialOwner->id; # => "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'
request_body = {
  :firstName => 'beneficial',
  :lastName => 'owner',
  :ssn => '123-54-6789',
  :dateOfBirth => '1963-11-11',
  :address => {
    :address1 => '123 Main St',
    :city => 'Des Moines',
    :stateProvinceRegion => 'IA',
    :country => 'US',
    :postalCode => '50309'
  }
}

update_beneficial_owner = app_token.post beneficial_owner_url, request_body
update_beneficial_owner.id # => "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'
request_body = {
  'firstName': 'beneficial',
  'lastName': 'owner',
  'dateOfBirth': '1963-11-11'
  'ssn': '123-54-6789'
  'address': {
    'address1': '123 Main St',
    'city': 'Des Moines',
    'stateProvinceRegion': 'IA',
    'country': 'US'
    'postalCode': '50309'
  }
}

update_beneficial_owner = app_token.post(beneficial_owner_url, request_body)
update_beneficial_owner.body['id'] # => '00cb67f2-768c-4ee3-ac81-73bc4faf9c2b'
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
var requestBody = {
  firstName: 'beneficial',
  lastName: 'owner',
  dateOfBirth: '1963-11-11',
  ssn: '123-54-6789',
  address: {
    address1: '123 Main St',
    city: 'Des Moines',
    stateProvinceRegion: 'IA',
    country: 'US'
    postalCode: '50309'
  }
};

appToken
  .post(beneficialOwnerUrl, requestBody)
  .then(res => res.body.id); // => '00cb67f2-768c-4ee3-ac81-73bc4faf9c2b'

HTTP status and error codes

HTTP Status Message
400 Duplicate customer or validation error.
403 Not authorized to create customers.

List beneficial owners

This section contains information on how to retrieve a list of beneficial owners that belong to a Customer.

HTTP request

GET https://api.dwolla.com/customers/{id}/beneficial-owners

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "_embedded": {
        "beneficial-owners": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/beneficial-owners/55469604-40ab-44b6-962f-de2c0837ba98",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "beneficial-owner"
                    },
                    "verify-with-document": {
                        "href": "https://api-sandbox.dwolla.com/beneficial-owners/55469604-40ab-44b6-962f-de2c0837ba98/documents",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "document"
                    }
                },
                "id": "55469604-40ab-44b6-962f-de2c0837ba98",
                "firstName": "document",
                "lastName": "owner1",
                "address": {
                    "address1": "18749 18th st",
                    "address2": "apt 12",
                    "address3": "",
                    "city": "Des Moines",
                    "stateProvinceRegion": "IA",
                    "country": "US",
                    "postalCode": "50265"
                },
                "verificationStatus": "document"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/beneficial-owners/caa81a5f-ec1e-4559-8b32-d90655bfd03c",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "beneficial-owner"
                    }
                },
                "id": "caa81a5f-ec1e-4559-8b32-d90655bfd03c",
                "firstName": "Joe",
                "lastName": "owner2",
                "address": {
                    "address1": "18749 18th st",
                    "address2": "apt 12",
                    "address3": "",
                    "city": "Des Moines",
                    "stateProvinceRegion": "IA",
                    "country": "US",
                    "postalCode": "50265"
                },
                "verificationStatus": "verified"
            }
        ]
    },
    "total": 2
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'

beneficial_owners = app_token.get "#{customer_url}/beneficial-owners"
beneficial_owners._embedded['beneficial-owners'][0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customerUrl = 'https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5';
$beneficialOwnerList = $customersApi->getBeneficialOwners($customerUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'

beneficial_owners = app_token.get('%s/beneficial-owners' % customer_url)
beneficial_owners.body['id']
var customerUrl = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';

token
  .get(`${customerUrl}/beneficial-owners`)
  .then(res => res.body._embedded['beneficial-owners'][0].id); // => '56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

Remove a beneficial owner

Delete a beneficial owner. A removed beneficial owner cannot be retrieved after being removed.

HTTP request

DELETE https://api.dwolla.com/beneficial-owners/{id}

Request parameters

Parameter Required Type Description
id yes string id of beneficial owner to delete.

HTTP status and error codes

HTTP Status Message
404 Beneficial owner not found.

Request and response

DELETE https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/0f394602-d714-4d77-9d58-3a3e8394bcdd",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "0f394602-d714-4d77-9d58-3a3e8394bcdd",
    "firstName": "B",
    "lastName": "Owner",
    "address": {
        "address1": "123 Main St.",
        "city": "New York",
        "stateProvinceRegion": "NY",
        "country": "US",
        "postalCode": "10005"
    },
    "verificationStatus": "verified"
}

...

HTTP 200 OK
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'

app_token.delete beneficial_owner_url
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';

appToken.delete(beneficialOwnerUrl);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'

app_token.delete(beneficial_owner_url)
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwner = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';
$deletedBeneficialOwner = $beneficialOwnersApi->deleteById($beneficialOwner);
?>

Retrieve beneficial ownership status

This section contains information on how to retrieve a Customer’s beneficial ownership status.

HTTP request

GET https://api.dwolla.com/customers/{id}/beneficial-ownership

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc/beneficial-ownership",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-ownership"
        }
    },
    "status": "uncertified"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

beneficial_ownership = app_token.get "#{customer_url}/beneficial-ownership"
beneficial_ownership.status # => "uncertified"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$newCustomer = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';
$customerOwnershipStatus = $customersApi->getOwnershipStatus($newCustomer);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

beneficial_ownership = app_token.get('%s/beneficial-ownership' % customer_url)
beneficial_ownership.body['status'] # => 'uncertified'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

appToken
  .get(`${customer_url}/beneficial-ownership`)
  .then(res => res.body.status); // => "uncertified"

Certify beneficial ownership

This section contains information on how to certify beneficial ownership for a business Verified Customer.

HTTP request

POST https://api.dwolla.com/customers/{id}/beneficial-ownership

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier.

Request and response

POST https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc/beneficial-ownership
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "status": "certified"
}

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc/beneficial-ownership",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-ownership"
        }
    },
    "status": "certified"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
  :status => "certified"
}

app_token.post "#{customer_url}/beneficial-ownership", request_body
var customerUrl = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
var requestBody = {
  status: 'certified'
};

appToken.post(`${customerUrl}/beneficial-ownership`, requestBody);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
    "status": "certified"
}

app_token.post('%s/beneficial-ownership' % customer_url, request_body)
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customerId = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
$certifyCustomer = $customersApi->changeOwnershipStatus(['status' => 'certified' ], $customerId);
?>

Create a document for a beneficial owner

Create a document for a beneficial owner pending verification by uploading a photo of the document. This requires a multipart form-data POST request. The file must be either a .jpg, .jpeg, .png, or .pdf up to 10MB in size.

HTTP request

POST https://api.dwolla.com/beneficial-owners/{id}/documents

Request parameters

Form Field Description
documentType One of passport, license, idCard, or other
file File contents.

Request and response

curl -X POST
\ -H "Authorization: Bearer tJlyMNW6e3QVbzHjeJ9JvAPsRglFjwnba4NdfCzsYJm7XbckcR"
\ -H "Accept: application/vnd.dwolla.v1.hal+json"
\ -H "Cache-Control: no-cache"
\ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
\ -F "documentType=passport"
\ -F "file=@foo.png"
\ 'https://api-sandbox.dwolla.com/beneficial-owners/1de32ec7-ff0b-4c0c-9f09-19629e6788ce/documents'

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

file = Faraday::UploadIO.new('mclovin.jpg', 'image/jpeg')
document = app_token.post "#{beneficial_owner_url}/documents", file: file, documentType: 'license'
document.response_headers[:location] # => "https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

document = app_token.post('%s/documents' % customer_url, file = open('mclovin.jpg', 'rb'), documentType = 'license')
document.headers['location'] # => 'https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16'
/**
 * No example for this language yet.
 **/
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE';

var requestBody = new FormData();
body.append('file', fs.createReadStream('mclovin.jpg'), {
  filename: 'mclovin.jpg',
  contentType: 'image/jpeg',
  knownLength: fs.statSync('mclovin.jpg').size
});
body.append('documentType', 'license');

appToken
  .post(`${beneficialOwnerUrl}/documents`, requestBody)
  .then(res => res.headers.get('location')); // => "https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"

Retrieve a document for a beneficial owner

This section contains information on how to retrieve a document by its id.

HTTP request

GET https://api.dwolla.com/documents/{id}

Request parameters

Parameter Required Type Description
id yes string Document unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
    }
  },
  "id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
  "status": "pending",
  "type": "passport",
  "created": "2015-09-29T21:42:16.000Z"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

document = app_token.get document_url
document.type # => "passport"
<?php
$documentUrl = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

$documentsApi = new DwollaSwagger\DocumentsApi($apiClient);

$document = $documentsApi->getDocument($documentUrl);
$document->type; # => "passport"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

documents = app_token.get(document_url)
documents.body['type'] # => 'passport'
var documentUrl = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

appToken
  .get(document_url)
  .then(res => res.body.type); // => "passport"

List documents for beneficial owners

This section contains information on how to retrieve a list of documents that belong to a beneficial owner.

HTTP request

GET https://api.dwolla.com/beneficial-owners/{id}/documents

Request parameters

Parameter Required Type Description
id yes string Beneficial owner unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents"
    }
  },
  "_embedded": {
    "documents": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
          }
        },
        "id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
        "status": "pending",
        "type": "passport",
        "created": "2015-09-29T21:42:16.000Z"
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0"
          }
        },
        "id": "11fe0bab-39bd-42ee-bb39-275afcc050d0",
        "status": "pending",
        "type": "passport",
        "created": "2015-09-29T21:45:37.000Z"
      }
    ]
  },
  "total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2'

documents = token.get "#{beneficial_owner_url}/documents"
documents._embedded['documents'][0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwner = 'https://api-sandbox.dwolla.com/beneficial-owners/55469604-40ab-44b6-962f-de2c0837ba98';
$listDocsBeneficialOwner = $beneficialOwnersApi->getBeneficialOwnerDocuments($beneficialOwner);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2'

documents = app_token.get('%s/documents' % beneficial_owner_url)
documents.body['total'] # => 2
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2';

token
  .get(`${beneficialOwnerUrl}/documents`)
  .then(res => res.body._embedded['documents'][0].id); // => '56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

Documents

Verified Customers of type personal or business and of status document require photos of identifying documents to be uploaded for manual review in order to be verified. Currently, SDK support for document upload only exists for Ruby, Node.js, and Python. To upload a document using other languages, you must use an external HTTP library.

For more information on handling the Customer verification status of document, reference our Customer verification resource article.

Document resource

Parameter Description
id Document unique identifier
type Either passport, license, idCard, or other.
status Either pending or reviewed. When a document has been manually reviewed by Dwolla, its status will be reviewed. A reviewed document does not necessarily indicate that the customer has completed the identity verification process.
created ISO 8601 Timestamp of document upload time and date.
failureReason The reason an uploaded document was rejected. Can be: ScanNotReadable, ScanNotUploaded, ScanIdTypeNotSupported, or ScanNameMismatch.
{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
    }
  },
  "id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
  "status": "pending",
  "type": "passport",
  "created": "2015-09-29T21:42:16.000Z"
}

Create a document

Create a document for a Customer pending verification by uploading a photo of the document. This requires a multipart form-data POST request. The file must be either a .jpg, .jpeg, .png, or .pdf up to 10MB in size.

HTTP request

POST https://api.dwolla.com/customers/{id}/documents

Request Parameters

Form Field Description
documentType Acceptable values of: passport, license, idCard, or other
file File contents.

HTTP status and error codes

HTTP Status Code Description
201 Created A document resource was created.
400 maximumNumberOfResources Max of four files upload allowed. Please wait for Dwolla to manually check the documents.
400 invalidFileType File types supported: .jpg, .jpeg, .png, or .pdf.
403 invalidResourceState Resource cannot be modified. Document creation not allowed for already verified Customers or non-verified Customer types.
403 notAuthorized Not authorized to create documents.
404 notFound Customer not found. Check CustomerId.
413 fileTooLarge Document requests are limited to 10 mb.

Request and response

curl -X POST
\ -H "Authorization: Bearer tJlyMNW6e3QVbzHjeJ9JvAPsRglFjwnba4NdfCzsYJm7XbckcR"
\ -H "Accept: application/vnd.dwolla.v1.hal+json"
\ -H "Cache-Control: no-cache"
\ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
\ -F "documentType=passport"
\ -F "file=@foo.png"
\ 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE/documents'

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0
customer_url = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

file = Faraday::UploadIO.new('mclovin.jpg', 'image/jpeg')
document = app_token.post "#{customer_url}/documents", file: file, documentType: 'license'
document.response_headers[:location] # => "https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

document = app_token.post('%s/documents' % customer_url, file = open('mclovin.jpg', 'rb'), documentType = 'license')
document.headers['location'] # => 'https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16'
/**
 * No example for this language yet.
 **/
var customerUrl = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE';

var requestBody = new FormData();
body.append('file', fs.createReadStream('mclovin.jpg'), {
  filename: 'mclovin.jpg',
  contentType: 'image/jpeg',
  knownLength: fs.statSync('mclovin.jpg').size
});
body.append('documentType', 'license');

appToken
  .post(`${customerUrl}/documents`, requestBody)
  .then(res => res.headers.get('location')); // => "https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"

List documents

This section contains information on how to retrieve a list of documents that belong to a Customer.

HTTP request

GET https://api.dwolla.com/customers/{id}/documents

Request parameters

Parameter Required Type Description
id yes string Customer unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents"
    }
  },
  "_embedded": {
    "documents": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
          }
        },
        "id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
        "status": "pending",
        "type": "passport",
        "created": "2015-09-29T21:42:16.000Z"
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0"
          }
        },
        "id": "11fe0bab-39bd-42ee-bb39-275afcc050d0",
        "status": "pending",
        "type": "passport",
        "created": "2015-09-29T21:45:37.000Z"
      }
    ]
  },
  "total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'

documents = app_token.get "#{customer_url}/documents"
documents._embedded['documents'][0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';

$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->getCustomerDocuments($customerUrl);
$customer->total; # => 2
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'

documents = app_token.get('%s/documents' % customer_url)
documents.body['total'] # => 2
var customerUrl = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';

token
  .get(`${customerUrl}/documents`)
  .then(res => res.body._embedded['documents'][0].id); // => '56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

Retrieve a document

This section contains information on how to retrieve a document by its id.

HTTP request

GET https://api.dwolla.com/documents/{id}

Request parameters

Parameter Required Type Description
id yes string Document unique identifier.

Request and response

GET https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
    }
  },
  "id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
  "status": "pending",
  "type": "passport",
  "created": "2015-09-29T21:42:16.000Z"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

document = app_token.get document_url
document.type # => "passport"
<?php
$documentUrl = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

$documentsApi = new DwollaSwagger\DocumentsApi($apiClient);

$document = $documentsApi->getDocument($documentUrl);
$document->type; # => "passport"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

documents = app_token.get(document_url)
documents.body['type'] # => 'passport'
var documentUrl = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

appToken
  .get(document_url)
  .then(res => res.body.type); // => "passport"

Funding sources

Add and retrieve ACH bank account information via funding sources. Customers can have a maximum of 6 funding sources. Funding sources can be created for both the Accounts and Customers resources.

Link Description
self URL of the funding source resource.
customer GET this link to retrieve details of the Customer.
remove POST to this link to remove the funding source from the Customer.
balance (Verified Customer only) GET this link to retrieve the amount available in the balance of the Customer’s Balance funding source.
transfer-from-balance (Verified Customer only) if this link exists, the Customer can transfer funds from their balance.
transfer-to-balance (Verified Customer only) if this link exists, funds can be transferred to the Customer’s balance.
transfer-send If this link exists, the Customer can send funds to another Customer.
transfer-receive The Customer can receive funds from another Customer.
initiate-micro-deposits POST to this link to initiate micro-deposits on an unverified funding source.
verify-micro-deposits Micro-deposits have completed to this funding source and are eligible for verification. POST to this link with the verify micro-deposit amounts and complete bank funding source verification.
failed-verification-micro-deposits Micro-deposits attempts have failed due to too many failed attempts. Remove the bank and re-add to attempt verification again.

Funding source resource

Parameter Description
id The funding source unique identifier.
status Possible values are unverified or verified. Determines if the funding source has completed verification.
type Type of funding source. Possible values are bank or balance.
bankAccountType An optional attribute for bank funding sources that determines the type of account. Possible values are checking or savings.
name Arbitrary nickname for the funding source.
created ISO-8601 timestamp for when the funding source was created.
balance An optional object that includes value and currency parameters. value is a string value for the amount available and currency is a string value currency code. Only returned for a Dwolla API Customer account balance.
removed Determines if the funding source has been removed. A boolean true if the funding source was removed or false if the funding source is not removed.
channels List of processing channels. ACH is the default processing channel for bank transfers. Possible values are ach or wire.
bankName The financial institution name.
iavAccountHolders An optional object that includes optional selected and other parameters. selected, a string with the account holder name(s) on file with the financial institution for the IAV selected account. other, a list of strings with name(s) of other accounts on file. Only returned for a Customer that added a bank using Dwolla IAV, and if names are returned for the selected bank account.
fingerprint Fingerprint is an optional unique identifying string value returned for funding sources of type bank. This attribute can be used to check across all Dwolla API Customers if two bank accounts share the same account number and routing number. Removing a funding source does not remove the fingerprint.
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/fc84223a-609f-42c9-866e-2c98f17ab4fb",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "customer": {
            "href": "https://api-sandbox.dwolla.com/customers/241ec287-8d7a-4b69-911e-ffbea98d75ce",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        }
    },
    "id": "fc84223a-609f-42c9-866e-2c98f17ab4fb",
    "status": "verified",
    "type": "bank",
    "bankAccountType": "checking",
    "name": "Your Account #1 - CHECKING",
    "created": "2017-08-16T20:06:34.000Z",
    "removed": false,
    "channels": [
        "ach"
    ],
    "bankName": "SANDBOX TEST BANK",
    "iavAccountHolders": {
        "selected": "account holder",
        "other": [
          "Jane Doe",
          "GeneriCompany LLC"
        ]
    },
    "fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
}

Retrieve a funding source

This section covers how to retrieve a funding source by id.

HTTP request

GET https://api.dwolla.com/funding-sources/{id}

Request parameters

Parameter Required Type Description
id yes string id of funding source to retrieve.

HTTP status and error codes

HTTP Status Message
404 Funding source not found.

Request and response

GET https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "customer": {
            "href": "https://api-sandbox.dwolla.com/customers/4594a375-ca4c-4220-a36a-fa7ce556449d",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "initiate-micro-deposits": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31/micro-deposits",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "micro-deposits"
        }
    },
    "id": "49dbaa24-1580-4b1c-8b58-24e26656fa31",
    "status": "unverified",
    "type": "bank",
    "bankAccountType": "checking",
    "name": "Test checking account",
    "created": "2017-09-26T14:14:08.000Z",
    "removed": false,
    "channels": [
        "ach"
    ],
    "bankName": "SANDBOX TEST BANK",
    "fingerprint": "5012989b55af15400e8102f95d2ec5e7ce3aef45c01613280d80a236dd8d6c3a"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31'

funding_source = app_token.get funding_source_url
funding_source.name # => "Test checking account"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fsApi->id($fundingSourceUrl);
$fundingSource->name; # => "Test checking account"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31'

funding_source = app_token.get(funding_source_url)
funding_source.body['name'] # => 'Test checking account'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31';

appToken
  .get(fundingSourceUrl)
  .then(res => res.body.name); // => "Test checking account"

Update a funding source

This section covers how to update a bank funding source. The accountNumber, routingNumber, type and name are all optional attributes that can be updated on a funding source when it has an unverified status. You can choose to update only name, name and routingNumber, name and accountNumber, name and type or all four attributes. Any attribute that isn’t updated remains the same as it was prior to update, including the funding source id. The name attribute can be updated when a funding source has either an unverified or verified status.

HTTP request

POST https://api.dwolla.com/funding-sources/{id}

Request parameters

Parameter Required Type Description
id yes string id of funding source to update.
name no string Arbitrary nickname for the funding source. Must be 50 characters or less.
bankAccountType no string Type of bank account: checking or savings.
routingNumber no string The bank account’s routing number.
accountNumber no string The bank account number.

HTTP Status and Error Codes

HTTP Status Code Description
404 NotFound Funding source not found.
400 ValidationError Only funding sources of type=“bank” can be updated.
400 ValidationError Invalid bank name.
403 InvalidResourceState A removed bank cannot be updated.

Request and response

POST https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "name": "Test Checking - 1234"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
      "name" => "Test Checking - 1234",
}

funding_source = app_token.post "#{funding_source_url}", request_body
funding_source.name # => "Test Checking - 1234"
/**
 *  No example for this language yet. Coming soon.
 **/
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
  "name": "Test Checking - 1234"
}

funding_source = app_token.post(funding_source_url, request_body)
funding_source.body['name'] # => 'Test Checking - 1234'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
  name: "Test Checking - 1234"
};

appToken
  .post(fundingSourceUrl, requestBody)
  .then(res => res.body.name); // => "Test Checking - 1234"

Retrieve a funding source balance

This section covers how to retrieve the balance of a funding source. The funding source type balance only exists for Verified Customer accounts and represents a balance held in the Dwolla network.

HTTP request

GET https://api.dwolla.com/funding-sources/{id}/balance

Request parameters

Parameter Required Type Description
id yes string id of funding source to retrieve a balance for.

HTTP status and error codes

HTTP Status Code Description
404 NotFound Funding source not found.

Request and response

GET https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418/balance
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418/balance",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "balance"
    },
    "funding-source": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "funding-source"
    }
  },
  "balance": {
    "value": "4616.87",
    "currency": "USD"
  },
  "lastUpdated": "2017-04-18T15:20:25.880Z"
}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source = app_token.get "#{funding_source_url}/balance"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fsApi->getBalance($fundingSourceUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418'

funding_source = app_token.get('%s/balance' % funding_source_url)
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418';

appToken
  .get(`${fundingSourceUrl}/balance`)
  .then(res => res.body.balance.amount);

Initiate micro-deposits

This section covers how to initiate micro-deposits for bank verification. Reference the funding source verification resource article for more information on the micro-deposit method of bank account verification.

HTTP request

POST https://api.dwolla.com/funding-sources/{id}/micro-deposits

Request parameters

Parameter Required Type Description
id yes string id of funding source to initiate micro-deposits to.

HTTP status and error codes

HTTP Status Code Description
201 Created Micro-deposits initiated, will take 1-2 days to settle to destination bank.
404 NotFound Funding source not found

Request and response

POST https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
Authorization: Bearer 8tJjM7iTjujLthkbVPMUcHLqMNw4uv5kG712g9j1RRBHplGpwo
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'

app_token.post "#{funding_source_url}/micro-deposits"
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';

appToken.post(`${fundingSourceUrl}/micro-deposits`);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'

app_token.post('%s/micro-deposits' % funding_source_url)
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fsApi->microDeposits(null, $fundingSourceUrl);
?>

Verify micro-deposits

This section covers how to verify micro-deposits for bank verification. Reference the funding source verification resource article for more information on the micro-deposit method of bank account verification.

HTTP request

POST https://api.dwolla.com/funding-sources/{id}/micro-deposits

Request parameters

Parameter Required Type Description
id yes string id of funding source to verify micro-deposits on.
amount1 yes string An amount JSON object of first micro-deposit. Contains value and currency.
amount2 yes string An amount JSON object of second micro-deposit. Contains value and currency.

HTTP status and error codes

HTTP Status Code Description
200 OK Micro-deposits successfully verified.
202 TryAgainLater Micro-deposits have not have not settled to destination bank. A Customer can verify these amounts after micro-deposits have processed to their bank.
400 ValidationError InvalidAmount, “Wrong amount(s).”
403 InvalidResourceState “Too many attempts.”, “Bank already verified.”
404 NotFound Micro-deposits not initiated,Funding source not found
500 Unknown “Verify micro-deposits returned an unknown error.”

Request and response

POST https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
Authorization: Bearer 8tJjM7iTjujLthkbVPMUcHLqMNw4uv5kG712g9j1RRBHplGpwo
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json

{
    "amount1": {
        "value": "0.03",
        "currency": "USD"
    },
    "amount2": {
        "value": "0.09",
        "currency": "USD"
    }
}

HTTP 200 OK
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
  :amount1 => {
    :value => "0.03",
    :currency => "USD"
  },
  :amount2 => {
    :value => "0.09",
    :currency => "USD"
  }
}

app_token.post "#{funding_source_url}/micro-deposits", request_body
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
var requestBody = {
  amount1: {
    value: '0.03',
    currency: 'USD'
  },
  amount2: {
    value: '0.09',
    currency: 'USD'
  }
};

appToken.post(`${fundingSourceUrl}/micro-deposits`, requestBody);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
    "amount1": {
        "value": "0.03",
        "currency": "USD"
    },
    "amount2": {
        "value": "0.09",
        "currency": "USD"
    }
}

app_token.post('%s/micro-deposits' % funding_source_url, request_body)
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fsApi->microDeposits([
  'amount1' => [
    'value' => '0.03',
    'currency' => 'USD'
  ],
  'amount2' => [
    'value' => '0.09',
    'currency' => 'USD'
  ]],
  $fundingSourceUrl
);
?>

Retrieve micro-deposits details

This section shows how to retrieve the status of micro-deposits and check if micro-deposits are eligible for verification. If the status of micro-deposits is failed, a failure object will be returned in the response body which includes the ACH return code and description.

HTTP request

GET https://api.dwolla.com/funding-sources/{id}/micro-deposits

Request parameters

Parameter Required Type Description
id no string id of funding source to check status of validation deposits.

Micro-deposits object

Attribute Description
_links A _links JSON object
created ISO-8601 timestamp
status Possible values: pending, processed, or failed. pending represents micro-deposits initiated and are en route to their destination. processed represents micro-deposits have reached the destination account and are awaiting verification. failed represents micro-deposits failed to clear successfully to the destination.
failure Determines if micro-deposits fail to complete to a bank. Failure is an object that contains a code and description, which represents the ACH return code and description of the return.

HTTP status and error codes

HTTP Status Code Description
200 Ok Pending micro-deposits exist.

Request and response

GET https://api-sandbox.dwolla.com/funding-sources/dfe59fdd-7467-44cf-a339-2020dab5e98a/micro-deposits
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/dfe59fdd-7467-44cf-a339-2020dab5e98a/micro-deposits",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "micro-deposits"
    },
    "verify-micro-deposits": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/dfe59fdd-7467-44cf-a339-2020dab5e98a/micro-deposits",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "micro-deposits"
    }
  },
  "created": "2016-12-30T20:56:53.000Z",
  "status": "failed",
  "failure": {
    "code": "R03",
    "description": "No Account/Unable to Locate Account"
  }
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

funding_source = app_token.get "#{funding_source_url}/micro-deposits"
funding_source.status # => "failed"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fsApi->verifyMicroDepositsExist($fundingSourceUrl);
$fundingSource->status; # => "failed"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

funding_source = app_token.get('%s/micro-deposits' % funding_source_url)
funding_source.body['status'] # => 'failed'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

appToken
  .get(`${fundingSourceUrl}/micro-deposits`)
  .then(res => res.body.status); // => "failed"

Remove a funding source

Remove a funding source by id. A removed funding source is soft deleted and can still be accessed when retrieved.

HTTP request

POST https://api.dwolla.com/funding-sources/{id}

Request parameters

Parameter Required Type Description
id yes string id of funding source to delete.
removed yes string Specify a value of true to remove the associated funding source.

HTTP status and error codes

HTTP Status Message
404 Funding source not found.

Request and response

POST https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
    "removed": true
}

...

HTTP 200 OK
{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c",
      "type": "funding-source"
    }
  },
  "id": "692486f8-29f6-4516-a6a5-c69fd2ce854c",
  "status": "verified",
  "type": "bank",
  "bankAccountType": "checking",
  "name": "Test bank account",
  "created": "2016-06-08T21:37:30.000Z",
  "removed": true,
  "fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

request_body = {
  :removed => true
}

app_token.post "#{funding_source_url}", request_body
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fsApi->softDelete(['removed' => true ], $fundingSourceUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
  "removed": True
}

funding_source = app_token.post(funding_source_url, request_body)
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
  removed: true
};

appToken.post(fundingSourceUrl, requestBody);

Transfers

A transfer represents money being transferred from a source to a destination. Transfers are available for the Customer and Account resources.

Link Description
self URL of the transfer.
source GET this link to retrieve the Customer that was the source of the transfer.
destination GET this link to retrieve the Customer that was the destination of the transfer.
source-funding-source GET this link to retrieve the funding source that was the source of the transfer.
destination-funding-source GET this link to retrieve the funding source that was the destination of the transfer.
cancel POST to this link to cancel the transfer (A bank transfer is cancellable up until 4pm CT on that same business day if the transfer was initiated prior to 4PM CT. If a transfer was initiated after 4pm CT, it can be cancelled anytime before 4pm CT on the following business day.)
fees GET this link to retrieve the facilitator fees associated with the transfer.

Transfer resource

Parameter Description
id Transfer unique identifier.
status Either processed, pending, cancelled, or failed.
amount An amount JSON object. See below.
created ISO-8601 timestamp.
metadata A metadata JSON object
clearing A clearing JSON object.
correlationId A unique string value attached to a transfer resource which can be used for traceability between Dwolla and your application.
individualAchId The individual identifier for that ACH entry, a unique string value matching the value on bank line related to the transfer. Appears when the debit entry clears out of the bank.
{
  "_links": {},
  "_embedded": {},
  "id": "string",
  "status": "string",
  "amount": {
    "value": "string",
    "currency": "string"
  },
  "created": "string",
  "metadata": {
    "key": "value"
    },
  "clearing": {
    "source": "standard",
    "destination": "next-available"
  },
  "correlationId": "string"
}

Initiate a transfer

This section covers how to initiate a transfer from either a Dwolla Account or Dwolla API Customer resource.

HTTP request

POST https://api.dwolla.com/transfers

Request parameters

Parameter Required Type Description
_links yes object A _links JSON object describing the desired source and destination of a transfer. Reference the Source and Destination object to learn more about possible values for source and destination.
amount yes object An amount JSON object. Reference the amount JSON object to learn more.
metadata no object A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters).
fees no array An array of fee JSON objects that contain unique fee transfers. Reference the facilitator fee JSON object to learn more.
clearing no object A clearing JSON object that contains source and destination keys. Reference the clearing JSON object to learn more.
achDetails no object An ACH details JSON object which represents additional information sent along with a transfer to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. Reference the achDetails JSON object to learn more
correlationId no string A unique string value attached to a transfer which can be used for traceability between Dwolla and your application. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _.

Source and destination types

Source types
Source Type URI Description
Funding source https://api.dwolla.com/funding-sources/{id} A bank or balance funding source.
Destination types
Destination Type URI Description
Funding source https://api.dwolla.com/funding-sources/{id} Destination of an Account or verified Customer’s own bank or balance funding source. OR A Customer’s bank funding source.
Customer https://api.dwolla.com/customers/{id} Destination Customer of a transfer.
Account https://api.dwolla.com/accounts/{id} Destination Account of a transfer.

amount JSON object

Parameter Required Type Description
value yes string Amount of money
currency yes string Possible values: USD

Facilitator fee JSON object

The facilitator fee is a feature allowing for a flat rate amount to be removed from a payment as a fee, and sent to the creator of the Dwolla application. The fee does not affect the original payment amount, and exists as a separate Transfer resource with a unique transfer ID. Within a transfer request you can specify an optional fees request parameter, which is an array of fee objects that can represent many unique fee transfers.

For more information on collecting fees on payments, reference the facilitator fee resource article.

Parameter Description
_links Contains a charge-to JSON object with a link to the associated source or destination Customer or Account resource.
amount Amount of fee to charge. An amount JSON object. See above

Facilitator fee example:

"fees": [
  {
    "_links": {
      "charge-to": {
        "href": "https://api-sandbox.dwolla.com/customers/d795f696-2cac-4662-8f16-95f1db9bddd8"
      }
    },
    "amount": {
      "value": "4.00",
      "currency": "USD"
    }
  }
]

clearing JSON object

The clearing object is used in tandem with our expedited transfer feature. Source specifies the clearing time for the source funding source involved in the transfer, and can be used to downgrade the clearing time from the default of Next-day ACH. Destination specifies the clearing time for the destination funding source involved in the transfer, and can be used to upgrade the clearing time from the default of Standard ACH to Same-day ACH. Note: The clearing request parameter is a premium feature available for Dwolla customers. Next-day ACH functionality must be enabled.

Parameter Required Type Description
source no string Represents a clearing object for next-day debits into the Dwolla network.
Possible values: standard
destination no string Represents a clearing object for same-day credits out of the Dwolla network to a bank funding source.
Possible values: next-available

Clearing example:

"clearing": {
  "source": "standard",
  "destination": "next-available"
}

achDetails and addenda object

The addendum record is used to provide additional information to the payment recipient about the payment. This value will be passed in on a transfer request and can be exposed on a Customer’s bank statement. Addenda records provide a unique opportunity to supply your customers with more information about their transactions. Allowing businesses to include additional details about the transaction—such as invoice numbers—provides their end users with more information about the transaction in the comfort of their own banking application.

achDetails object
Parameter Required Type Description
source no object Represents information that is sent to a source/originating bank account along with a transfer. Include information within this JSON object for customizing details on ACH debit transfers. Can include an addenda JSON object.
destination no object Represents information that is sent to a destination/receiving bank account along with a transfer. Include information within this JSON object for customizing details on ACH credit transfers. Can include an addenda JSON object.
addenda object
Parameter Required Type Description
addenda no object An addenda object contains a values key which is an array of comma separated string addenda values. Addenda record information is used for the purpose of transmitting transfer-related information. Values must be less than or equal to 80 characters and can include spaces. Acceptable characters are: a-Z, 0-9, and special characters - _ . ~! * ' ( ) ; : @ & = + $ , / ? % # [ ]. Will not show up on bank statements from balance-sourced transfers

achDetails with addenda example:

"achDetails": {
  "source": {
    "addenda": {
      "values": ["ABC123_AddendaValue"]
    }
  },
  "destination": {
    "addenda": {
      "values": ["ZYX987_AddendaValue"]
    }
  }
}

HTTP status and error codes

HTTP Status Error Message Description
201 Created. A transfer was created.
400 Funding source not found. Double check the funding source Id, and make sure you are using the correct funding source Id.
400 Invalid funding source. The source funding source must be verified in order to send funds. Make sure your source funding source is verified.
400 Metadata not supported for this type of transfer. Metadata is unable to be passed in on transfers with a Balance Funding Source.
400 Sender // Receiver Restricted. The source or destination Customer is either deactivated or suspended and not eligible for transfers.
401 Invalid access token Access token not valid. Generate a new one and try again.
403 Forbidden Not authorized to create a transfer.

Request and response

The reference example below shows what a request looks like when sending a transfer. Please note this example is using same-day clearing to a Dwolla API Customer’s bank account, part of Dwolla’s API.

POST https://api-sandbox.dwolla.com/transfers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77

{
   "_links": {
       "source": {
           "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
       },
       "destination": {
           "href": "https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8"
       }
   },
   "amount": {
       "currency": "USD",
       "value": "10.00"
   },
   "metadata": {
       "paymentId": "12345678",
       "note": "payment for completed work Dec. 1"
   },
   "fees": [
       {
          "_links":{
             "charge-to":{
                "href":"https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4"
             }
          },
          "amount":{
             "value":"2.00",
             "currency":"USD"
          }
       }
   ],
   "clearing": {
       "destination": "next-available"
   },
    "achDetails": {
        "source": {
            "addenda": {
                "values": ["ABC123_AddendaValue"]
            }
        },
        "destination": {
            "addenda": {
                "values": ["ZYX987_AddendaValue"]
            }
        }
     },
 "correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :_links => {
    :source => {
      :href => "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    },
    :destination => {
      :href => "https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8"
    }
  },
  :amount => {
    :currency => "USD",
    :value => "1.00"
  },
  :metadata => {
    :paymentId => "12345678",
    :note => "payment for completed work Dec. 1"
  },
  :clearing => {
    :destination => "next-available"
  },
  :achDetails => {
    :source => {
      :addenda => {
        :values => "ABC123_AddendaValues"
      }
    },
    :destination => {
      :addenda => {
        :values => "ZYX987_AddendaValues"
      }
    }
  },
  :correlationId => "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}

transfer = app_token.post "transfers", request_body
transfer.response_headers[:location] # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
<?php
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);

$transfer = $transfersApi->create([
  '_links' => [
    'source' => [
      'href' => 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4',
    ],
    'destination' => [
      'href' => 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
    ]
  ],
  'amount' => [
    'currency' => 'USD',
    'value' => '1.00'
  ],
  'metadata' => [
    'paymentId' => '12345678',
    'note' => 'payment for completed work Dec. 1',
  ],
  'clearing' => [
    'destination' => 'next-available'
  ],
  'correlationId' => '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
]);
$transfer; # => "https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  '_links': {
    'source': {
      'href': 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    },
    'destination': {
      'href': 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
    }
  },
  'amount': {
    'currency': 'USD',
    'value': '1.00'
  },
  'metadata': {
    'paymentId': '12345678',
    'note': 'payment for completed work Dec. 1'
  },
  'clearing': {
    'destination': 'next-available'
  },
  'achDetails': {
    'source': {
      'addenda': {
        'values': ["ABC123_AddendaValues"]
      }
    },
    'destination': {
      'addenda': {
        'values': ["ZYX987_AddendaValues"]
      }
    }
  },
  'correlationId': '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
}

transfer = app_token.post('transfers', request_body)
transfer.headers['location'] # => 'https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'
var requestBody = {
  _links: {
    source: {
      href: 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    },
    destination: {
      href: 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
    }
  },
  amount: {
    currency: 'USD',
    value: '1.00'
  },
  metadata: {
    paymentId: '12345678',
    note: 'payment for completed work Dec. 1'
  },  
  clearing: {
    destination: 'next-available'
  },
  addenda: {
    source: {
      addenda: {
        values: ["ABC123_AddendaValue"]
      }
    },
    destination: {
      addenda: {
        values: ["ZYX987_AddendaValue"]
      }
    }
  },
  correlationId: '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
};

appToken
  .post('transfers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'

Retrieve a transfer

This section covers how to retrieve a transfer belonging to an Account or Customer by its id.

HTTP request

GET https://api.dwolla.com/transfers/{id}

Request parameters

Parameter Required Type Description
id yes string The id of the transfer to be retrieved.

HTTP status and error codes

HTTP Status Message
404 Transfer not found.

Request and response

GET https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388"
    },
    "source": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "destination": {
      "href": "https://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271"
    }
  },
  "id": "4C8AD8B8-3D69-E511-80DB-0AA34A9B2388",
  "status": "pending",
  "amount": {
    "value": "225.00",
    "currency": "USD"
  },
  "created": "2015-10-02T19:42:32.950Z",
  "metadata": {
    "foo": "bar",
    "baz": "foo"
  }
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388'

transfer = app_token.get transfer_url
transfer.status # => "pending"
<?php
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388';

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

$transfer = $transfersApi->byId($transferUrl);
$transfer->status; # => "pending"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388'

transfer = account_token.get(transfer_url)
transfer.body['status'] # => 'pending'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388';

appToken
  .get(transferUrl)
  .then(res => res.body.status); // => 'pending'

List fees for a transfer

This section outlines how to retrieve fees charged on a created transfer. Fees are visible to the Customer or Account that is charged the fee, as well as the Dwolla Account that is involved in receiving the fee.

HTTP request

GET https://api.dwolla.com/transfers/{id}/fees

Request parameters

Parameter Required Type Description
id yes string The id of the transfer to retrieve fees for.

HTTP status and error codes

HTTP Status Message
404 Transfer not found.

Request and response

GET https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388/fees
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "transactions": [
    {
      "_links": {
        "self": {
          "href": "https://api-sandbox.dwolla.com/transfers/416a2857-c887-4cca-bd02-8c3f75c4bb0e"
        },
        "source": {
          "href": "https://api-sandbox.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd"
        },
        "destination": {
          "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
        },
        "created-from-transfer": {
          "href": "https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388"
        }
      },
      "id": "416a2857-c887-4cca-bd02-8c3f75c4bb0e",
      "status": "pending",
      "amount": {
        "value": "2.00",
        "currency": "usd"
      },
      "created": "2016-02-22T20:46:38.777Z"
    },
    {
      "_links": {
        "self": {
          "href": "https://api-sandbox.dwolla.com/transfers/e58ae1f1-7007-47d3-a308-7e9aa6266d53"
        },
        "source": {
          "href": "https://api-sandbox.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd"
        },
        "destination": {
          "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
        },
        "created-from-transfer": {
          "href": "https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388"
        }
      },
      "id": "e58ae1f1-7007-47d3-a308-7e9aa6266d53",
      "status": "pending",
      "amount": {
        "value": "1.00",
        "currency": "usd"
      },
      "created": "2016-02-22T20:46:38.860Z"
    }
  ],
  "total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

fees = app_token.get "#{transfer_url}/fees"
fees.total # => 2
<?php
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

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

$transferFees = $transfersApi->getFeesBySource($transferUrl);
$transferFees->total; # => "2"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

fees = app_token.get('%s/fees' % transfer_url)
fees.body['total'] # => 2
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

appToken
  .get(`${transferUrl}/fees`)
  .then(res => res.body.total); // => 2

Retrieve a transfer failure reason

When a bank transfer fails for an Account or Customer, Dwolla returns a failure link when retrieving the transfer by its Id. This failure link is used to retrieve the ACH return code and description. For reference, the list of possible failure codes and descriptions are shown in the Transfer failures resource article.

Note: If a transfer fails to/from a bank account then the bank will automatically be removed from the Dwolla system for all ACH return codes except an R01.

HTTP Request

GET https://api.dwolla.com/transfers/{id}/failure

Request parameters

Parameter Required Type Description
id yes string Transfer unique identifier.

Request and Response

GET https://api-sandbox.dwolla.com/transfers/e6d9a950-ac9e-e511-80dc-0aa34a9b2388/failure
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/transfers/E6D9A950-AC9E-E511-80DC-0AA34A9B2388/failure"
    }
  },
  "code": "R01",
  "description": "Insufficient Funds"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

failure = app_token.get "#{transfer_url}/failure"
failure.code # => "R01"
<?php
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

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

$transferFailure = $transfersApi->failureById($transferUrl);
$transferFailure->code; # => "R01"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

failure = app_token.get('%s/failure' % transfer_url)
failure.body['code'] # => 'R01'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

appToken
  .get(`${transferUrl}/failure`)
  .then(res => res.body.code); // => 'R01'

Cancel a transfer

When a bank transfer is eligible for cancellation, Dwolla returns a cancel link when getting the transfer by Id. This cancel link is used to trigger the cancellation, preventing the bank transfer from processing further. A bank transfer is cancellable up until 4pm CT on that same business day if the transfer was initiated prior to 4PM CT. If a transfer was initiated after 4pm CT, it can be cancelled anytime before 4pm CT on the following business day.

HTTP Request

POST https://api.dwolla.com/transfers/{id}

Request parameters

Parameter Required Type Description
status yes string Possible value: cancelled.

Request and Response

POST https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
    "status": "cancelled"
}

...

{
  "_links": {
    "cancel": {
      "href": "https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388"
    },
    "source": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "funding-transfer": {
      "href": "https://api-sandbox.dwolla.com/transfers/3c48c13a-0fc6-e511-80de-0aa34a9b2388"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388"
    },
    "destination": {
      "href": "https://api-sandbox.dwolla.com/customers/05e267e5-c13d-491a-93a8-da52b721f123"
    }
  },
  "id": "3d48c13a-0fc6-e511-80de-0aa34a9b2388",
  "status": "cancelled",
  "amount": {
    "value": "22.00",
    "currency": "USD"
  },
  "created": "2016-01-28T22:34:02.663Z",
  "metadata": {
    "foo": "bar",
    "baz": "boo"
  }
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388'
request_body = {
      "status" => "cancelled",
}

transfer = app_token.post "#{transfer_url}", request_body
transfer.status # => "cancelled"
<?php
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);

$transferUrl = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388';
$transfer = $transfersApi->update([
  'status' => 'cancelled',
], $transferUrl);

$transfer->status; # => "cancelled"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388'
request_body = {
  "status": "cancelled"
}

transfer = app_token.post(transfer_url, request_body)
transfer.body['status'] # => 'cancelled'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388'
var requestBody = {
  status: "cancelled"
};

appToken
  .post('transfers', requestBody)
  .then(res => res.body.status); // => "cancelled"

Mass payments

Dwolla mass payments allows you to easily send up to 5,000 payments one API request. The payments are funded from a single user’s specified funding source and processed asynchronously upon submission.

  1. Dwolla Mass Payments are meant for batches of multiple payments. If you are initiating a single payment to a singular Customer, we recommend using our /transfers endpoint.

Your mass payment will initially be pending and then processed. As the service processes your mass payment, each item is processed one after the other, at a rate between 0.5 sec. - 1 sec. / item. Therefore, you can expect a 1000-item mass payment to be completed between 8-16 minutes.

A mass payment offers a significant advantage over repeatedly calling the Transfers endpoint for each individual transaction. A key benefit is that a bank-funded mass payment only incurs a single ACH debit from the bank account to fund the entire batch of payments. The alternative approach will incur an ACH debit from the bank funding source for each individual payment. Those who used this approach have reported incurring fees from their financial institutions for excessive ACH transactions.

Mass payments resource

Parameter Description
id Mass payment unique identifier.
status Either deferred: A created mass payment that can be processed at a later time. pending: A mass payment that is pending and awaiting processing. A mass payment has a pending status for a brief period of time and cannot be cancelled. processing: A mass payment that is processing. complete: A mass payment successfully completed processing.
created ISO-8601 timestamp.
metadata A metadata JSON object.
total The sum amount of all items in the mass payment.
totalFees The sum amount of all fees charged for the mass payment.
correlationId A unique string value attached to a mass payment resource which can be used for traceability between Dwolla and your application.
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/da835c07-1e12-4212-8b93-a7e0013dfd98",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "mass-payment"
        },
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "items": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/da835c07-1e12-4212-8b93-a7e0013dfd98/items",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "mass-payment-item"
        }
    },
    "id": "da835c07-1e12-4212-8b93-a7e0013dfd98",
    "status": "complete",
    "created": "2017-08-31T19:18:02.000Z",
    "metadata": {
        "batch": "batch1"
    },
    "total": {
        "value": "0.02",
        "currency": "USD"
    },
    "totalFees": {
        "value": "0.00",
        "currency": "USD"
    },
    "correlationId": "d028beed-8152-481d-9427-21b6c4d99644"
}

Initiate a mass payment

This section covers how to initiate a mass payment from your Dwolla Master Account or Verified Customer resource. A mass payment contains a list of items representing individual payments. Optionally, mass payments can contain metadata and a correlationId on the mass payment itself as well as items contained in the mass payment, which can be used to pass along additional information with the mass payment and item respectively. If a correlationId is included on a mass payment item it will be passed along to the transfer created from the item and can be searched on.

Deferred mass payment

A mass payment can be created with a status of deferred, which allows you to create the mass payment and defer processing to a later time. To trigger processing on a deferred mass payment, you’ll update the mass payment with a status of pending. A deferred mass payment can be cancelled by updating the mass payment with a status of cancelled.

HTTP request

POST https://api.dwolla.com/mass-payments

Request parameters

Parameter Required Type Description
_links yes object A _links JSON object describing the desired source of a mass payment. Reference the Source and Destination object to learn more about possible values for source and destination.
items yes array an array of item JSON objects that contain unique payments. See below
metadata no object A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters).
status no string Acceptable value is: deferred.
achDetails no object An ACH details JSON object which represents additional information sent along with a transfer created from a mass payment item to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. See below
correlationId no string A unique string value attached to a mass payment which can be used for traceability between Dwolla and your application. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _.

Source and destination values

Source types
Source Type URI Description
Funding source https://api.dwolla.com/funding-sources/{id} A bank or balance funding source of an Account or verified Customer.
Destination types
Destination Type URI Description
Funding source https://api.dwolla.com/funding-sources/{id} Destination of a Verified Customer’s own bank or balance funding source, an Unverified Customer’s bank funding source, or a Receive-only Customer’s bank funding source.
Customer https://api.dwolla.com/customers/{id} Destination Dwolla API Customer of a transfer.
Account https://api.dwolla.com/accounts/{id} Destination Transfer Account of a transfer.

Mass payment item

Parameter Description
_links A _links JSON object describing the desired destination of a mass payment. See above for possible values for destination.
amount An amount JSON object containing currency and value keys.
metadata A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters).
correlationId A unique string value attached to a mass payment item which can be used for traceability between Dwolla and your application. The correlationId will be passed along to a transfer that is created from an item and can be searched on. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _.
achDetails An ACH details JSON object which represents additional information sent along with a transfer created from a mass payment item to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution.

amount JSON object

Parameter Required Type Description
value yes string Amount of money
currency yes string Possible values: USD

achDetails and addenda object

The addendum record is used to provide additional information to the payment recipient about the payment. This value will be passed in on a transfer request and can be exposed on a customer’s bank statement. Addenda records provide a unique opportunity to supply your customers with more information about their transactions. Allowing businesses to include additional details about the transaction—such as invoice numbers—provides their end users with more information about the transaction in the comfort of their own banking application.

achDetails object
Parameter Required Type Description
source no object Represents information that is sent to a source/originating bank account along with a transfer. Include information within this JSON object for customizing details on ACH debit transfers. Can include an addenda JSON object.
destination no object Represents information that is sent to a destination/receiving bank account along with a transfer from a mass payment item. Include information within this JSON object for customizing details on ACH credit transfers. Can include an addenda JSON object.
addenda object
Parameter Required Type Description
addenda no object An addenda object contains a values key which is an array of comma separated string addenda values. Addenda record information is used for the purpose of transmitting transfer-related information. Values must be less than or equal to 80 characters and can include spaces. Acceptable characters are: a-Z, 0-9, and special characters - _ . ~! * ' ( ) ; : @ & = + $ , / ? % # [ ]. Will not show up on bank statements from balance-sourced transfers.
Source mass payment achDetails with addenda example:
"achDetails": {
  "source": {
    "addenda": {
      "values": ["ABC123_AddendaValue"]
    }
  }
},
Destination mass payment item with achDetails and addenda example
"achDetails": {
  "destination": {
    "addenda": {
      "values": ["ZYX987_AddendaValue"]
    }
  }
}

HTTP status and error codes

HTTP Status Code Description
201 Created A mass payment resource was created
400 ValidationError Can be: Items exceeded maximum count of 5000, Invalid amount, Invalid metadata, Invalid job item correlation ID, or Invalid funding source.
401 NotAuthorized OAuth token does not have Send scope.

Request and response (mass payment from Account to Customers)

POST https://api-sandbox.dwolla.com/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77

{
    "_links": {
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "achDetails": {
      "source": {
        "addenda": {
          "values": ["ABC123_AddendaValue"]
        }
      }
    },
    "items": [
      {
        "_links": {
            "destination": {
                "href": "https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
            }
        },
        "amount": {
            "currency": "USD",
            "value": "1.00"
        },
        "metadata": {
            "payment1": "payment1"
        },
        "achDetails": {
          "destination": {
            "addenda": {
              "values": ["ZYX987_AddendaValue"]
            }
          }
        },
        "correlationId": "ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841"
      },
      {
        "_links": {
            "destination": {
                "href": "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
            }
        },
        "amount": {
            "currency": "USD",
            "value": "5.00"
        },
        "metadata": {
            "payment2": "payment2"
        },
        "achDetails": {
          "destination": {
            "addenda": {
              "values": ["ZYX987_AddendaValue"]
              }
            }
        }
      }
    ],
    "metadata": {
        "batch1": "batch1"
    },
    "correlationId": "6d127333-69e9-4c2b-8cae-df850228e130"
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/mass-payments/d093bcd1-d0c1-41c2-bcb5-a5cc011be0b7
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :_links => {
    :source => {
      :href => "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    }
  },
  :achDetails => {
    :source => {
      :addenda => {
        :values: => ["ABC123_AddendaValue"]
      }
    }
  },
  :items => [
    {
      :_links => {
        :destination => {
          :href => "https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
        }
      },
      :amount => {
        :currency => "USD",
        :value => "1.00"
      },
      :metadata => {
        :payment1 => "payment1"
      },
      :correlationId => "ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841",
      :achDetails => {
        :destination => {
          :addenda => {
            :values: => ["ABC123_AddendaValue"]
          }
        }
      }
    },
    {
      :_links => {
        :destination => {
          :href => "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
        }
      },
      :amount => {
        :currency => "USD",
        :value => "5.00"
      },
      :metadata => {
        :payment2 => "payment2"
      },
      :achDetails => {
        :destination => {
          :addenda => {
            :values: => ["ABC123_AddendaValue"]
          }
        }
      }
    }
  ],
  :metadata => {
    :batch1 => "batch1"
  },
  :correlationId => "6d127333-69e9-4c2b-8cae-df850228e130"
}

mass_payment = app_token.post "mass-payments", request_body
mass_payment.response_headers[:location] # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"
<?php
$massPaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);

$massPayment = $massPaymentsApi->create([
  '_links' =>
  [
    'source' =>
    [
      'href' => 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4',
    ],
  ],
  'achDetails' =>
  [
    'source' => [
      'addenda' => [
        'values' => ['ABC123_AddendaValue']
      ]
    ]
  ],
  'items' =>
  [
    [
      '_links' =>
      [
        'destination' =>
        [
          'href' => 'https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db',
        ],
      ],
      'amount' =>
      [
        'currency' => 'USD',
        'value' => '1.00',
      ],
      'metadata' =>
      [
        'payment1' => 'payment1',
      ],
      'correlationId' => 'ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841',
      'achDetails' =>
      [
        'source' => [
          'addenda' => [
            'values' => ['ABC123_AddendaValue']
          ]
        ]
      ]
    ],
    [
      '_links' =>
      [
        'destination' =>
        [
          'href' => 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd',
        ],
      ],
      'amount' =>
      [
        'currency' => 'USD',
        'value' => '5.00',
      ],
      'metadata' =>
      [
        'payment2' => 'payment2',
      ],
      'achDetails' =>
      [
        'source' => [
          'addenda' => [
            'values' => ['ABC123_AddendaValue']
          ]
        ]
      ]
    ],
  ],
  'metadata' =>
  [
    'batch1' => 'batch1',
  ],
  'correlationId' => '6d127333-69e9-4c2b-8cae-df850228e130',
]);
$massPayment; # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  '_links': {
    'source': {
      'href': 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  'achDetails': {
    'addenda': {
      'values': ['ABC123_AddendaValue']
    }
  },
  'items': [
    {
      '_links': {
        'destination': {
          'href': 'https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db'
        }
      },
      'amount': {
        'currency': 'USD',
        'value': '1.00'
      },
      'metadata': {
        'payment1': 'payment1'
      },
      'correlationId': 'ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841',
      'achDetails': {
        'addenda': {
          'values': ['ABC123_AddendaValue']
        }
      }
    },
    {
      '_links': {
        'destination': {
          'href': 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd'
        }
      },
      'amount': {
        'currency': 'USD',
        'value': '5.00'
      },
      'metadata': {
        'payment2': 'payment2'
      },
      'achDetails': {
        'addenda': {
          'values': ['ABC123_AddendaValue']
        }
      }
    }
  ],
  'metadata': {
    'batch1': 'batch1'
  },
  'correlationId': '6d127333-69e9-4c2b-8cae-df850228e130'
}

mass_payment = app_token.post('mass-payments', request_body)
mass_payment.headers['location'] # => 'https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4'
var requestBody = {
  _links: {
    source: {
      href: 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  achDetails: {
    source: {
      addenda: {
        values: ['ABC123_AddendaValue']
      }
    }
  }
  items: [
    {
      _links: {
        destination: {
          href: 'https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db'
        }
      },
      amount: {
        currency: 'USD',
        value: '1.00'
      },
      metadata: {
        payment1: 'payment1'
      },
      correlationId: 'ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841',
      achDetails: {
        destination: {
          addenda: {
            values: ['ABC123_AddendaValue']
          }
        }
      }
    },
    {
      _links: {
        destination: {
          href: 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd'
        }
      },
      amount: {
        currency: 'USD',
        value: '5.00'
      },
      metadata: {
        payment2: 'payment2'
      },
      achDetails: {
        destination: {
          addenda: {
            values: ['ABC123_AddendaValue']
          }
        }
      }
    }
  ],
  metadata: {
    batch1: 'batch1'
  },
  correlationId: '6d127333-69e9-4c2b-8cae-df850228e130'
}

appToken
  .post('mass-payments', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4'

Retrieve a mass payment

This section outlines how to retrieve a mass payment by its id. All mass payments will have a status of pending upon creation and will move to processing and finally complete as the service runs. It is recommended that you retrieve your list of mass payment items when your mass payment has a status of complete to determine if any items failed to process successfully.

HTTP request

GET https://api.dwolla.com/mass-payments/{id}

Request parameters

Parameter Required Type Description
id yes string The id of the mass payment to retrieve information for.

HTTP status and error codes

HTTP Status Code Description
404 NotFound Mass payment not found.

Request and response

GET https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
    },
    "source": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    },
    "items": {
      "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items"
    }
  },
  "id": "eb467252-808c-4bc0-b86f-a5cd01454563",
  "status": "processing",
  "created": "2016-03-18T19:44:16.000Z",
  "metadata": {}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_url = "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"

mass_payment = account_token.get mass_payment_url
mass_payment.status # => "processing"
<?php
$massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';

$massPaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);

$massPayment = $massPaymentsApi->byId($massPaymentUrl);
$massPayment->status; # => "processing"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

mass_payment = app_token.get(mass_payment_url)
mass_payment.body['status'] # => 'processing'
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';

appToken
  .get(massPaymentUrl)
  .then(res => res.body.status); // => 'processing'

Update a mass payment

This section covers how to update a mass payment’s status to pending which triggers processing on a created and deferred mass payment, or cancelled which cancels a created and deferred mass payment.

HTTP request

POST https://api.dwolla.com/mass-payments/{id}

Request parameters

Parameter Required Type Description
id yes string id of mass payment to update.
status yes string Either pending or cancelled depending on the action you want to take on a deferred mass payment.

HTTP status and error codes

HTTP Status Code Description
404 NotFound Mass payment not found.
400 ValidationError Invalid status. Allowed types are pending, cancelled.

Request and response

POST https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "status": "pending"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
      "status" => "pending",
}

mass_payment = app_token.post "#{mass_payment_url}", request_body
mass_payment.status # => "pending"
/**
 *  No example for this language yet. Coming soon.
 **/
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
  "status": "pending"
}

mass_payments = app_token.post('mass-payments', request_body)
mass_payments.body['status'] # => 'pending'
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
  status: "pending"
};

appToken
  .post(massPaymentUrl, requestBody)
  .then(res => res.body.status); // => "pending"

List items for a mass payment

A mass payment contains a list of payments called items. An item is distinct from the transfer which it creates. An item can contain a status of either failed, pending, or success depending on whether the payment was created by the Dwolla service or not. A mass payment item status of success is an indication that a transfer was successfully created. A mass payment’s items will be returned in the _embedded object as a list of items.

HTTP Request

GET https://api.dwolla.com/mass-payments/{id}/items

Request parameters

Parameter Required Type Description
id yes string Mass payment unique identifier.
limit no integer How many results to return. Defaults to 25.
offset no integer How many results to skip.
status no string Filter results on item status. Possible values: failed, pending, and success. Values delimited by &status= (i.e. - /items?status=failed&status=pending).

Mass payment item failures

Individual mass payment items can have a status of failed. If an item has a status of failed, an _embedded object will be returned within the item which contains a list of errors. Each error object includes a top-level error code, a message with a detailed description of the error, and a path which is a JSON pointer to the specific field in the request that has a problem. You can utilize both the failure code and message to get a better understanding of why the particular item failed.

Code Message Description
InsufficientFunds “Insufficient funds.” The source funding source has insufficient funds, and as a result failed to create a transfer.
Invalid “Receiver not found.” The destination was not a valid Customer or Funding Source.
Invalid “Receiver cannot be the owner of the source funding source.” The destination of the transfer cannot be the same as the source.
RequiresFundingSource “Receiver requires funding source.” The destination of the mass payment item does not have an active funding source attached.
Restricted “Receiver restricted.” The destination customer is either deactivated or suspended and is not eligible to receive funds.

HTTP status and error codes

HTTP Status Code Description
403 Forbidden Not authorized to list mass payment items.
404 NotFound Mass payment not found.

Request and response

GET https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items?limit=25&offset=0"
    }
  },
  "_embedded": {
    "items": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/mass-payment-items/2f845bc9-41ed-e511-80df-0aa34a9b2388"
          },
          "mass-payment": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
          },
          "destination": {
            "href": "https://api-sandbox.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
          },
          "transfer": {
            "href": "https://api-sandbox.dwolla.com/transfers/fa3999db-41ed-e511-80df-0aa34a9b2388"
          }
        },
        "id": "2f845bc9-41ed-e511-80df-0aa34a9b2388",
        "status": "success",
        "amount": {
          "value": "1.00",
          "currency": "USD"
        },
        "metadata": {
          "item1": "item1"
        }
      },
      {
        "_links": {
            "self": {
                "href": "https://api-sandbox.dwolla.com/mass-payment-items/30845bc9-41ed-e511-80df-0aa34a9b2388",
                "type": "application/vnd.dwolla.v1.hal+json",
                "resource-type": "mass-payment-item"
            },
            "mass-payment": {
                "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563",
                "type": "application/vnd.dwolla.v1.hal+json",
                "resource-type": "mass-payment"
            },
            "destination": {
                "href": "https://api-sandbox.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd",
                "type": "application/vnd.dwolla.v1.hal+json",
                "resource-type": "customer"
            }
        },
        "_embedded": {
            "errors": [
                {
                    "code": "RequiresFundingSource",
                    "message": "Receiver requires funding source.",
                    "path": "/items/destination/href",
                    "_links": {}
                }
            ]
        },
        "id": "30845bc9-41ed-e511-80df-0aa34a9b2388",
        "status": "failed",
        "amount": {
            "value": "0.02",
            "currency": "USD"
        },
        "metadata": {
            "item2": "item2"
        }
      }
    ]
  },
  "total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

mass_payment_items = app_token.get "#{mass_payment_url}/items"
mass_payment_items.total # => 2
<?php
$massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';

$massPaymentItemsApi = new DwollaSwagger\MasspaymentitemsApi($apiClient);

$massPaymentItems = $massPaymentItemsApi->getMassPaymentItems($massPaymentUrl);
$massPaymentItems->total; # => "2"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

mass_payment_items = app_token.get('%s/items' % mass_payment_url)
mass_payment_items.body['total'] # => "2"
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

appToken
  .get(`${massPaymentUrl}/items`)
  .then(res => res.body.total); // => 2

Retrieve a mass payment item

This section covers how to retrieve a mass payment item by its unique identifier. An item can contain _links to: the mass payment the item belongs to, the transfer created from the item, and the destination user.

HTTP request

GET https://api.dwolla.com/mass-payment-items/{id}

Request parameters

Parameter Required Type Description
id yes string The id of the item to be retrieved in a mass payment.

HTTP status and error codes

HTTP Status Code Description
403 Forbidden Not authorized to list mass payment items.
404 NotFound Mass payment not found.

Request and response

GET https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/mass-payment-items/2f845bc9-41ed-e511-80df-0aa34a9b2388"
    },
    "mass-payment": {
      "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
    },
    "destination": {
      "href": "https://api-sandbox.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
    },
    "transfer": {
      "href": "https://api-sandbox.dwolla.com/transfers/fa3999db-41ed-e511-80df-0aa34a9b2388"
    }
  },
  "id": "2f845bc9-41ed-e511-80df-0aa34a9b2388",
  "status": "success",
  "amount": {
    "value": "1.00",
    "currency": "USD"
  },
  "metadata": {
    "item1": "item1"
  }
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_item_url = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388'

mass_payment_item = app_token.get mass_payment_item_url
mass_payment_item.status # => "success"
<?php
$massPaymentItemUrl = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388';

$massPaymentItemsApi = new DwollaSwagger\MasspaymentitemsApi($apiClient);

$massPaymentItem = $massPaymentItemsApi->byId($massPaymentItemUrl);
$massPaymentItem->status; # => "success"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_item_url = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388'

mass_payment_item = app_token.get(mass_payment_item_url)
mass_payment_item.body['status'] # => 'success'
var massPaymentItemUrl = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388';

appToken
  .get(massPaymentItemUrl)
  .then(res => res.body.status); // => 'success'

Events

When the state of a resource changes, Dwolla creates a new event resource to record the change. When an Event is created, a Webhook will be created to deliver the Event to any URLs specified by your active Webhook Subscriptions.

Events resource

Parameter Description
_links Contains links to the event, associated resource, and the Account associated with the event.
id Event id
created ISO-8601 timestamp when event was created
topic Type of event
resourceId id of the resource associated with the event.
{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/events/f8e70f48-b7ff-47d0-9d3d-62a099363a76"
    },
    "resource": {
      "href": "https://api.dwolla.com/transfers/48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
    },
    "account": {
      "href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    }
  },
  "id": "f8e70f48-b7ff-47d0-9d3d-62a099363a76",
  "created": "2015-10-16T15:58:15.000Z",
  "topic": "transfer_created",
  "resourceId": "48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
}

Dwolla Master Account Event topics

Accounts
Topic Description
account_suspended A Dwolla Master Account was suspended.
account_activated A Dwolla Master Account moves from deactivated or suspended to active state of verification.
Funding Sources
Topic Description
funding_source_added A funding source was added to a Dwolla account.
funding_source_removed A funding source was removed from a Dwolla account.
funding_source_verified A funding source was marked as verified.
funding_source_unverified A funding source has been systematically unverified. This is generally a result of a transfer failure. View our developer resource article to learn more.
funding_source_negative A Dwolla Master account balance has gone negative. You are responsible for ensuring a zero or positive Dwolla balance for your account. If your balance funding source has gone negative, you are responsible for making the Dwolla account whole. Dwolla will notify you via a webhook and separate email of the negative balance. If no action is taken, Dwolla will debit your attached billing source.
funding_source_updated A funding source has been updated. This can also be fired as a result of a correction after a bank transfer processes. For example, a financial institution can issue a correction to change the bank account type from checking to savings.
microdeposits_added Two <=10¢ transfers to a Dwolla Master account’s linked bank account were initiated.
microdeposits_failed The two <=10¢ transfers to a Dwolla Master account’s linked bank account failed to clear successfully.
microdeposits_completed The two <=10¢ transfers to a Dwolla Master account’s linked bank account have cleared successfully.
microdeposits_maxattempts The funding source has reached its max verification attempts limit of three. The funding source can no longer be verified with the completed micro-deposit amounts.
Transfers
Topic Description
bank_transfer_created A bank transfer was created.
bank_transfer_cancelled A pending bank transfer has been cancelled, and will not process further.
bank_transfer_failed A transfer failed to clear successfully. Usually, this is a result of an ACH failure (insufficient funds, etc.).
bank_transfer_completed A bank transfer has cleared successfully.
transfer_created A transfer was created.
transfer_cancelled A pending transfer has been cancelled, and will not process further.
transfer_failed A transfer failed to clear successfully.
transfer_reclaimed The transfer was returned to the sender after remaining unclaimed by the intended recipient for a period of time.
transfer_completed A transfer has cleared successfully.
Mass Payments
Topic Description
mass_payment_created A mass payment was created.
mass_payment_completed A mass payment completed.
mass_payment_cancelled A created and deferred mass payment was cancelled.

Customer Account Event topics

Customers
Topic Description
customer_created A Customer was created.
customer_verification_document_needed Additional documentation is needed to verify a Customer.
customer_verification_document_uploaded A verification document was uploaded for a Customer.
customer_verification_document_failed A verification document has been rejected for a Customer.
customer_verification_document_approved A verification document was approved for a Customer.
customer_reverification_needed Incomplete information was received for a Customer; updated information is needed to verify the Customer.
customer_verified A Customer was verified.
customer_suspended A Customer was suspended.
customer_activated A Customer moves from deactivated or suspended to an active status.
customer_deactivated A Customer was deactivated.
Beneficial Owners
Topic Description
customer_beneficial_owner_created Beneficial owner successfully created.
customer_beneficial_owner_removed An individual beneficial owner has been successfully removed from the Customer
customer_beneficial_owner_verification_document_needed Additional documentation is needed to verify an individual beneficial owner.
customer_beneficial_owner_verification_document_uploaded A verification document was uploaded for beneficial owner.
customer_beneficial_owner_verification_document_failed A verification document has been rejected for a beneficial owner.
customer_beneficial_owner_verification_document_approved A verification document was approved for a beneficial owner.
customer_beneficial_owner_reverification_needed A previously verified beneficial owner status has changed due to either a change in the beneficial owner’s information or at request for more information from Dwolla. The individual will need to verify their identity within 30 days.
customer_beneficial_owner_verified A beneficial owner has been verified.
Funding Sources
Topic Description
customer_funding_source_added A funding source was added to a Customer.
customer_funding_source_removed A funding source was removed from a Customer.
customer_funding_source_verified A Customer’s funding source was marked as verified.
customer_funding_source_unverified A funding source has been systematically unverified. This is generally a result of a transfer failure. View our developer resource article to learn more.
customer_funding_source_negative A Customer’s balance has gone negative. You are responsible for ensuring a zero or positive Dwolla balance for Customer accounts created by your application. If a Customer balance funding source has gone negative, you are responsible for making the Dwolla Customer account whole. Dwolla will notify you via a webhook and separate email of the negative balance. If no action is taken, Dwolla will debit your attached billing source.
customer_funding_source_updated A Customer’s funding source has been updated. This can also be fired as a result of a correction after a bank transfer processes. For example, a financial institution can issue a correction to change the bank account type from checking to savings.
customer_microdeposits_added Two <=10¢ transfers to a Customer’s linked bank account were initiated.
customer_microdeposits_failed The two <=10¢ transfers to a Customer’s linked bank account failed to clear successfully.
customer_microdeposits_completed The two <=10¢ transfers to a Customer’s linked bank account have cleared successfully.
customer_microdeposits_maxattempts The Customer has reached their max verification attempts limit of three. The Customer can no longer verify their funding source with the completed micro-deposit amounts.
Transfers
Topic Description
customer_bank_transfer_created A bank transfer was created for a Customer. Represents funds moving either from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank.
customer_bank_transfer_creation_failed An attempt to initiate a transfer to a verified Customer’s bank was made, but failed. Transfers initiated to a verified Customer’s bank must pass through the verified Customer’s balance before being sent to a receiving bank. Dwolla will fail to create a transaction intended for a verified Customer’s bank if the funds available in the balance are less than the transfer amount.
customer_bank_transfer_cancelled A pending Customer bank transfer has been cancelled, and will not process further. Represents a cancellation of funds either transferring from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank.
customer_bank_transfer_failed A Customer bank transfer failed to clear successfully. Usually, this is a result of an ACH failure (insufficient funds, etc.). Represents funds failing to clear either from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank.
customer_bank_transfer_completed A bank transfer that was created for a Customer has cleared successfully. Represents funds clearing either from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank.
customer_transfer_created A transfer was created for a Customer. Represents funds transferring from a verified Customer’s balance or unverified Customer’s bank
customer_transfer_cancelled A pending transfer has been cancelled, and will not process further. Represents a cancellation of funds transferring either to an unverified Customer’s bank or to a verified Customer’s balance.
customer_transfer_failed A Customer transfer failed to clear successfully. Represents funds failing to clear either to an unverified Customer’s bank or to a verified Customer’s balance.
customer_transfer_completed A Customer transfer has cleared successfully. Represents funds clearing either to an unverified Customer’s bank or to a verified Customer’s balance.
Mass Payments
Topic Description
customer_mass_payment_created A Verified Customer’s mass payment was created.
customer_mass_payment_completed A Verified Customer’s mass payment completed.
customer_mass_payment_cancelled A Verified Customer’s created and deferred mass payment was cancelled.
customer_balance_inquiry_completed Upon checking a Customer’s bank balance, Dwolla will immediately return an HTTP 202 with response body that includes a status of processing. This event will be triggered when the bank balance check has completed processing.

List events

Retrieve a list of events for the application. Note: Dwolla will only guarantee access to events through the API over a rolling 30-day period.

HTTP request

GET https://api.dwolla.com/events

Request parameters

Parameter Required Type Description
limit no integer How many results to return
offset no integer How many results to skip

HTTP status and error codes

HTTP Status Message
404 Resource not found.

Request and response

GET https://api-sandbox.dwolla.com/events
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/events"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/events?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/events?limit=25&offset=150"
    },
    "next": {
      "href": "https://api-sandbox.dwolla.com/events?limit=25&offset=25"
    }
  },
  "_embedded": {
    "events": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/events/78e57644-56e4-4da2-b743-059479f2e80f"
          },
          "resource": {
            "href": "https://api-sandbox.dwolla.com/transfers/47CFDDB4-1E74-E511-80DB-0AA34A9B2388"
          },
          "account": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          }
        },
        "id": "78e57644-56e4-4da2-b743-059479f2e80f",
        "created": "2015-10-16T15:58:18.000Z",
        "topic": "bank_transfer_created",
        "resourceId": "47CFDDB4-1E74-E511-80DB-0AA34A9B2388"
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/events/f8e70f48-b7ff-47d0-9d3d-62a099363a76"
          },
          "resource": {
            "href": "https://api-sandbox.dwolla.com/transfers/48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
          },
          "account": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          }
        },
        "id": "f8e70f48-b7ff-47d0-9d3d-62a099363a76",
        "created": "2015-10-16T15:58:15.000Z",
        "topic": "transfer_created",
        "resourceId": "48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
      },
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/events/9f0167e0-dce6-4a1a-ad26-30015d6f1cc1"
          },
          "resource": {
            "href": "https://api-sandbox.dwolla.com/transfers/08A166BC-1B74-E511-80DB-0AA34A9B2388"
          },
          "account": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          }
        },
        "id": "9f0167e0-dce6-4a1a-ad26-30015d6f1cc1",
        "created": "2015-10-16T15:37:03.000Z",
        "topic": "bank_transfer_created",
        "resourceId": "08A166BC-1B74-E511-80DB-0AA34A9B2388"
      }
    ]
  },
  "total": 3
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
events = app_token.get "events"
events.total # => 3
<?php
$eventsApi = new DwollaSwagger\EventsApi($apiClient);

$events = $eventsApi->events();
$events->total; # => 3
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
events = app_token.get('events')
events.body['total'] # => 3
appToken
  .get('events')
  .then(res => res.body.total); // => 3

Retrieve an event

This section covers how to retrieve an event by id.

HTTP Request

GET https://api.dwolla.com/events/{id}

Request parameters

Parameter Required Type Description
id yes string ID of application event to get.

HTTP status and error codes

HTTP Status Message
404 Application event not found.

Request and response

GET https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095"
    },
    "resource": {
      "href": "https://api-sandbox.dwolla.com/transfers/09A166BC-1B74-E511-80DB-0AA34A9B2388"
    },
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "customer": {
      "href": "https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8"
    }
  },
  "id": "81f6e13c-557c-4449-9331-da5c65e61095",
  "created": "2015-10-16T15:37:02.000Z",
  "topic": "customer_transfer_created",
  "resourceId": "09A166BC-1B74-E511-80DB-0AA34A9B2388"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
event_url = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'

event = app_token.get event_url
event.topic # => "customer_transfer_created"
<?php
$eventUrl = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095';

$eventsApi = new DwollaSwagger\EventsApi($apiClient);

$event = $eventsApi->id($eventUrl);
$event->topic; # => "customer_transfer_created"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
event_url = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'

event = app_token.get(event_url)
event.body['topic'] # => 'customer_transfer_created'
var eventUrl = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095';

appToken
  .get(eventUrl)
  .then(res => res.body.topic); // => 'customer_transfer_created'

Webhook subscriptions

Create a webhook subscription to receive POST requests from Dwolla (called webhooks) when events associated with your application occur. Webhooks are sent to a URL which you provide when creating a webhook subscription. While we see most applications maintain one webhook subscription, you can have up to ten active webhook subscription at a time. Refer to the events section for the list of events that trigger webhooks.

Automatic pause of a webhook subscription

Dwolla will automatically pause subscribed webhook endpoints that are no longer reachable. The webhook subscription will be paused after 400 consecutive failures. This will help us ensure that unavailable endpoints don’t cause delays or issues in delivery of notifications for other API customers. Webhook subscriptions can be unpaused by calling this endpoint.

Acknowledgement and retries

When your application receives a webhook, it should respond with a HTTP 2xx status code to indicate successful receipt. If Dwolla receives a status code greater than or equal to 400, or your application fails to respond within 10 seconds of the attempt, another attempt will be made.

Dwolla will re-attempt delivery 8 times over the course of 72 hours according the backoff schedule below. If a webhook was successfully received but you would like the information again, you can call retrieve a webhook by its Id.

Retry number Interval (relative to last retry) Interval (relative to original attempt)
1 15 min 15 min
2 45 min 1 h
3 2 h 3 h
4 3 h 6 h
5 6 h 12 h
6 12 h 24 h
7 24 h 48 h
8 24 h 72 h

Webhook subscription resource

Parameter Description
id Webhook subscription unique identifier.
url Subscribed url where Dwolla should deliver the webhook notification.
paused A boolean true or false value indicating if the webhook subscription is paused. A webhook subscription will be automatically paused after 400 consecutive failures. In addition, a subscription can be paused or unpaused by calling this endpoint in the API.
created ISO-8601 timestamp

Create a webhook subscription

This section details how to create a webhook subscription to deliver webhooks to a specified URL.

HTTP request

POST https://api.dwolla.com/webhook-subscriptions

Request parameters

Parameter Required Type Description
url yes string Where Dwolla should deliver the webhook notification.
secret yes string A random, secret key, only known by your application. This secret key should be securely stored and used later when validating the authenticity of the webhook request from Dwolla.

Request and response

POST https://api-sandbox.dwolla.com/webhook-subscriptions
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q
{
    "url": "http://myapplication.com/webhooks",
    "secret": "sshhhhhh"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :url => "http://myawesomeapplication.com/destination",
  :secret => "your webhook secret"
}
subscription = app_token.post "webhook-subscriptions", request_body
subscription.response_headers[:location] # => "https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"
var requestBody = {
  url: 'http://myawesomeapplication.com/destination',
  secret: 'your webhook secret'
};
appToken
  .post('webhook-subscriptions', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'url': 'http://myapplication.com/webhooks',
  'secret': 'sshhhhhh'
}
retries = app_token.post('webhook-subscriptions', request_body)
retries.body['total'] # => 1
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$subscription = $webhookApi->create(array (
  'url' => 'http://myapplication.com/webhooks',
  'secret' => 'sshhhhhh',
));
$subscription; # => "https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"
?>

Retrieve a webhook subscription

This section details how to retrieve a webhook subscription by its id.

HTTP request

GET https://api.dwolla.com/webhook-subscriptions/{id}

Request parameters

Parameter Required Type Description
id yes string Webhook subscription unique identifier.

HTTP status and error codes

HTTP Status Message
404 Webhook subscription not found.

Request and response

GET https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/webhook-subscriptions/077dfffb-4852-412f-96b6-0fe668066589"
    },
    "webhooks": {
      "href": "https://api-sandbox.dwolla.com/webhook-subscriptions/077dfffb-4852-412f-96b6-0fe668066589/webhooks"
    }
  },
  "id": "077dfffb-4852-412f-96b6-0fe668066589",
  "url": "http://myapplication.com/webhooks",
  "created": "2015-10-28T16:20:47+00:00"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

webhook_subscription = app_token.get webhook_subscription_url
webhook_subscription.created # => 2015-10-28T16:20:47+00:00
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

appToken
  .get(webhookSubscriptionUrl)
  .then(res => res.body.created); // => '2016-04-20T15:49:50.340Z'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

webhook_subscription = app_token.get(webhook_subscription_url)
webhook_subscription.body['created'] # => '2015-10-28T16:20:47+00:00'
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$retrieved = $webhookApi->id('https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');

$retrieved->created; # => 2015-10-28T16:20:47+00:00
?>

Update a webhook subscription

This section details how to pause a webhook subscription. When a webhook subscription is paused Dwolla will continue to create webhooks but not send them to your subscribed webhook url. This is useful if your webhook endpoint is unavailable and you want to temporarily disable webhook requests.

HTTP request

POST https://api.dwolla.com/webhook-subscriptions/{id}

Request parameters

Parameter Required Type Description
id yes string Webhook unique identifier.
paused yes string Specify a value of true to pause the associated webhook subscription or false to unpause a paused subscription.

Request and response

POST https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q
{
    "paused": true
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

request_body = {
  :paused => true
}

subscription = app_token.post "#{webhook_subscription_url}", request_body
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/692486f8-29f6-4516-a6a5-c69fd2ce854c';

var requestBody = {
  paused: true
};

appToken
  .post(webhookSubscriptionUrl, requestBody)
  .then(res => res.body.paused); // => 'true'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

request_body = {
  'paused': true
}

subscription = app_token.post(webhook_subscription_url, request_body)
subscription.body['paused'] # => true
<?php
$webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);

$subscription = $webhookApi->updateSubscription(array (
  'paused' => true
), $webhookSubscriptionUrl);
?>

List webhook subscriptions

This section covers how to retrieve a list of webhook subscriptions that belong to an application.

HTTP request

GET https://api.dwolla.com/webhook-subscriptions

Request and response

GET https://api-sandbox.dwolla.com/webhook-subscriptions
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/webhook-subscriptions"
    }
  },
  "_embedded": {
    "webhook-subscriptions": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/webhook-subscriptions/f4d21628-fde2-4d3a-b69a-0a7cb42adc4c"
          },
          "webhooks": {
            "href": "https://api-sandbox.dwolla.com/webhook-subscriptions/f4d21628-fde2-4d3a-b69a-0a7cb42adc4c/webhooks"
          }
        },
        "id": "f4d21628-fde2-4d3a-b69a-0a7cb42adc4c",
        "url": "https://destination.url",
        "created": "2015-08-19T21:43:49.000Z"
      }
    ]
  },
  "total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscriptions = app_token.get "webhook-subscriptions"
webhook_subscriptions.total # => 1
appToken
  .get('webhook-subscriptions')
  .then(res => res.body.total); // => 1
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscriptions = app_token.get('webhook-subscriptions')
webhook_subscriptions.body['total'] # => 1
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);

$retrieved = $webhookApi->_list();
$retrieved->total; # => 1
?>

Delete a webhook subscription

Delete a Webhook Subscription to stop receiving Webhooks at the URL specified. If using an SDK, the request was successful unless an exception was thrown stating otherwise.

HTTP request

DELETE https://api.dwolla.com/webhook-subscriptions/{id}

Request parameters

Parameter Required Type Description
id yes string Webhook unique identifier.

HTTP status and error codes

HTTP Status Message
404 Webhook subscription not found.

Request and response

DELETE https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

app_token.delete webhook_subscription_url
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

appToken.delete(webhookSubscriptionUrl);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

app_token.delete(webhook_subscription_url)
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$webhookApi->deleteById('https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');
?>

List webhooks for a webhook subscription

This section covers how to view all fired webhooks for a webhook subscription. Note: Dwolla will only guarantee access to webhook data through the API over a rolling 30-day period.

HTTP request

GET https://api.dwolla.com/webhook-subscriptions/{id}/webhooks

Request parameters

Parameter Required Type Description
id yes string Webhook subscription unique identifier.
limit no integer How many results to return. Defaults to 25.
offset no integer How many results to skip.

Request and response

GET https://api-sandbox.dwolla.com/webhook-subscriptions/10d4133e-b308-4646-b276-40d9d36def1c/webhooks
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {},
  "total": 0,
  "items": [
    {
      "_links": {},
      "id": "string",
      "topic": "string",
      "accountId": "string",
      "eventId": "string",
      "subscriptionId": "string",
      "attempts": [
        {
          "id": "string",
          "request": {
            "created": "2015-07-23T14:19:37.006Z",
            "url": "string",
            "headers": [
              {
                "name": "string",
                "value": "string"
              }
            ],
            "body": "string"
          },
          "response": {
            "created": "2015-07-23T14:19:37.006Z",
            "headers": [
              {
                "name": "string",
                "value": "string"
              }
            ],
            "statusCode": 0,
            "body": "string"
          }
        }
      ]
    }
  ]
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

hooks = app_token.get "#{webhook_subscription_url}/webhooks"
hooks.total # => 5
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

appToken
  .get(`${webhookSubscriptionUrl}/webhooks`)
  .then(res => res.body.total); // => 5
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

hooks = app_token.get('%s/hooks' % webhook_subscription_url)
hooks.body['total'] # => 5
<?php
$webhookApi = new DwollaSwagger\WebhooksApi($apiClient);

$hooks = $webhookApi->hooksById('https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');
$hooks->total; # => 5
?>

Webhooks

When a new event is created and there is an active webhook subscription, a new webhook is created in order to deliver that event. Attempted deliveries are recorded under the webhook’s attempts property. Each attempt includes the recorded request and response of the delivery attempt. Webhooks are sent asynchronously and are not guaranteed to be delivered in order. We recommend that applications protect against duplicated events by making event processing idempotent.

Note: Webhooks containing an event are only fired if an application has a valid refresh_token for the Dwolla user Account that an event is created on.

Webhook resource

Parameter Description
id Webhook unique identifier
topic Type of webhook subscription
accountId Account associated with the webhook notification
eventId Event id for this webhook
subscriptionId Webhook subscription id for this event
attempts Array of attempt JSON object

Attempts JSON object

Parameter Description
id Unique id of webhook delivery attempt.
request Request JSON object
response Response JSON object

Request/response JSON object

Parameter Description
created ISO-8601 timestamp
url URL where data was sent to/received from
headers Array of objects with keys name and value representative of HTTP headers
body An Event for the webhook

Retrieve a webhook

This section covers how to retrieve a single webhook.

HTTP request

GET https://api.dwolla.com/webhooks/{id}

Request parameters

Parameter Required Type Description
id yes string Id of webhook to retrieve.

HTTP status and error codes

HTTP Status Message
404 Webhook not found.

Request and response

GET https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8"
    },
    "subscription": {
      "href": "https://api-sandbox.dwolla.com/webhook-subscriptions/a0943041-7a5c-4e8f-92de-b55711ef3a83"
    },
    "retry": {
      "href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
    },
    "event": {
      "href": "https://api-sandbox.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50"
    }
  },
  "id": "9ece9660-aa34-41eb-80d7-0125d53b45e8",
  "topic": "transfer_created",
  "accountId": "ca32853c-48fa-40be-ae75-77b37504581b",
  "eventId": "03c7e14c-7f15-44a2-bcf7-83f2f7e95d50",
  "subscriptionId": "a0943041-7a5c-4e8f-92de-b55711ef3a83",
  "attempts": [
    {
      "id": "d4d16621-c6b0-40cb-8dc3-0469fa9dc4e8",
      "request": {
        "timestamp": "2015-10-27T17:07:34.304Z",
        "url": "https://myapp.runscope.net",
        "headers": [
          {
            "name": "X-Dwolla-Topic",
            "value": "transfer_created"
          },
          {
            "name": "X-Request-Signature",
            "value": "bd93780bd7e1ad77ab821094aaa0f9e3dece5ee3"
          }
        ],
        "body": "{\"id\":\"03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\",\"resourceId\":\"81BA6F36-CD7C-E511-80DB-0AA34A9B2388\",\"topic\":\"transfer_created\",\"timestamp\":\"2015-10-27T17:07:34.207Z\",\"_links\":{\"self\":{\"href\":\"https://api.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\"},\"account\":{\"href\":\"https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b\"},\"resource\":{\"href\":\"https://api.dwolla.com/transfers/81BA6F36-CD7C-E511-80DB-0AA34A9B2388\"}}}"
      },
      "response": {
        "timestamp": "2015-10-27T17:07:34.308Z",
        "headers": [
          {
            "name": "Date",
            "value": "Tue, 27 Oct 2015 17:07:34 GMT"
          },
          {
            "name": "Content-Type",
            "value": "application/json; charset=UTF-8"
          },
          {
            "name": "Content-Length",
            "value": "1093"
          },
          {
            "name": "Connection",
            "value": "keep-alive"
          },
          {
            "name": "Access-Control-Allow-Credentials",
            "value": "true"
          },
          {
            "name": "Access-Control-Allow-Methods",
            "value": "GET, PUT, POST, PATCH, DELETE, OPTIONS, HEAD"
          },
          {
            "name": "Server",
            "value": "Runscope-Gateway/1.0"
          },
          {
            "name": "Runscope-Message-Id",
            "value": "97aa5bbd-784f-4007-80cc-8f56919000a0"
          },
          {
            "name": "Access-Control-Allow-Origin",
            "value": "*"
          }
        ],
        "statusCode": 200,
        "body": "{\"body\":\"{\"id\":\"03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\",\"resourceId\":\"81BA6F36-CD7C-E511-80DB-0AA34A9B2388\",\"topic\":\"transfer_created\",\"timestamp\":\"2015-10-27T17:07:34.207Z\",\"_links\":{\"self\":{\"href\":\"https://api-sandbox.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\"},\"account\":{\"href\":\"https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b\"},\"resource\":{\"href\":\"https://api.dwolla.com/transfers/81BA6F36-CD7C-E511-80DB-0AA34A9B2388\"}}}\",\"files\":[],\"form\":{},\"fragment\":\"\",\"headers\":{\"Connection\":[\"close\"],\"Content-Length\":[\"453\"],\"Content-Type\":[\"application/json; charset=UTF-8\"],\"Host\":[\"myapp.runscope.net\"],\"User-Agent\":[\"dwolla-webhooks/1.0\"],\"X-Dwolla-Topic\":[\"transfer_created\"],\"X-Request-Signature\":[\"bd93780bd7e1ad77ab821094aaa0f9e3dece5ee3\"]},\"host\":\"myapp.runscope.net\",\"method\":\"POST\",\"params\":{},\"path\":\"/\",\"region\":\"us5\",\"runscope_host\":\"prod078.runscope.in\",\"scheme\":\"https\",\"source\":\"capture\",\"source_ip\":\"52.24.10.184\",\"timestamp\":1.4459656543078682e+09,\"url\":\"https://myapp.runscope.net/\"}"
      }
    }
  ]
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

webhook = app_token.get webhook_url
webhook.topic # => "transfer_created"
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

$webhooksApi = new DwollaSwagger\WebhooksApi($apiClient);

$webhook = $webhooksApi->id($webhookUrl);
$webhook->topic; # => "transfer_created"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

webhook = app_token.get(transfer_url)
webhook.body['topic'] # => 'transfer_created'
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

appToken
  .get(webhookUrl)
  .then(res => res.body.topic); // => 'transfer_created'

Retry a webhook

This section details how to retry a webhook by id.

HTTP Request

POST https://api.dwolla.com/webhooks/{id}/retries

Request parameters

Parameter Required Type Description
id yes string Id of webhook to retry.

HTTP status and error codes

HTTP Status Message
404 Webhook not found.

Request and response

POST https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries/5aa27a0f-cf99-418d-a3ee-67c0ff99a494
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

app_token.post "#{webhook_url}/retries"
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

$webhooksApi = new DwollaSwagger\WebhooksApi($apiClient);

$webhooksApi->retryWebhook($webhookUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

app_token.post('%s/retries' % webhook_url)
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

appToken.post(`${webhookUrl}/retries`);

List retries for a webhook

This section covers how to retrieve webhook retries by id.

  1. This endpoint requires an OAuth application access token.

HTTP Request

GET https://api.dwolla.com/webhooks/{id}/retries

Request parameters

Parameter Required Type Description
id yes string Id of webhook to get retries for.

HTTP status and error codes

HTTP Status Message
404 Webhook not found.

Request and response

GET https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
    }
  },
  "_embedded": {
    "retries": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries/5aa27a0f-cf99-418d-a3ee-67c0ff99a494"
          },
          "webhook": {
            "href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8"
          }
        },
        "id": "5aa27a0f-cf99-418d-a3ee-67c0ff99a494",
        "timestamp": "2015-11-02T17:43:26.000Z"
      }
    ]
  },
  "total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

retries = app_token.get "#{webhook_url}/retries"
retries.total # => 1
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

$webhooksApi = new DwollaSwagger\WebhooksApi($apiClient);

$retries = $webhooksApi->retriesById($webhookUrl);
$retries->total; # => 1
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

retries = app_token.get('%s/retries' % webhook_url)
retries.body['total'] # => 1
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

appToken
  .get(`${webhookUrl}/retries`)
  .then(res => res.body.total); // => 1
Financial institutions play an important role in the Dwolla network.

Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.