Language

Introduction

Welcome to the Dwolla Access API documentation. Connect your software to the banking infrastructure. The Access API is white label by design, however some co-branded experiences and capabilities have been and will continue to be migrated from the legacy API v1 (no longer supported). For more information on transitioning v1 to the Access API, see our migration guide.

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.

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 intented 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 is required.",
                "path": "/firstName",
            }
        ]
    }
}

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 aide 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 Access API has officially maintained software packages to make it easier for developers to get started with making requests against the API. 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, and Python.

PHP and Java SDKs 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.

API Hosts

Production Sandbox
api.dwolla.com 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 fetch a page of customers:

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

DwollaSwagger Ruby

dwolla-swagger-ruby 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_swagger

Quickstart

Let’s list some Customer objects:

require 'dwolla_swagger'

DwollaSwagger::Swagger.configure do |config|
    config.access_token = 'a token'
    config.host = 'api-sandbox.dwolla.com'
    config.base_path = '/'
end

my_custies = DwollaSwagger::CustomersApi.list(: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})

DwollaSwagger Python

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

Installation

pip install dwollaswagger

Quickstart

Let’s list some Customer objects:

dwollaswagger.configuration.access_token = 'token'
client = dwollaswagger.ApiClient('https://api-sandbox.dwolla.com')

customers_api = dwollaswagger.CustomersApi(client)
my_custies =  customers_api.list(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);

?>

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 Access 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 client credentials), 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 which will invalidate the previous token.

Application authorization

The client credentials flow is used when an application needs to obtain permission to act on its own behalf. An application will exchange it’s client_id, client_secret, and grant_type=client_credentials for an application access token. An application access token can then be used to make calls to the Dwolla API on behalf of the application, for example, create a webhook subscription, retrieve events, and make calls to Access API Customer related endpoints. The primary reason for obtaining an application access token is for managing webhooks and events. However, Dwolla has modified this grant type by allowing applications to access Access API Customer related endpoints using the application access token.

HTTP request

Production: POST https://www.dwolla.com/oauth/v2/token

Sandbox: POST https://sandbox.dwolla.com/oauth/v2/token

Including the Content-Type: application/x-www-form-urlencoded header, the request is sent to the token endpoint with the following form-encoded parameters:

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://sandbox.dwolla.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

client_id=CGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkwasGMuGhkem9Bo&client_secret=g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5CcJSLqXIcDOxfTr&grant_type=client_credentials
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
# This example assumes you've already intialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
application_token = client.Auth.client()
// Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-node
// This example assumes you've already intialized 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 intialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
application_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 a user account access token is provided in the request, the API will return links to resources that belong to a Dwolla account of that user (i.e. “accounts” and “customers”). Alternatively, 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 = token.get "/"
root._links.account.href # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
/**
 *  No example for this language yet. Coming soon.
 **/
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
root = token.get('/')
root.body['_links']['account']['href'] # => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
root_api = dwollaswagger.RootApi(client)
an_account = root_api.root()
an_account._links['account']['href'] # => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'
token
  .get('/')
  .then(res => res.body._links.account.href); // => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'

Accounts

An Account represents an Access API partner Dwolla account that was established on dwolla.com.

Migrating Transfer user Accounts to Access API Customers

Dwolla offers a seamless process for migrating existing Transfer user Accounts managed via OAuth on your platform to Access API Customers. The user Account will maintain existing functionality on dwolla.com and will act as a separate Access API Customer upon completion of the migration. To learn more about upgrading to the Access 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 Accounts’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 Access 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.

Errors

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"
}
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
account = account_token.get account_url
account.name # => "Jane Doe"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
account = DwollaSwagger::AccountsApi.id(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"
?>
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

accounts_api = dwollaswagger.AccountsApi(client)

account = accounts_api.id(account_url)
print(account.name) # => Jane Doe
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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.
type 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 Access API partners.

Errors

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",
    "type": "checking",
    "name": "My Bank"
}

...

HTTP/1.1 201 Created
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).

Errors

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"
    }
  },
  "_embedded": {
    "funding-sources": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
          },
          "account": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          }
        },
        "id": "04173e17-6398-4d36-a167-9d98c4b1f1c3",
        "status": "verified",
        "type": "bank",
        "name": "First Midwestern Bank",
        "created": "2014-07-09T20:39:37.000Z"
      },
      {
        "_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"
          }
        },
        "id": "b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
        "status": "verified",
        "type": "balance",
        "name": "Balance",
        "created": "2014-07-09T20:39:33.000Z"
      }
    ]
  }
}
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
funding_sources = account_token.get "#{account_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe's Checking"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
funding_sources = DwollaSwagger::FundingsourcesApi.get_account_funding_sources(account_url)
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"
?>
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

fs_api = dwollaswagger.FundingsourcesApi(client)
funding_sources = fs_api.get_account_funding_sources(account_url)

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

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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 querystring parameters such as: search which represents a term to search on, startAmount, endAmount, startDate, and endDate.

  1. This endpoint requires an OAuth account access token with the Transactions scope.

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.
limit no integer Number of search results to return. Defaults to 25.
offset no integer Number of search results to skip. Used for pagination.

Errors

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
}
account_url = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
transfers = account_token.get "#{account_url}/transfers"
transfers._embedded.transfers[0].status # => "processed"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
transfers = DwollaSwagger::TransfersApi.get_account_transfers(account_url)
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"
?>
account_url = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
transfers = account_token.get('%s/transfers' % account_url)
transfers.body['_embedded']['transfers'][0]['status'] # => "processed"

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
transfers_api = dwollaswagger.TransfersApi(client)
transfers = transfers_api.get_account_transfers(account_url)
transfers._embedded['transfers'][0]['status'] # => "processed"
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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.

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"
        }
      }
    ]
  },
  "total": 1
}
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payments = account_token.get "#{account_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"
/**
 *  No example for this language yet. Coming soon.
 **/
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
transfers = account_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';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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.

  1. This section outlines functionality for the Access API, a premium product that only approved partners may access in production. To learn more about entering into an Access API agreement, please contact Sales.

Verified and unverified Customers

With a transfer of money, at least one party must complete the identity verification process, either the sender or the receiver. It’s your decision about which party completes this process, based on your business model, and you may want to have both parties complete the identity verification process. In cases where a Customer is sending funds to or receiving funds from your account, the Customer can remain unverified because your account is already verified. However, if you need to transfer funds between your Customers, at least one of them will need to be verified.

For more information on Access API account types, reference the account types resource article.

Receive-only

Receive-only customers are restricted to a “payouts only” business model. A receive-only customer maintains limited functionality in the API and is only eligible to receive transfers to an attached bank account from the Dwolla Account that created it.

Migrating Dwolla user Accounts to Access API Customers

Dwolla offers a seamless process for migrating existing user Accounts managed via OAuth on your platform to Access API Customers. The user Account will maintain existing functionality on dwolla.com and will act as a separate Access API Customer upon completion of the migration. To learn more about upgrading to the Access 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 authorized representaive 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-authorized-representative-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 authorized representative 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.
{
  "_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 Unverified Customers, you need to provide only the customer’s full name and email address. Verified Customers require additional information that will give Dwolla the ability 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 “authorized representative” for that business. For Receive-only Customers, you’ll provide the customer’s full name, type with the value of receive-only, and businessName if applicable.

For more information on verified Customers, reference our Customer verification resource article.

  1. This endpoint requires an OAuth account access token with the ManageCustomers scope.

HTTP request

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

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.
ipAddress no string Customer’s IP address.

Request parameters - verified Customer

Parameter Required Type Description
firstName yes string Customer or if business, authorized representative’s first name.
lastName yes string Customer or if business, authorized representative’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 below for additional required information.
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. Should be a five digit postal code, e.g. 50314.
dateOfBirth yes string Customer or if business, authorized representative’s date of birth in YYYY-MM-DD format.
ssn yes string Last four digits of the Customer’s Social Security Number.
phone no string Customer or if business, authorized representative’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.

Additional request parameters for verified Customer with type=business

Parameter Required Type Description
businessClassification yes string The industry classification id that corresponds to Customer’s business
businessType yes string Business structure. Possible values are corporation, llc, partnership, and soleproprietorship
businessName yes string Customer’s registered business name.
ein yes string Employer Identification Number. Note: If the businessType is a sole proprietorship then ein can be omitted from the request.
doingBusinessAs no string Name that is different from the officially registered name of Customer’s business.
website no string www.domain.com

Request parameters - receive-only

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.

Errors

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

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"
}

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

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = app_token.post "customers", request_body
customer.headers[:location] # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customer = DwollaSwagger::CustomersApi.create(:body => request_body)
customer # => "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"
?>
request_body = {
  'firstName': 'Jane',
  'lastName': 'Merchant',
  'email': 'jmerchant@nomail.net',
  'ipAddress': '99.99.99.99'
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
customer = customers_api.create(body = request_body)
customer # => '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'

Verified 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"
?>
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'
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = app_token.post "customers", request_body
customer.headers[:location] # => "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customer = DwollaSwagger::CustomersApi.create(:body => request_body)
customer # => "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C"
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'
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
customer = customers_api.create(body = request_body)
customer # => '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'

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
request_body = {
  :firstName => 'Jane',
  :lastName => 'Merchant',
  :email => 'jmerchant@nomail.net',
  :type => 'receive-only',
  :businessName => 'Jane Corp llc',
  :ipAddress => '99.99.99.99'
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = app_token.post "customers", request_body
customer.headers[:location] # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customer = DwollaSwagger::CustomersApi.create(:body => request_body)
customer # => "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"
?>
request_body = {
  'firstName': 'Jane',
  'lastName': 'Merchant',
  'email': 'jmerchant@nomail.net',
  'type': 'receive-only',
  'businessName': 'Jane Corp llc',
  'ipAddress': '99.99.99.99'
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
customer = customers_api.create(body = request_body)
customer # => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
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'

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": "9ed3f66a-7d6f-11e3-8acd-5404a6144203",
              "name": "Breweries"
            },
            {
              "id": "9ed3f66d-7d6f-11e3-9101-5404a6144203",
              "name": "Alcoholic beverage drinking places"
            },
            {
              "id": "9ed3f66e-7d6f-11e3-9480-5404a6144203",
              "name": "Beer, wine, and liquor store"
            },
            {
              "id": "9ed3f66b-7d6f-11e3-95ac-5404a6144203",
              "name": "Wineries"
            },
            {
              "id": "9ed3f674-7d6f-11e3-9619-5404a6144203",
              "name": "Tobacco"
            },
            {
              "id": "9ed3f673-7d6f-11e3-adb1-5404a6144203",
              "name": "Restaurant"
            },
            {
              "id": "9ed3f676-7d6f-11e3-af8e-5404a6144203",
              "name": "Supplement store"
            },
            {
              "id": "9ed3f675-7d6f-11e3-afad-5404a6144203",
              "name": "Pharmacy and drugstore"
            },
            {
              "id": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
              "name": "Coffee and tea"
            },
            {
              "id": "9ed3f66f-7d6f-11e3-b1df-5404a6144203",
              "name": "Catering services"
            },
            {
              "id": "9ed3f672-7d6f-11e3-b67a-5404a6144203",
              "name": "Specialty and miscellaneous food store"
            }
          ]
        },
        "id": "9ed3f669-7d6f-11e3-b545-5404a6144203",
        "name": "Food retail and service"
      }
      ...........
    ]
  },
  "total": 27
}

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": "9ed3cf5c-7d6f-11e3-8d0e-5404a6144203",
        "name": "Gambling"
      },
      {
        "id": "9ed3cf53-7d6f-11e3-8ee9-5404a6144203",
        "name": "Cable, satellite, and other pay TV and radio broadcasting"
      },
      {
        "id": "9ed3cf59-7d6f-11e3-9158-5404a6144203",
        "name": "Slot machines"
      },
      {
        "id": "9ed3cf57-7d6f-11e3-921d-5404a6144203",
        "name": "Theater tickets"
      },
      {
        "id": "9ed3cf4f-7d6f-11e3-97ea-5404a6144203",
        "name": "Motion picture and video"
      },
      {
        "id": "9ed3cf5a-7d6f-11e3-9a99-5404a6144203",
        "name": "Digital content"
      },
      {
        "id": "9ed3cf5b-7d6f-11e3-a368-5404a6144203",
        "name": "Entertainers"
      },
      {
        "id": "9ed3a867-7d6f-11e3-a6e4-5404a6144203",
        "name": "Memorabilia"
      },
      {
        "id": "9ed3cf52-7d6f-11e3-b0da-5404a6144203",
        "name": "Music store - CDs, cassettes and albums"
      },
      {
        "id": "9ed3cf5d-7d6f-11e3-b35e-5404a6144203",
        "name": "Online gaming"
      },
      {
        "id": "9ed3cf55-7d6f-11e3-b43c-5404a6144203",
        "name": "Adult digital content"
      },
      {
        "id": "9ed3cf51-7d6f-11e3-b49f-5404a6144203",
        "name": "Movie store - DVDs, videotapes"
      },
      {
        "id": "9ed3cf5e-7d6f-11e3-b9d5-5404a6144203",
        "name": "Video games and systems"
      },
      {
        "id": "9ed3cf56-7d6f-11e3-ba87-5404a6144203",
        "name": "Concert tickets"
      },
      {
        "id": "9ed3cf54-7d6f-11e3-bf23-5404a6144203",
        "name": "Cable and other subscription programming"
      }
    ]
  },
  "id": "9ed3a866-7d6f-11e3-a0ce-5404a6144203",
  "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, 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
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.
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 peramanent 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

Unverified and Verified Customers can be deactivated by specifying a status of deactivated in your request. A Customer cannot be deactivated if the following conditions are true: Customer has a suspended verification status, a Customer has transfers that are pending, or if there are funds available in the Customer’s balance(Verified Customers only).

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

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": {
    "self": {
      "href": "https://api.dwolla.com/customers/730CA23F-06C5-45CC-AA6B-8EC2D6EE109F"
    },
    "funding-sources": {
      "href": "https://api.dwolla.com/customers/730CA23F-06C5-45CC-AA6B-8EC2D6EE109F/funding-sources"
    },
    "transfers": {
      "href": "https://api.dwolla.com/customers/730CA23F-06C5-45CC-AA6B-8EC2D6EE109F/transfers"
    },
    "retry-verification": {
      "href": "https://api.dwolla.com/customers/730CA23F-06C5-45CC-AA6B-8EC2D6EE109F"
    }
  },
  "id": "730CA23F-06C5-45CC-AA6B-8EC2D6EE109F",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jdoe@nomail.com",
  "type": "personal",
  "status": "retry",
  "created": "2015-10-06T01:18:26.923Z"
}

Request and response

POST https://api-sandbox.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1
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"
}

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

$customerUrl = 'https://api.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F';
$customer = $customersApi->updateCustomer($customerUrl, 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',
));
$customer->id; # => "FC451A7A-AE30-4404-AB95-E3553FCD733F"
?>
customer_url = 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
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"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = app_token.post customer_url, request_body
customer.id # => "FC451A7A-AE30-4404-AB95-E3553FCD733F"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customer = DwollaSwagger::CustomersApi.update_customer(customer_url, :body => request_body)
customer.id # => "FC451A7A-AE30-4404-AB95-E3553FCD733F"
customer_url = 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
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"
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = app_token.post('customers', request_body)
customer.body.id # => 'FC451A7A-AE30-4404-AB95-E3553FCD733F'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
customer = customers_api.update_customer(customer_url, body = request_body)
customer.id # => 'FC451A7A-AE30-4404-AB95-E3553FCD733F'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F';
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); // => 'FC451A7A-AE30-4404-AB95-E3553FCD733F'

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.
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.

Errors

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)

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 (Recommended)
customers = app_token.get "customers", limit: 10
customers._embedded.customers[0].firstName # => "Jane"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customers = DwollaSwagger::CustomersApi.list(: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 (Recommended)
customer = app_token.get('customers', limit = 10)
customer.body['_embedded']['customers'][0]['firstName'] # => 'Jane'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
customers = customers_api.list(limit = 10)
customers._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.

Errors

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"
}
customer_url = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = app_token.get customer_url
customer.firstName # => "Jane"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customer = DwollaSwagger::CustomersApi.get_customer(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"
?>
customer_url = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = app_token.get(customer_url)
customer.body['firstName']

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
customer = customers_api.get_customer(customer_url)
customer.firstName # => 'Jane'
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 Access 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"
/**
 * No example for this language yet.
 **/
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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 Access 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.
type 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 Access API partners.

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",
  "type": "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",
  "type" => "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"
?>
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  routingNumber: '222222226',
  accountNumber: '123456789',
  type: 'checking',
  name: 'Jane Doe’s Checking'
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
funding_source = app_token.post "#{customer_url}/funding-sources", request_body
funding_source.headers[:location] # => "https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
funding_source = DwollaSwagger::FundingsourcesApi.create_customer_funding_source(customer_url, :body => request_body)
funding_source # => "https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'type': 'checking',
  'name': 'Jane Doe’s Checking'
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
funding_api = dwollaswagger.FundingsourcesApi(client)
funding_source = funding_api.create_customer_funding_source(customer_url, body = request_body)
funding_source # => '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',
  'type': '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' }, 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.

Errors

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"
}
customer_url = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = app_token.post "#{customer_url}/iav-token"
customer.token # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
customer = DwollaSwagger::CustomersApi.get_customer_iav_token(customer_url)
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'
customer_url = 'http://api.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'
customers_api = dwollaswagger.CustomersApi(client)

token = customers_api.get_customer_iav_token(customer_url)
print token['token'] # => 'lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL'
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$fsToken = $customersApi->getCustomerIavToken("https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6");
$fsToken->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 querystring 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).

Errors

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"
      },
      {
        "_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",
        "name": "Jane Doe’s Checking",
        "created": "2015-10-02T22:03:45.537Z"
      }
    ]
  }
}
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
funding_sources = app_token.get "#{customer}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe’s Checking"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
funding_sources = DwollaSwagger::FundingsourcesApi.get_customer_funding_sources(customer_url)
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"
?>
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_sources = app_token.get('%s/funding-sources' % customer_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Jane Doe’s Checking'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
fs_api = dwollaswagger.FundingsourcesApi(client)
funding_sources = fs_api.get_customer_funding_sources(customer_url)
funding_sources._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, startAmount, endAmount, startDate, and endDate.

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.
limit no integer Number of search results to return. Defaults to 25.
offset no integer Number of search results to skip. Used for pagination.

Errors

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
}
customer_url = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
transfers = app_token.get "#{customer_url}/transfers"
transfers._embedded.transfers[0].status # => "pending"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
transfers = DwollaSwagger::TransfersApi.get_customer_transfers(customer_url)
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"
?>
customer_url = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
transfers = app_token.get('%s/transfers' % customer_url)
transfers.body['_embedded']['transfers'][0]['status'] # => 'pending'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
transfers_api = dwollaswagger.TransfersApi(client)
transfers = transfers_api.get_customer_transfers(customer_url)
transfers._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.

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"
        }
      }
    ]
  },
  "total": 1
}
customer_url = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payments = app_token.get "#{customer_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"
/**
 *  No example for this language yet. Coming soon.
 **/
customer_url = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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"

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 verifiation 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, ScanNameMismatch, ScanFailedOther, or FailedOther.
{
  "_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, .tif, or .pdf up to 10MB in size.

HTTP request

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/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.headers[:location] # => "https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
customer_url = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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
}
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
documents = token.get "#{customer_url}/documents"
documents._embedded.documents[0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
documents = DwollaSwagger::CustomersApi.get_customer_documents(customer_url)
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
?>
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
documents = app_token.get('%s/documents' % customer_url)
documents.body['total'] # => 2

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
customers_api = dwollaswagger.CustomersApi(client)
documents = customers_api.get_customer_documents(customer_url)
documents.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"
}
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
document = app_token.get document_url
document.type # => "passport"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
document = DwollaSwagger::DocumentsApi.get_document(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"
?>
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
documents = app_token.get(document_url)
documents.body['type'] # => 'passport'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
documents_api = dwollaswagger.DocumentsApi(client)
document = documents_api.get_customer(document_url)
document.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.

Funding source resource

Parameter Description
id The funding source unique identifier.
status A status of either unverified or verified specifying if the funding source has completed verification.
type Type of funding source. Either bank or balance.
name Customer’s arbitrary nickname for the funding source.
created ISO-8601 timestamp.
removed A value of true if the funding source has been removed or false if the funding source is not removed.
channels An array containing a list of processing channels. ACH is the default processing channel for bank transfers. Can be either ach or wire.
bankName The financial institution name.
{
    "routingNumber": "222222226",
    "accountNumber": "123456789",
    "type": "checking",
    "name": "My Bank"
}

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.

Errors

HTTP Status Message
404 Funding source not found.

Request and response

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

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c"
    },
    "customer": {
      "href": "https://api-sandbox.dwolla.com/customers/36e9dcb2-889b-4873-8e52-0c9404ea002a"
    },
    "initiate-micro-deposits": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c/micro-deposits"
    }
  },
  "id": "692486f8-29f6-4516-a6a5-c69fd2ce854c",
  "status": "unverified",
  "type": "bank",
  "name": "Test checking account",
  "created": "2015-10-23T20:37:57.137Z"
}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
funding_source = app_token.get funding_source_url
funding_source.name # => "Test checking account"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
funding_source = DwollaSwagger::FundingsourcesApi.id(funding_source_url)
funding_source.name # => "Test checking account"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

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

$fundingSource = $fsApi->id($fundingSourceUrl);
$fundingSource->name; # => "Test checking account"
?>
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_source = app_token.get(funding_source_url)
funding_source.body['name'] # => 'Test checking account'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
fs_api = dwollaswagger.FundingsourcesApi(client)
funding_source = fs_api.id(funding_source_url)
funding_source.name # => 'Test checking account'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

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, 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, or all three 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.
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"
}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
      "name" => "Test Checking - 1234",
}

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_source = app_token.post('funding-sources', 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 can be either of type balance or bank.

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 retreive 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 (Recommended)
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);
?>
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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
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
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
app_token.post "#{funding_source_url}/micro-deposits"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
DwollaSwagger::FundingsourcesApi.micro_deposits(funding_source_url)
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
app_token.post('%s/micro-deposits' % funding_source_url)

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
fs_api = dwollaswagger.FundingsourcesApi(client)
fs_api.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 verified
202 TryAgainLater “Invalid wait time.”
400 ValidationError InvalidAmount
400 ValidationError “Wrong amount(s).”
403 InvalidResourceState “Too many attempts.”
403 InvalidResourceState “Bank already verified.”
404 NotFound Micro deposits not initiated
404 NotFound Funding source not found
500 Unknown “Verify microdeposits 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
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"
  }
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
app_token.post "#{funding_source_url}/micro-deposits", request_body

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
DwollaSwagger::FundingsourcesApi.micro_deposits(funding_source_url, body: 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);
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"
    }
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
app_token.post('%s/micro-deposits' % funding_source_url, request_body)

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
fs_api = dwollaswagger.FundingsourcesApi(client)
fs_api.micro_deposits(funding_source_url, body = 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.

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"
  }
}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
funding_source = app_token.get "#{funding_source_url}/micro-deposits"
funding_source.status # => "failed"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
funding_source = DwollaSwagger::FundingsourcesApi.verify_micro_deposits_exist(funding_source_url)
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"
?>
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_source = app_token.get('%s/micro-deposits' % funding_source_url)
funding_source.body['status'] # => 'failed'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
fs_api = dwollaswagger.FundingsourcesApi(client)
funding_source = fs_api.verify_micro_deposits_exist(funding_source_url)
funding_source.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 id of funding source to delete.
removed yes Specify a value of true to remove the associated funding source.

Errors

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",
  "name": "Test bank account",
  "created": "2016-06-08T21:37:30.000Z",
  "removed": true
}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

request_body = {
  :removed => true
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
app_token.post "#{funding_source_url}", request_body

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
DwollaSwagger::FundingsourcesApi.soft_delete(funding_source_url, :body => 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);
?>
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
  "removed": true
}
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_source = app_token.post('funding-sources', 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.

Transfer resource

Parameter Description
id Transfer unique identifier
status Either processed, pending, cancelled, failed, or reclaimed
amount An amount JSON object. See below
created ISO-8601 timestamp
metadata A metadata JSON object
clearing
{
  "_links": {},
  "_embedded": {},
  "id": "string",
  "status": "string",
  "amount": {
    "value": "string",
    "currency": "string"
  },
  "created": "2015-10-02T19:48:40.485Z",
  "metadata": {}
}

Amount JSON object

Parameter Description
value Amount of money
currency String, USD

Initiate a transfer

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

  1. This endpoint requires an OAuth account access token with the Send scope.

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. See below for possible values for source and destination.
amount yes object An amount JSON object. See above.
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. See below.
clearing no object A clearing JSON object that contains source and destination keys. Acceptable value for source is: standard. Acceptable value for destination is: next-available. 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 Access API partners. Next-day ACH functionality must be enabled.

Source and destination types

Source Type URI Description
Funding source https://api.dwolla.com/funding-sources/{id} A bank or balance funding source.
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.
Email mailto:johndoe@email.com Email address of existing Dwolla Account or recipient (recipient will create a Dwolla Account to claim funds)

Facilitator fee

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.

A fee JSON object

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

Fee object example:

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

HTTP Status and Error Codes

HTTP Status Message
400 Transfer failed.
403 OAuth token does not have Send scope.

Request and response (using Same Day ACH)

The reference example below shows what a request looks like when sending a transfer. Please note this example is using same-day clearing to an Access API Customer’s bank account, part of Dwolla’s Access 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"
    },
    "clearing": {
        "destination": "next-available"
  }
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388
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"
  }
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
transfer = account_token.post "transfers", request_body
transfer.headers[:location] # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
transfer = DwollaSwagger::TransfersApi.create(:body => request_body)
transfer # => "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'
  ]
]);
$transfer; # => "https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
?>
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'
  }
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
transfer = account_token.post('transfers', request_body)
transfer.headers['location'] # => 'https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
transfers_api = dwollaswagger.TransfersApi(client)
transfer = transfers_api.create(body = request_body)
transfer # => 'https://api-sandbox.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'
  }
};

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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.

  1. This endpoint requires an OAuth account access token with the Transactions scope.

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.

Errors

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"
  }
}
transfer_url = 'https://api.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
transfer = account_token.get transfer_url
transfer.status # => "pending"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
transfer = DwollaSwagger::TransfersApi.by_id(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"
?>
transfer_url = 'https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
fees = account_token.get(transfer_url)
fees.body['stats'] # => 'pending'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
transfers_api = dwollaswagger.TransfersApi(client)
transfer = transfers_api.by_id(transfer_url)
transfer.status # => 'pending'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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.

  1. This endpoint requires an OAuth account access token with the Transactions scope.

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.

Errors

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
}
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
fees = account_token.get "#{transfer_url}/fees"
fees.total # => 2
/**
 *  No example for this language yet.
 **/
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
fees = account_token.get('%s/fees' % transfer_url)
fees.body['total'] # => 2
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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.

  1. This endpoint requires an OAuth account access token with the Transactions scope.

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": "R1",
  "description": "Insufficient Funds"
}
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
failure = account_token.get "#{transfer_url}/failure"
failure.code # => "R1"
/**
 *  No example for this language yet.
 **/
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
# For Access API applications, an app_token can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
failure = account_token.get('%s/failure' % transfer_url)
failure.body['code'] # => 'R1'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .get(`${transferUrl}/failure`)
  .then(res => res.body.code); // => 'R1'

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.

  1. This endpoint requires an OAuth account access token with the Transactions scope.

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"
  }
}

MassPay

Dwolla MassPay 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.

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 MassPay to be completed between 8-16 minutes.

MassPay offers a significant advantage over repeatedly calling the Transfers endpoint for each individual transaction. This benefit is the fact that a bank-funded MassPay only incurs a single ACH debit from the bank account to fund the entire batch of payments. The alternative approach will incur a 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 payment 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.
{
  "_links": {},
  "_embedded": {},
  "id": "string",
  "status": "string",
  "created": "2016-03-11T15:52:58.289Z",
  "metadata": {},
  "total": {},
  "totalFees": {}
}

Initiate a mass payment

This section covers how to initiate a mass payment from a Partner Dwolla Account or Verified Customer resource. A mass payment contains a list of items representing individual payments. Optionally, mass payments can contain metadata 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.

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. See below for 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.

Source and destination values

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 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 Access API Customer of a transfer.
Account https://api.dwolla.com/accounts/{id} Destination Transfer Account of a transfer.
Email mailto:johndoe@email.com Email address of existing Transfer Account or recipient (recipient will create a Transfer Account to claim funds)

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).

Item object example:

{
  "_links": {
      "destination": {
          "href": "https: //api.dwolla.com/funding-sources/01B47CB2-52AC-42A7-926C-6F1F50B1F271"
      }
  },
  "amount": {
      "currency": "USD",
      "value": "1.00",
  },
  "metadata": {
      "key1": "value1"
  }
}

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, or Invalid funding source.
401 NotAuthorized OAuth token does not have Send scope.

Request and response (masspayment 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"
        }
    },
    "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"
        }
      },
            {
        "_links": {
            "destination": {
                "href": "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
            }
        },
        "amount": {
            "currency": "USD",
            "value": "5.00"
        },
        "metadata": {
            "payment2": "payment2"
        }
      }
    ],
    "metadata": {
        "batch1": "batch1"
    }
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/mass-payments/d093bcd1-d0c1-41c2-bcb5-a5cc011be0b7
request_body = {
  _links: {
    source: {
      href: "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    }
  },
  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"
      }
    },
    {
      _links: {
        destination: {
          href: "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
        }
      },
      amount: {
        currency: "USD",
        value: "5.00"
      },
      metadata: {
        payment2: "payment2"
      }
    }
  ],
  metadata: {
    batch1: "batch1"
  }
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payment = account_token.post "mass-payments", request_body
mass_payment.headers[:location] # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"
/**
 *  No example for this language yet. Coming soon.
 **/
# No example for this language yet. Coming soon.
var requestBody = {
  _links: {
    source: {
      href: 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  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'
      }
    },
    {
      _links: {
        destination: {
          href: 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd'
        }
      },
      amount: {
        currency: 'USD',
        value: '5.00'
      },
      metadata: {
        payment2: 'payment2'
      }
    }
  ],
  metadata: {
    batch1: 'batch1'
  }
}

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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": {}
}
mass_payment_url = "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payment = account_token.get mass_payment_url
mass_payment.status # => "processing"
/**
 *  No example for this language yet. Coming soon.
 **/
# No example for this language yet. Coming soon.
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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"
}
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
      "status" => "pending",
}

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
mass_payments = account_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"
};

accountToken
  .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).

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"
          },
          "mass-payment": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
          },
          "destination": {
            "href": "https://api-sandbox.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd"
          },
          "transfer": {
            "href": "https://api-sandbox.dwolla.com/transfers/fb3999db-41ed-e511-80df-0aa34a9b2388"
          }
        },
        "id": "30845bc9-41ed-e511-80df-0aa34a9b2388",
        "status": "success",
        "amount": {
          "value": "2.00",
          "currency": "USD"
        },
        "metadata": {
          "item2": "item2"
        }
      }
    ]
  },
  "total": 2
}
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payment_items = account_token.get "#{mass_payment_url}/items"
mass_payment_items.total # => 2
/**
 *  No example for this language yet. Coming soon.
 **/
# No example for this language yet. Coming soon.
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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"
  }
}
mass_payment_item_url = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payment_item = account_token.get mass_payment_item_url
mass_payment_item.status # => "success"
/**
 *  No example for this language yet. Coming soon.
 **/
mass_payment_item_url = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
mass_payment_item = account_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';

// For Access API applications, an appToken can be used for this endpoint. (https://docsv2.dwolla.com/#application-access-token)
accountToken
  .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"
}

Event topics - (Partner Dwolla Account)

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.
microdeposits_added Two <=10¢ transfers to a Dwolla account’s linked bank account were initiated.
microdeposits_failed The two <=10¢ transfers to a Dwolla account’s linked bank account failed to clear successfully.
microdeposits_completed The two <=10¢ transfers to a Dwolla account’s linked bank account have cleared successfully.
microdeposits_maxattempts The account has reached their max verification attempts limit of three. The account can no longer verify their funding source with the completed micro-deposit amounts.
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_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.
account_suspended An account was suspended.
account_activated A Dwolla account moves from deactive or suspended to active state of verification.

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 deactive or suspended to active state of verification.
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_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.
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_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.
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.

List events

Retrieve a list of events for the application.

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

Errors

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 (Recommended)
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 (Recommended)
events = app_token.get('events')
events.body['total'] # => 3

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
events_api = dwollaswagger.EventsApi(client)
events = events_api.events()
events.total # => 3
applicationToken
  .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.

Errors

HTTP Status Message
404 Application event not found.

Request and response

GET htttps://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"
}
event_url = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
event = app_token.get event_url
event.topic # => "customer_transfer_created"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
event = DwollaSwagger::EventsApi.id(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"
?>
event_url = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
event = app_token.get(event_url)
event.body['topic'] # => 'customer_transfer_created'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
events_api = dwollaswagger.EventsApi(client)
event = events_api.id(event_url)
event.topic # => 'customer_transfer_created'
var eventUrl = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095';

applicationToken
  .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. 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 to ensure that unavailable endpoints don’t cause delays or issues in delivery of notifications for other API partners. 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 20 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.

  1. This endpoint requires an OAuth application access token.

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"
}
request_body = {
  :url => "http://myawesomeapplication.com/destination",
  :secret => "your webhook secret"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
subscription = app_token.post "webhook-subscriptions", request_body
subscription.headers[:location] # => "https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
subscription = DwollaSwagger::WebhooksubscriptionsApi.create(:body => request_body)
subscription # => "https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"
var requestBody = {
  url: 'http://myawesomeapplication.com/destination',
  secret: 'your webhook secret'
};

applicationToken
  .post('webhook-subscriptions', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
request_body = {
  'url': 'http://myapplication.com/webhooks',
  'secret': 'sshhhhhh'
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
retries = app_token.post('webhook-subscriptions', request_body)
retries.body['total'] # => 1

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhook_api = dwollaswagger.WebhooksubscriptionsApi(client)
subscription = webhook_api.create(body = request_body)
subscription # => 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
<?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.

  1. This endpoint requires an OAuth application access token.

HTTP request

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

Request parameters

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

Errors

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"
}
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
webhook_subscription = app_token.get webhook_subscription_url
webhook_subscription.created # => 2015-10-28T16:20:47+00:00

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
webhook_subscription = DwollaSwagger::WebhooksubscriptionApi.id 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';

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
webhook_subscription = app_token.get(webhook_subscription_url)
webhook_subscription.body['created'] # => '2015-10-28T16:20:47+00:00'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhook_api = dwollaswagger.WebhooksubscriptionsApi(client)
retrieved = webhook_api.id(webhook_subscription_url)
retrieved.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.

  1. This endpoint requires an OAuth application access token.

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.

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
}
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

request_body = {
  :paused => true
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
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
};

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

request_body = {
  'paused': true
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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.

  1. This endpoint requires an OAuth application access token.

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 (Recommended)
webhook_subscriptions = app_token.get "webhook-subscriptions"
webhook_subscriptions.total # => 1

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
webhook_subscriptions = DwollaSwagger::WebhooksubscriptionsApi.list
webhook_subscriptions.total # => 1
applicationToken
  .get('webhook-subscriptions')
  .then(res => res.body.total); // => 1
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
webhook_subscriptions = app_token.get('webhook-subscriptions')
webhook_subscriptions.body['total'] # => 1

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhook_api = dwollaswagger.WebhooksubscriptionsApi(client)
retrieved = webhook_api.list()
retrieved.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.

  1. This endpoint requires an OAuth application access token.

HTTP request

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

Request parameters

Parameter Required Type Description
id yes string Webhook unique identifier.

Errors

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
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
app_token.delete webhook_subscription_url

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
DwollaSwagger::WebhooksubscriptionApi.delete_by_id(webhook_subscription_url)
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
app_token.delete(webhook_subscription_url)

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhook_api = dwollaswagger.WebhooksubscriptionsApi(client)
webhook_api.delete_by_id(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.

  1. This endpoint requires an OAuth application access token.

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"
          }
        }
      ]
    }
  ]
}
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
hooks = app_token.get "#{webhook_subscription_url}/webhooks"
hooks.total # => 5

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
hooks = DwollaSwagger::WebhooksApi.hooks_by_id webhook_subscription_url
hooks.total # => 5
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
hooks = app_token.get('%s/hooks' % webhook_subscription_url)
hooks.body['total'] # => 5

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhook_api = dwollaswagger.WebhooksApi(client)
hooks = webhook_api.hooks_by_id(webhook_subscription_url)
hooks.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.

  1. This endpoint requires an OAuth application access token.

HTTP request

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

Request parameters

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

Errors

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/\"}"
      }
    }
  ]
}
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
webhook = app_token.get webhook_url
webhook.topic # => "transfer_created"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
webhook = DwollaSwagger::WebhooksApi.id(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"
?>
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
webhook = app_token.get(transfer_url)
webhook.body['topic'] # => 'transfer_created'

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhooks_api = dwollaswagger.WebhooksApi(client)
webhook = webhooks_api.id(webhook_url)
webhook.topic # => 'transfer_created'
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

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

Retry a webhook

This section details how to retry a webhook by id.

  1. This endpoint requires an OAuth application access token.

HTTP Request

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

Request parameters

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

Errors

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
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
app_token.post "#{webhook_url}/retries"

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
DwollaSwagger::WebhooksApi.retry_webhook(webhook_url)
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

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

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
app_token.post('%s/retries' % webhook_url)

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhooks_api = dwollaswagger.WebhooksApi(client)
webhooks_api.retry_webhook(webhook_url)
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

applicationToken.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.

Errors

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
}
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
retries = app_token.get "#{webhook_url}/retries"
retries.total # => 1

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
retries = DwollaSwagger::WebhooksApi.retries_by_id(webhook_url)
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
?>
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
retries = app_token.get('%s/retries' % webhook_url)
retries.body['total'] # => 1

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
webhooks_api = dwollaswagger.WebhooksApi(client)
retries = webhooks_api.retries_by_id(webhook_url)
retries.total # => 1
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

applicationToken
  .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 Compass Bank and all funds associated with your account in the Dwolla network are held in pooled accounts at Veridian Credit Union and Compass Bank. These funds are not eligible for individual insurance, including FDIC insurance and 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 and Compass Bank.