Language

Introduction

Welcome to the Dwolla API V2 documentation, with ongoing updates as functionality is released to the API. We plan to implement API V1 functionality in API V2, but in the meantime, the two versions will operate in parallel.

The initial focus of API Version 2 centers around a premium product: white label, and provides different functionality from API Version 1. Over time, we are adding the same functionality currently available in V1 to V2.

Official SDKs for Java, Node.JS, PHP, Ruby, and Python are being actively developed.

Please note: white label is a premium product that cannot be activated in our production environment until you’ve received our approval to use it and have entered into an agreement with us. Please contact a sales representative to find a package that best meets your needs.

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 an client_id and client_secret are passed in the JSON request body for POST requests or as querystring parameters for GET requests:

GET https://api.dwolla.com/example?client_id={client_id}&client_secret={client_secret}

API Host

Production: https://api.dwolla.com

Sandbox: https://api-uat.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-uat.dwolla.com/customers/d795f696-2cac-4662-8f16-95f1db9bddd8"
        },
        "source": {
            "href": "http://api-uat.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "1337.00"
    }
}' "https://api-uat.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"
}

SDK Support

The Dwolla API V2 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.

Each SDK is automatically versioned with the Dwolla API Schema; all libraries (with the exception of JavaScript) are organized in a similar manner. 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.

API Hosts

Production Sandbox
api.dwolla.com api-uat.dwolla.com

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-uat.dwolla.com'
    config.base_path = '/'
end

my_custies = DwollaSwagger::CustomersApi.list(:limit => 10)

DwollaV2 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'

# see dwolla.com/applications for your client id and secret
$dwolla = DwollaV2::Client.new(id: "...", secret: "...")

# generate a token on dwolla.com/applications
account_token = $dwolla.tokens.new access_token: "..."

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

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-uat.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-uat.dwolla.com/");

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

?>

Java

dwolla-swagger-java will soon be available on Maven Central with source code available on our GitHub page. 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-uat.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:

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

# see dwolla.com/applications for your client id and secret
var client = new dwolla.Client({id: "...", secret: "..."});

# generate a token on dwolla.com/applications
var accountToken = new client.Token({access_token: "..."});

accountToken
  .get('customers', { limit: 10 })
  .then(function(res) {
    console.log(res.body);
  });

OAuth

Dwolla’s API lets you interact with a user’s Dwolla account and act on its behalf to transfer money, add funding sources, and more. To do so, your application first needs to request authorization from users.

Dwolla implements the OAuth 2.0 standard to facilitate this authorization. Similar to Facebook and Twitter’s authentication flow, the user is first presented with a permission dialog for your application, at which point the user can either approve the permissions requested, or reject them. Once the user approves, an authorization_code is sent to your application, which will then be exchanged for an access_token and a refresh_token pair.

The access_token can then be used to make API calls which require user authentication like Initiate a Transfer or List Transfers.

Token lifetimes

Access tokens are short lived: 1 hour.

Refresh tokens are long lived: 60 days.

A refresh token can be used within 60 days to generate a new access_token and refresh_token pair. So long as you refresh your authorization at least every 60 days, your application can maintain authorization indefinitely without requiring the user to re-authorize.

Request user authorization

To start the OAuth process, construct the initiation URL which the user will visit in order to grant permission to your application. It describes the permissions your application requires (scope), who the client application is (client_id), and where the user should be redirected to after they grant or deny permissions to your application (redirect_uri).

URL Format:

Production

https://www.dwolla.com/oauth/v2/authenticate?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope={scope}

UAT(Sandox)

https://uat.dwolla.com/oauth/v2/authenticate?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope={scope}

Request parameters

Parameter Required Type Description
client_id yes string Application key.
response_type yes string This must always be set to code.
redirect_uri yes string URL where the user will be redirected to afterwards. The value of this parameter must match one of the values that appear in your application details page. (We compare: protocol, subdomain, domain, tld, and file path. Querystring parameters are ignored)
scope yes string Permissions you are requesting. See below for list of available scopes. Scopes are delimited by a pipe (“|”)
verified_account no string Require new users opting to register for Dwolla to create a fully-verified Dwolla account instead of a default lightweight Direct account.
dwolla_landing no string An optional override that force displays either the login or create an account screen. Possible values are: login, register, or null.
  1. Remember to url-encode all querystring parameters!

OAuth scopes

Applications may request the following permission scopes when generating an access token:

Scope Name Description
Transactions Access the user’s transfer data
Send Transfer money on the user’s behalf
Funding Access names of funding sources the user has connected to Dwolla, access available balance information for Dwolla Balance and Dwolla Credit (if applicable), add new funding sources, verify funding sources, initiate transfers to and from funding sources.
ManageCustomers Includes create Customers, manage their funding sources, and allow related money movement
/**
 *  No example for this language yet.
 **/
# you can find your client id and secret at dwolla.com/applications
client = dwollav2.Client(id = '...', secret = '...')

state = binascii.b2a_hex(os.urandom(15))
client.Auth(redirect_uri = 'https://yoursite.com/callback',
            scope = 'ManageCustomers|Funding',
            state = state)

# redirect the user to dwolla.com for authorization
redirect_to(auth.url)

# exchange the code for a token
token = auth.callback({'code': '...', 'state': state})
// where to send the user after they grant permission:
var redirect_uri = "https://www.myredirect.com/redirect";  

// generate OAuth initiation URL
var authUrl = Dwolla.authUrl(redirect_uri);
# config/initializers/dwolla.rb
# you can find your client id and secret at dwolla.com/applications
$dwolla = DwollaV2::Client.new(id: "...", secret: "...")

# app/controllers/your_auth_controller.rb
class YourAuthController
  # redirect the user to dwolla.com/oauth/v2/authenticate
  def authenticate
    redirect_to auth.url
  end

  # exchange the code for a token
  def callback
    token = auth.callback(params)
  end

  private

  def auth
    $dwolla.auths.new redirect_uri: "https://www.myredirect.com/redirect",
                      scope: "send|funding",
                      state: session[:state] ||= SecureRandom.hex
  end
end
not applicable

Example initiation URL (where you send the user):

https://uat.dwolla.com/oauth/v2/authenticate?client_id=PO%2BSzGAsZCE4BTG7Cw4OAL40Tpf1008mDjGBSVo6QLNfM4mD%2Ba&response_type=code&redirect_uri=https://developers.dwolla.com/dev/token/callback?env=sandbox&scope=Balance%7CAccountInfoFull

Finish user authorization

Once the user returns to your application via the redirect_uri you specified, there will be a code querystring parameter appended to that URL. Exchange the authorization code for an access_token and refresh_token pair.

HTTP request

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

UAT: POST https://uat.dwolla.com/oauth/v2/token

Request parameters

Parameter Required Type Description
client_id yes string Application key.
client_secret yes string Application secret.
code yes string The authorization code included in the redirect URL. Single use code with an expiration of 30 minutes.
grant_type yes string This must be set to authorization_code.
redirect_uri yes string The same redirect_uri specified in the intiation step.

Response parameters

Parameter Description
_links Contains a link to the associated user account resource
access_token A new access token with requested scopes
expires_in The lifetime of the access token, in seconds. Default is 3600.
refresh_token New refresh token
refresh_expires_in The lifetime of the refresh token, in seconds. Default is 5184000.
token_type Always bearer.
scope Pipe | delimited list of permission scopes granted
account_id A unique user account ID for the associated user account
{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr",
  "code": "h6TvQZH+5BsV//O43uOJ0uRkBLk=",
  "grant_type": "authorization_code",
  "redirect_uri": "https://www.myredirect.com/redirect"
}

Successful response:

{
  "_links": {
    "account": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    }
  },
  "access_token": "sdWPNdPyteKlVEmudKa9K2oFGs4s7VpiGfxBGFyDsolvuveafk",
  "expires_in": 3600,
  "refresh_token": "EDidiHt28eRzthBlXvDDECz67wK3rNEA2fGdq46t8jOYqAuC4N",
  "refresh_expires_in": 5184000,
  "token_type": "bearer",
  "scope": "send|transactions|funding|managecustomers",
  "account_id": "ca32853c-48fa-40be-ae75-77b37504581b"
}

Refresh authorization

Use a valid refresh_token to generate a new access_token and refresh_token pair.

NOTE: The refresh_token you receive will change every time you exchange either an authorization_code or refresh_token for a new token pair. However, If you exchange your last valid refresh_token within a short timespan of being issued a new token pair, Dwolla will return most recently issued token pair for a short duration of time.

HTTP request

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

UAT: POST https://uat.dwolla.com/oauth/v2/token

Request parameters

Parameter Required Type Description
client_id yes string Application key.
client_secret yes string Application secret.
refresh_token yes string A valid refresh token.
grant_type yes string This must be set to refresh_token.

Response parameters

Parameter Description
_links Contains a link to the associated user account resource
access_token A new access token with requested scopes
expires_in The lifetime of the access token, in seconds. Default is 3600.
refresh_token New refresh token
refresh_expires_in The lifetime of the refresh token, in seconds. Default is 5184000.
token_type Always bearer.
scope Pipe | delimited list of permission scopes granted
account_id A unique user account ID for the associated user account
{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr",
  "refresh_token": "Pgk+l9okjwTCfsvIvEDPrsomE1er1txeyoaAkTIBAuXza8WvZY",
  "grant_type": "refresh_token"
}

Successful response

{
  "_links": {
    "account": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    }
  },
  "access_token": "F3jK4rg7FGlq4yRQ7vWECoXVD4zQq9Xg26VnxzMbHGusZqr7dF",
  "expires_in": 3600,
  "refresh_token": "DRlqGJ0IFsRK8xzjkKhjTOgz3meet6E91T2oacGCefHGU4h1hj",
  "refresh_expires_in": 5184000,
  "token_type": "bearer",
  "scope": "send|transactions|funding|managecustomers",
  "account_id": "ca32853c-48fa-40be-ae75-77b37504581b"
}

Invalid or expired refresh token response

{
  "error": "access_denied",
  "error_description": "Invalid refresh token."
}
{
  "error": "access_denied",
  "error_description": "Expired refresh token."
}

Application access token

Some endpoints require an application access token, which is different from a user access token. Application access tokens don’t require any particular user’s authorization, since they grant your application access to resources which belong to the application itself (i.e. events, webhooks, and webhook-subscriptions), rather than an account. Provide your client credentials to receive an application access token.

HTTP request

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

UAT: POST https://uat.dwolla.com/oauth/v2/token

Request parameters

Parameter Required Type Description
client_id yes string Application key.
client_secret yes string Application secret.
grant_type yes string This must be set to client_credentials.

Response parameters

Parameter Description
access_token A new access token with requested scopes
expires_in The lifetime of the access token, in seconds. Default is 3600.
token_type Always bearer.
scope Pipe | delimited list of permission scopes granted
{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr",
  "grant_type": "client_credentials"
}

Successful response

{
  "access_token": "SF8Vxx6H644lekdVKAAHFnqRCFy8WGqltzitpii6w2MVaZp1Nw",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "AccountInfoFull|ManageAccount|Contacts|Transactions|Balance|Send|Request|Funding"
}

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

  1. This endpoint requires an OAuth account access token or an Application access token but does not require a particular scope.

HTTP request

GET https://api.dwolla.com/

Request and response

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

...

{
  "_links": {
    "account": {
      "href": "https://api-uat.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
    },
    "customers": {
      "href": "https://api-uat.dwolla.com/customers"
    }
  }
}
root = account_token.get "/"
root._links.account.href # => "https://api-uat.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 = account_token.get('/')
root.body['_links']['account']['href'] # => 'https://api-uat.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-uat.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'
accountToken
  .get('/')
  .then(function(res) {
    res.body._links.account.href; // => 'https://api-uat.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'
  });

Accounts

An Account represents a Dwolla account that was either established on dwolla.com, or created inline with the capture of the user account’s permissions via Dwolla’s OAuth flow. A user account grants authorization to an application via OAuth, which gives the application permission to interact with the API on their behalf.

Verified and unverified Accounts

With a transfer of money, at least one party must complete the identity verification process through creation of a Traditional CIP Verified Dwolla account, 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 Dwolla user Account is sending funds to or receiving funds from your Account, the Account can remain unverified because your account is already verified. However, if you need to transfer funds between your users, at least one of them will need to have a Traditional CIP Verified Dwolla account.

For more information on Traditional Dwolla accounts, both Tradtional CIP Verified and Dwolla Direct, reference the account types resource article.

Migrating Dwolla user Accounts to White Label Customers

Dwolla offers a seamless process for migrating existing user Accounts managed via OAuth on your platform to White Label Customers. The user Account will maintain existing functionality on dwolla.com and will act as a separate White Label Customer upon completion of the migration. To learn more about upgrading to White Label, 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 can create and manage white label Customers.
send Follow the link to create a transfer to this Account.
{
  "_links": {
    "self": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "receive": {
      "href": "https://api-uat.dwolla.com/transfers"
    },
    "funding-sources": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
    },
    "transfers": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
    },
    "customers": {
      "href": "https://api-uat.dwolla.com/customers"
    },
    "send": {
      "href": "https://api-uat.dwolla.com/transfers"
    }
  },
  "id": "ca32853c-48fa-40be-ae75-77b37504581b",
  "name": "Jane Doe"
}

Get an Account by id

This section shows you how to retrieve account information belonging to the authorized user. The developer can pass either an id or the entire location resource to make this request.

  1. This endpoint requires an OAuth account access token but does not require a particular scope.

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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

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

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
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-uat.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-uat.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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

accountToken
  .get(accountUrl)
  .then(function(res) {
    res.body.name; // => 'Jane Doe'
  });

Create an Account funding source

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.

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

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.

Errors

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

Request and response

POST /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-uat.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3

List an Account’s funding sources

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.

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

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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
    }
  },
  "_embedded": {
    "funding-sources": [
      {
        "_links": {
          "self": {
            "href": "https://api-uat.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
          },
          "account": {
            "href": "https://api-uat.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-uat.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7"
          },
          "account": {
            "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          },
          "with-available-balance": {
            "href": "https://api-uat.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)
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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

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

List an Account’s transfers

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-uat.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers"
    },
    "first": {
      "href": "https://api-uat.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-uat.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers?limit=25&offset=0"
    }
  },
  "_embedded": {
    "transfers": [
      {
        "_links": {
          "self": {
            "href": "https://api-uat.dwolla.com/transfers/DC68A3DC-3C61-E511-80DA-0AA34A9B2388"
          },
          "source": {
            "href": "https://api-uat.dwolla.com/accounts/CA32853C-48FA-40BE-AE75-77B37504581B"
          },
          "destination": {
            "href": "https://api-uat.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-uat.dwolla.com/transfers/D36FD9AA-6E5C-E511-80DA-0AA34A9B2388"
          },
          "source": {
            "href": "https://api-uat.dwolla.com/funding-sources/2BFF2631-4006-45D6-BBBD-A7BE4853E870"
          },
          "destination": {
            "href": "https://api-uat.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-uat.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-uat.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-uat.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

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

List an Account’s mass payments

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.

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

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-uat.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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments"
    },
    "first": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
    }
  },
  "_embedded": {
    "mass-payments": [
      {
        "_links": {
          "self": {
            "href": "https://api-uat.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc"
          },
          "source": {
            "href": "https://api-uat.dwolla.com/funding-sources/84c77e52-d1df-4a33-a444-51911a9623e9"
          },
          "items": {
            "href": "https://api-uat.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-uat.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-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

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

accountToken
  .get(`${accountUrl}/mass-payments`)
  .then(function(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 OAuth access token with the ManageCustomers OAuth scope is required.

  1. This section outlines functionality for Dwolla White Label, a premium product that only approved partners may access in production. To learn more about entering into a White Label 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 white label 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 White Label Customers

Dwolla offers a seamless process for migrating existing user Accounts managed via OAuth on your platform to White Label Customers. The user Account will maintain existing functionality on dwolla.com and will act as a separate White Label Customer upon completion of the migration. To learn more about upgrading to White Label, 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 Customer has a status of document, POST to this link to upload a new photo document to verify the Customer’s identity. 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 is unverified or suspended.
If type is personal or business: status is 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 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 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 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.dwolla.com/customers/730CA23F-06C5-45CC-AA6B-8EC2D6EE109F"
    },
    "receive": {
      "href": "https://api.dwolla.com/transfers"
    },
    "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"
    },
    "send": {
      "href": "https://api.dwolla.com/transfers"
    }
  },
  "id": "730CA23F-06C5-45CC-AA6B-8EC2D6EE109F",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "janedoe@nomail.com",
  "type": "personal",
  "status": "verified",
  "created": "2015-10-06T01:18:26.923Z"
}

Create a Customer

This section details how to create a new Customer. To create an unverified Customer, 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.
address2 no string Second line of the street address of the Customer’s permanent residence. Must be 50 characters or less.
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 yes 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.
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 /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.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 = account_token.post "customers", request_body
customer.headers[:location] # => "https://api-uat.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-uat.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-uat.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 = account_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-uat.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-uat.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
var requestBody = {
  firstName: 'Jane',
  lastName: 'Merchant',
  email: 'jmerchant@nomail.net',
  ipAddress: '99.99.99.99'
};

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

Verified Customer

POST /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",
  "phone": "5155555555"
}

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',
  'phone' => '5155555555'
]);

$customer; # => "https://api-uat.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',
  :phone => '5155555555'
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = account_token.post "customers", request_body
customer.headers[:location] # => "https://api-uat.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-uat.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',
  'phone': '5155555555'
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = account_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-uat.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-uat.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',
  phone: '5155555555'
};

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

Receive-only customer

POST /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 = account_token.post "customers", request_body
customer.headers[:location] # => "https://api-uat.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-uat.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-uat.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 = account_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-uat.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-uat.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'
};

accountToken
  .post('customers', requestBody)
  .then(function(res) {
    res.headers.get('location'); // => 'https://api-uat.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.

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

HTTP request

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

Request and response:

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

{
  "_links": {},
  "_embedded": {
    "business-classifications": [
      {
        "_links": {
          "self": {
            "href": "https://api-uat.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
}

Get business classification by id

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.

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

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-uat.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-uat.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, and update a verified Customer’s information to retry verification.

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

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
address2 no string Second line of the street address of the customer’s permanent residence
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
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. See this table for required information.

Suspend a Customer

An unverified and verified Customer can be suspended by supplying the status of suspended. You’ll need to contact Dwolla to unsuspend a Customer.

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

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 /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.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.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 = account_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.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 = account_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.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"
};

accountToken
  .post(customerUrl, requestBody)
  .then(function(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
address2 no string Second line of the street address of the Customer’s permanent residence
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
dateOfBirth yes string Customer’s date of birth in YYYY-MM-DD format
ssn yes string Customer’s full Social Security Number
phone yes 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 Customers

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

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

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 /customers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "first": {
      "href": "https://api.dwolla.com/customers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api.dwolla.com/customers?limit=25&offset=0"
    },
    "self": {
      "href": "https://api.dwolla.com/customers?limit=25&offset=0"
    }
  },
  "_embedded": {
    "customers": [
      {
        "_links": {
          "self": {
            "href": "https://api.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 = account_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 = account_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'
accountToken
  .get('customers', { limit: 10 })
  .then(function(res) {
    res.body._embedded.customers[0].firstName; // => 'Jane'
  });

Get a Customer by id

This section shows you how to retrieve a Customer belonging to the authorized user. 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.

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

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-uat.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api.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-uat.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = account_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-uat.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8';

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

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer = account_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-uat.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8';

accountToken
  .get(customerUrl)
  .then(function(res) {
    res.body.firstName; // => 'Jane'
  });

Create 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 White Label product and requires additional approval before getting started. Please contact Sales for more information on enabling.

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

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-uat.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-uat.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 = account_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 = account_token.post('on-demand-authorizations')
on_demand_authorization.body['buttonText'] # => 'Agree & Continue'
accountToken
  .post('on-demand-authorizations')
  .then(function(res) {
    res.body.buttonText; // => "Agree & Continue"
  });

Create a Customer funding source

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 white label 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 Customer funding source

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

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

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.

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 /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
{
  "_links": {
    "on-demand-authorization": {
      "href": "https://api-uat.dwolla.com/on-demand-authorizations/30e7c028-0bdf-e511-80de-0aa34a9b2388"
    }
  },
  "routingNumber": "222222226",
  "accountNumber": "123456789",
  "type": "checking",
  "name": "Jane Doe’s Checking"
}

HTTP/1.1 201 Created
Location: https://api.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-uat.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C");
$fundingSource; # => "https://api-uat.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
?>
customer_url = 'https://api-uat.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 = account_token.post "#{customer_url}/funding-sources", request_body
funding_source.headers[:location] # => "https://api-uat.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-uat.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
customer_url = 'https://api-uat.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 = account_token.post('%s/funding-sources' % customer_url, request_body)
customer.headers['location'] # => 'https://api-uat.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-uat.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31'
var customerUrl = 'https://api-uat.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C';
var requestBody = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'type': 'checking',
  'name': 'Jane Doe’s Checking'
};

accountToken
  .post(`${customerUrl}/funding-sources`, requestBody)
  .then(function(res) {
    res.headers.get('location'); // => 'https://api-uat.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">
  dwolla.configure('sandbox');
  dwolla.iav.start('container', token.value, 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.

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

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 /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-uat.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/iav-token"
    }
  },
  "token": "4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY"
}
customer_url = 'https://api-uat.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer = account_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-uat.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6';

accountToken
  .post(`${customerUrl}/iav-token`)
  .then(function(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-uat.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6");
$fsToken->token; # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
?>

Initiate IAV flow

Initiate instant account verification for a Customer.

  1. An IAV token is required to render the IAV flow.

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 (UAT)
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.config.dwollaUrl = 'https://uat.dwolla.com';
  dwolla.iav.start('iavContainer', iavToken, 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 a Customer’s funding sources

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.

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

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.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.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources"
    },
    "customer": {
      "href": "https://api.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
    }
  },
  "_embedded": {
    "funding-sources": [
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
          },
          "customer": {
            "href": "https://api.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
          },
          "with-available-balance": {
            "href": "https://api.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.dwolla.com/funding-sources/98c209d3-02d6-4bee-bc0f-61e18acf0e33"
          },
          "customer": {
            "href": "https://api.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.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
funding_sources = account_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.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.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_sources = account_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.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';

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

List a Customer’s transfers

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.

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

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.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.dwolla.com/customers/01b47cb2-52ac-42a7-926c-6f1f50b1f271/transfers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api.dwolla.com/customers/01b47cb2-52ac-42a7-926c-6f1f50b1f271/transfers?limit=25&offset=0"
    },
    "self": {
      "href": "http://api.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271/transfers"
    }
  },
  "_embedded": {
    "transfers": [
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388"
          },
          "source": {
            "href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          },
          "destination": {
            "href": "https://api.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.dwolla.com/transfers/9DC99076-3D69-E511-80DB-0AA34A9B2388"
          },
          "source": {
            "href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          },
          "destination": {
            "href": "https://api.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.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
transfers = account_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.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.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
transfers = account_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.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271';

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

List a Customer’s mass payments

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.

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

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-uat.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-uat.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments"
    },
    "first": {
      "href": "https://api-uat.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-uat.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments?limit=25&offset=0"
    }
  },
  "_embedded": {
    "mass-payments": [
      {
        "_links": {
          "self": {
            "href": "https://api-uat.dwolla.com/mass-payments/89ca72d2-63bf-4a8f-92ef-a5d00140aefa"
          },
          "source": {
            "href": "https://api-uat.dwolla.com/funding-sources/e1c972d4-d8d9-4c30-861a-9081dcbaf4ab"
          },
          "items": {
            "href": "https://api-uat.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-uat.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
mass_payments = account_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-uat.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
mass_payments = account_token.get('%s/mass-payments' % customer_url)
mass_payments.body['_embedded']['mass-payments'][0]['status'] # => 'complete'
var customerUrl = 'https://api-uat.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b';

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

Documents

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 only exists for retrieving data with regards to a Document resource. To create a document, 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.

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

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.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE/documents'

...

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

file = Faraday::UploadIO.new('mclovin.jpg', 'image/jpeg')
document = account_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.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
document = account_token.post('%s/documents' % customer_url, file = open('mclovin.jpg', 'rb'), documentType = 'license')
document.headers['location'] # => 'https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16'
/**
 * No example for this language yet.
 **/
var customerUrl = 'https://api.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');

accountToken
  .post(`${customerUrl}/documents`, requestBody)
  .then(function(res) {
    res.headers.get('location'); // => "https://api.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.

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

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.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.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents"
    }
  },
  "_embedded": {
    "documents": [
      {
        "_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"
      },
      {
        "_links": {
          "self": {
            "href": "https://api.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.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.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';

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

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

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

token
  .get(`${customerUrl}/documents`)
  .then(function(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.

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

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.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_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"
}
document_url = 'https://api.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
document = account_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.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

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

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
documents = account_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.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';

accountToken
  .get(document_url)
  .then(function(res) {
    res.body.type; // => "passport"
  });

Funding sources

Add and retrieve ACH bank account information via funding sources, which are available to the Customers and Accounts resources. Customers can have a maximum of 6 funding sources.

Funding source resource

Parameter Description
id The funding source unique identifier
status Is the funding source verified?
type Type of funding source
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.
{
    "routingNumber": "222222226",
    "accountNumber": "123456789",
    "type": "checking",
    "name": "My Bank"
}

Create a funding source

Create a new funding source for an Account.

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

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.

Errors

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

Request and response

POST /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-uat.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3

Get a funding source by id

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

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

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.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.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c"
    },
    "customer": {
      "href": "https://api.dwolla.com/customers/36e9dcb2-889b-4873-8e52-0c9404ea002a"
    },
    "initiate-micro-deposits": {
      "href": "https://api.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.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
funding_source = account_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.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.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
funding_source = account_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.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

accountToken
  .get(fundingSourceUrl)
  .then(function(res) {
    res.body.name; // => "Test checking account"
  });

Update a funding source

This section covers how to update a bank funding source name.

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

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 yes string Arbitrary nickname for the funding source. Must be 50 characters or less.

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.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.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 = account_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.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 = account_token.post('funding-sources', request_body)
funding_source.body['name'] # => 'Test Checking - 1234'
var fundingSourceUrl = 'https://api.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
  name: "Test Checking - 1234"
};

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

Initiate or verify micro-deposits

This section covers how to initiate and 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.

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

HTTP request

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

Request parameters

Parameter Required Type Description
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
201 Created Micro deposits initiated
202 TryAgainLater “Invalid wait time.”
400 NotFound Funding source not found.
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 (Initiate)

POST /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
Cache-Control: no-cache

HTTP/1.1 201 Created
Location: https://api.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
funding_source_url = 'https://api-uat.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
account_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-uat.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';

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

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

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

$fsApi->micro_deposits($fundingSourceUrl);
?>

Request and response (Verify)

POST /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-uat.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)
account_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-uat.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
var requestBody = {
  amount1: {
    value: '0.03',
    currency: 'USD'
  },
  amount2: {
    value: '0.09',
    currency: 'USD'
  }
};

accountToken.post(`${fundingSourceUrl}/micro-deposits`, requestBody);
funding_source_url = 'https://api-uat.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)
account_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-uat.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';

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

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

Retrieve micro-deposits status

This section shows how to retrieve the status of micro-deposits and check if pending verification for completed micro-deposits exists.

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

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.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8/micro-deposits
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8/micro-deposits",
      "type": "micro-deposits"
    }
  },
  "status": "pending"
  "created": "2016-07-25T19:46:35.000Z"
}

Remove a funding source

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

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

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 /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.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.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

request_body = {
  :removed => true
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
account_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.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';

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

$fsApi->softDelete(['removed' => true ], $fundingSourceUrl);
?>
funding_source_url = 'https://api.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'

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

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
fs_api = dwollaswagger.FundingsourcesApi(client)
fs_api.soft_delete(funding_source_url, body = {
  'removed': true
})
var fundingSourceUrl = 'https://api.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
  removed: true
};

accountToken.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
{
  "_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 transfer

This section covers how to initiate a transfer for either an Account or 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.

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
Account https://api.dwolla.com/accounts/{id} Destination Account of a transfer.
Customer https://api.dwolla.com/customers/{id} Destination Customer 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)
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.

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-uat.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 (transfer from Account to Customer)

POST /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": {
        "destination": {
            "href": "https://api.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8"
        },
        "source": {
            "href": "https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "10.00"
    },
    "metadata": {
        "foo": "bar",
        "baz": "boo"
    },
   "fees":[  
      {  
         "_links":{  
            "charge-to":{  
               "href":"http://api-uat.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8"
            }
         },
         "amount":{  
            "value":"1.00",
            "currency":"USD"
         }
      }
   ]
}

...

HTTP/1.1 201 Created
Location: https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388
request_body = {
  :_links => {
    :destination => {
      :href => "https://api.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8"
    },
    :source => {
      :href => "https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    }
  },
  :amount => {
    :currency => "USD",
    :value => "1.00"
  },
  :metadata => {
    :foo => "bar",
    :baz => "boo"
  }
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
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' => [
    'destination' => [
      'href' => 'https://api.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
    ],
    'source' => [
      'href' => 'https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4',
    ],
  ],
  'amount' => [
    'currency' => 'USD',
    'value' => '1.00'
  ],
  'metadata' => [
    'foo' => 'bar',
    'baz' => 'boo',
  ]
]);
$transfer; # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
?>
request_body = {
  '_links': {
    'destination': {
      'href': 'https://api.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
    },
    'source': {
      'href': 'https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  'amount': {
    'currency': 'USD',
    'value': '1.00'
  },
  'metadata': {
    'foo': 'bar',
    'baz': 'boo'
  }
}

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'
var requestBody = {
  _links: {
    destination: {
      href: 'https://api.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
    },
    source: {
      href: 'https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  amount: {
    currency: 'USD',
    value: '1.00'
  },
  metadata: {
    foo: 'bar',
    baz: 'boo'
  }
};

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

Get a transfer by id

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.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388"
    },
    "source": {
      "href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "destination": {
      "href": "https://api.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)
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.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388';

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

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
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.dwolla.com/transfers/4C8AD8B8-3D69-E511-80DB-0AA34A9B2388';

accountToken
  .get(transferUrl)
  .then(function(res) {
    res.body.status; // => 'pending'
  });

Get a transfer’s fees

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-uat.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-uat.dwolla.com/transfers/416a2857-c887-4cca-bd02-8c3f75c4bb0e"
        },
        "source": {
          "href": "https://api-uat.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd"
        },
        "destination": {
          "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
        },
        "created-from-transfer": {
          "href": "https://api-uat.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-uat.dwolla.com/transfers/e58ae1f1-7007-47d3-a308-7e9aa6266d53"
        },
        "source": {
          "href": "https://api-uat.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd"
        },
        "destination": {
          "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
        },
        "created-from-transfer": {
          "href": "https://api-uat.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-uat.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
fees = account_token.get "#{transfer_url}/fees"
fees.total # => 2
/**
 *  No example for this language yet.
 **/
transfer_url = 'https://api-uat.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
fees = account_token.get('%s/fees' % transfer_url)
fees.body['total'] # => 2
var transferUrl = 'https://api-uat.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

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

Get transfer failure reason

When a bank transfer fails for an Account or Customer, Dwolla returns a failure link when getting the transfer by Id. This failure link is used to retrieve the 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-uat.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-uat.dwolla.com/transfers/E6D9A950-AC9E-E511-80DC-0AA34A9B2388/failure"
    }
  },
  "code": "R1",
  "description": "Insufficient Funds"
}
transfer_url = 'https://api-uat.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
failure = account_token.get "#{transfer_url}/failure"
failure.code # => "R1"
/**
 *  No example for this language yet.
 **/
transfer_url = 'https://api-uat.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
failure = account_token.get('%s/failure' % transfer_url)
failure.body['code'] # => 'R1'
var transferUrl = 'https://api-uat.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';

accountToken
  .get(`${transferUrl}/failure`)
  .then(function(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-uat.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-uat.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388"
    },
    "source": {
      "href": "https://api-uat.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "funding-transfer": {
      "href": "https://api-uat.dwolla.com/transfers/3c48c13a-0fc6-e511-80de-0aa34a9b2388"
    },
    "self": {
      "href": "https://api-uat.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388"
    },
    "destination": {
      "href": "https://api-uat.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 then be queued and 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 pending, processing, or complete
created ISO-8601 timestamp
metadata A metadata JSON object
{
  "_links": {},
  "_embedded": {},
  "id": "string",
  "status": "string",
  "created": "2016-03-11T15:52:58.289Z",
  "metadata": {}
}

Initiate a mass payment

This section covers how to initiate a mass payment from an 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.

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

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

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
Account https://api.dwolla.com/accounts/{id} Destination Account of a transfer.
Customer https://api.dwolla.com/customers/{id} Destination Customer 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)
Funding source https://api.dwolla.com/funding-sources/{id} Destination of a verified Customer’s own bank or balance funding source. OR An unverified Customer’s bank funding source.

Mass payment item

Parameter Description
_links Can return mass-payment, destination and transfer JSON objects that contain relational links to associated resources.
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/customers/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 (transfer from Account to Customer)

POST /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-uat.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "items": [
      {
        "_links": {
            "destination": {
                "href": "https://api-uat.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
            }
        },
        "amount": {
            "currency": "USD",
            "value": "1.00"
        },
        "metadata": {
            "payment1": "payment1"
        }
      },
            {
        "_links": {
            "destination": {
                "href": "https://api-uat.dwolla.com/customers/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.dwolla.com/mass-payments/d093bcd1-d0c1-41c2-bcb5-a5cc011be0b7
request_body = {
  _links: {
    source: {
      href: "https://api-uat.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    }
  },
  items: [
    {
      _links: {
        destination: {
          href: "https://api-uat.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
        }
      },
      amount: {
        currency: "USD",
        value: "1.00"
      },
      metadata: {
        payment1: "payment1"
      }
    },
    {
      _links: {
        destination: {
          href: "https://api-uat.dwolla.com/customers/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-uat.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-uat.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  items: [
    {
      _links: {
        destination: {
          href: 'https://api-uat.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db'
        }
      },
      amount: {
        currency: 'USD',
        value: '1.00'
      },
      metadata: {
        payment1: 'payment1'
      }
    },
    {
      _links: {
        destination: {
          href: 'https://api-uat.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd'
        }
      },
      amount: {
        currency: 'USD',
        value: '5.00'
      },
      metadata: {
        payment2: 'payment2'
      }
    }
  ],
  metadata: {
    batch1: 'batch1'
  }
}

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

Get a mass payment by id

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.

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

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-uat.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-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
    },
    "source": {
      "href": "https://api-uat.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    },
    "items": {
      "href": "https://api-uat.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-uat.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-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';

accountToken
  .get(massPaymentUrl)
  .then(function(res) {
    res.body.status; // => 'processing'
  });

List mass payment items

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.

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

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-uat.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-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items"
    },
    "first": {
      "href": "https://api-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items?limit=25&offset=0"
    }
  },
  "_embedded": {
    "items": [
      {
        "_links": {
          "self": {
            "href": "https://api-uat.dwolla.com/mass-payment-items/2f845bc9-41ed-e511-80df-0aa34a9b2388"
          },
          "mass-payment": {
            "href": "https://api-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
          },
          "destination": {
            "href": "https://api-uat.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
          },
          "transfer": {
            "href": "https://api-uat.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-uat.dwolla.com/mass-payment-items/30845bc9-41ed-e511-80df-0aa34a9b2388"
          },
          "mass-payment": {
            "href": "https://api-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
          },
          "destination": {
            "href": "https://api-uat.dwolla.com/customers/b442c936-1f87-465d-a4e2-a982164b26bd"
          },
          "transfer": {
            "href": "https://api-uat.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-uat.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-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'

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

Get a mass payment item by id

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.

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

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-uat.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-uat.dwolla.com/mass-payment-items/2f845bc9-41ed-e511-80df-0aa34a9b2388"
    },
    "mass-payment": {
      "href": "https://api-uat.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
    },
    "destination": {
      "href": "https://api-uat.dwolla.com/customers/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
    },
    "transfer": {
      "href": "https://api-uat.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-uat.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-uat.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-uat.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388';

accountToken
  .get(massPaymentItemUrl)
  .then(function(res) {
    res.body.status; // => 'success'
  });

Events

When the state of a resource changes, we create a new event resource to record the change. For instance, if a Customer’s status changes to verified, a customer_verified event will be created. 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, the Account associated with the event, and the Customer associated with the event (if any).
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 - (Accounts)

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_unverified A funding source was marked as unverified.
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.
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_unverified A Customer’s funding source was marked as unverified.
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.

List events

Retrieve a list of events for the authorized user.

  1. This endpoint requires an OAuth Application access token.

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.dwolla.com/events
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/events"
    },
    "first": {
      "href": "https://api.dwolla.com/events?limit=25&offset=0"
    },
    "last": {
      "href": "https://api.dwolla.com/events?limit=25&offset=150"
    },
    "next": {
      "href": "https://api.dwolla.com/events?limit=25&offset=25"
    }
  },
  "_embedded": {
    "events": [
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/events/78e57644-56e4-4da2-b743-059479f2e80f"
          },
          "resource": {
            "href": "https://api.dwolla.com/transfers/47CFDDB4-1E74-E511-80DB-0AA34A9B2388"
          },
          "account": {
            "href": "https://api.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.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"
      },
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/events/9f0167e0-dce6-4a1a-ad26-30015d6f1cc1"
          },
          "resource": {
            "href": "https://api.dwolla.com/transfers/08A166BC-1B74-E511-80DB-0AA34A9B2388"
          },
          "account": {
            "href": "https://api.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"
      },
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095"
          },
          "resource": {
            "href": "https://api.dwolla.com/transfers/09A166BC-1B74-E511-80DB-0AA34A9B2388"
          },
          "account": {
            "href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
          },
          "customer": {
            "href": "https://api.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"
      }
    ]
  },
  "total": 4
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
events = application_token.get "events"
events.total # => 4

# Using DwollaSwagger - https://github.com/Dwolla/dwolla-swagger-ruby
events = DwollaSwagger::EventsApi.events
events.total # => 4
<?php
$eventsApi = new DwollaSwagger\EventsApi($apiClient);

$events = $eventsApi->events();
$events->total; # => 4
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
events = application_token.get('events')
events.body['total'] # => 4

# Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-python
events_api = dwollaswagger.EventsApi(client)
events = events_api.events()
events.total # => 4
applicationToken
  .get('events')
  .then(function(res) {
    res.body.total; // => 4
  });

Get event by id

This section covers how to retrieve an event by id.

  1. This endpoint requires an OAuth Application access token.

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 /events/81f6e13c-557c-4449-9331-da5c65e61095
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095"
    },
    "resource": {
      "href": "https://api.dwolla.com/transfers/09A166BC-1B74-E511-80DB-0AA34A9B2388"
    },
    "account": {
      "href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "customer": {
      "href": "https://api.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.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
event = application_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.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.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
event = application_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.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095';

applicationToken
  .get(eventUrl)
  .then(function(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. If you are a white label partner, you will use these events to notify your customers via email as described in the white label terms of service. Refer to the events section for the list of events that trigger webhooks.

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/webhook-subscriptions/034a0ae2-fc7f-4922-8e4e-6fb9855ed43b"
    },
    "webhooks": {
      "href": "https://api.dwolla.com/webhook-subscriptions/034a0ae2-fc7f-4922-8e4e-6fb9855ed43b/webhooks"
    }
  },
  "id": "034a0ae2-fc7f-4922-8e4e-6fb9855ed43b",
  "url": "http://requestb.in/vbxb1bvb",
  "created": "2015-10-06T01:11:36.000Z"
}

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 a HTTP 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 webhook by 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 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

Attempt 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 Event id for this webhook

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-uat.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 = application_token.post "webhook-subscriptions", request_body
subscription.headers[:location] # => "https://api-uat.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-uat.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(function(res) {
    res.headers.get('location'); // => 'https://api-uat.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 = application_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-uat.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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"
?>

Delete a 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-uat.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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
application_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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
application_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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');
?>

List 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.dwolla.com/webhook-subscriptions
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/webhook-subscriptions"
    }
  },
  "_embedded": {
    "webhook-subscriptions": [
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/webhook-subscriptions/f4d21628-fde2-4d3a-b69a-0a7cb42adc4c"
          },
          "webhooks": {
            "href": "https://api.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 = application_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(function(res) {
    res.body.total; // => 1
  });
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
webhook_subscriptions = application_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
?>

Get a subscription by id

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-uat.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-uat.dwolla.com/webhook-subscriptions/077dfffb-4852-412f-96b6-0fe668066589"
    },
    "webhooks": {
      "href": "https://api-uat.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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
webhook_subscription = application_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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
webhook_subscription = application_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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');

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

Get a subscription’s webhooks

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.

Request and response

GET /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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
hooks = application_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-uat.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';

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

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

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8"
    },
    "subscription": {
      "href": "https://api.dwolla.com/webhook-subscriptions/a0943041-7a5c-4e8f-92de-b55711ef3a83"
    },
    "retry": {
      "href": "https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
    },
    "event": {
      "href": "https://api.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.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.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\"},\"account\":{\"href\":\"https://api.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/\"}"
      }
    }
  ]
}

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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8"
    },
    "subscription": {
      "href": "https://api.dwolla.com/webhook-subscriptions/a0943041-7a5c-4e8f-92de-b55711ef3a83"
    },
    "retry": {
      "href": "https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
    },
    "event": {
      "href": "https://api.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.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.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\"},\"account\":{\"href\":\"https://api.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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
webhook = application_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.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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
webhook = application_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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

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

Retry a webhook by id

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 /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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries/5aa27a0f-cf99-418d-a3ee-67c0ff99a494
webhook_url = 'https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

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

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

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

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
application_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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

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

Get webhook retries by id

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 /webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
    }
  },
  "_embedded": {
    "retries": [
      {
        "_links": {
          "self": {
            "href": "https://api.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries/5aa27a0f-cf99-418d-a3ee-67c0ff99a494"
          },
          "webhook": {
            "href": "https://api.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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
retries = application_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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

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

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

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
retries = application_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.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';

applicationToken
  .get(`${webhookUrl}/retries`)
  .then(function(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.