Welcome to the Dwolla API documentation. This API will give you the ability to connect your software to banking infrastructure to move money, store funds, validate customer identities, and verify bank accounts.
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
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}
Production: https://api.dwolla.com
Sandbox: https://api-sandbox.dwolla.com
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. It is recommended to use a random value for the idempotency key, like a UUID (i.e. - Idempotency-Key: d2adcbab-4e4e-430b-9181-ac9346be723a).
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, rather than creating new or potentially duplicate resources, you will receive a 201 Created, with the original response of the created resource. If the Dwolla server is still processing the original POST request, you will receive a 409 Conflict error response on the subsequent request. Idempotency keys are intended to prevent conflicts over a short period of time, therefore keys will expire after 24 hours.
To prevent resources from being created more than once, we highly recommend making all requests idempotent.
POST https://api-sandbox.dwolla.com/transfers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77
{
"_links": {
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
},
"source": {
"href": "http://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
}
},
"amount": {
"currency": "USD",
"value": "1337.00"
}
}
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.
{
"code": "InvalidAccessToken",
"message": "Invalid access token."
}
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 your client credentials. |
| 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. |
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:
{
"code": "ValidationError",
"message": "Validation error(s) present. See embedded errors list for more details.",
"_embedded": {
"errors": [
{
"code": "Required",
"message": "FirstName required.",
"path": "/firstName",
"_links": {}
}
]
}
}
Relationships and available actions for a resource are represented with links. All resources have a _links attribute. At a minimum, all resources will have a self link which indicates the URL of the resource itself.
Some links, such as funding-sources, give you a URL which you can follow to access related resources. For example, the customer resource has a funding-sources link which, when followed, will list the customer’s available funding sources.
Responses which contain a collection of resources have pagination links, first, next, last, and prev.
{
"_links": {
"self": {
"href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1"
},
"funding-sources": {
"href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1/funding-sources"
},
"transfers": {
"href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1/transfers"
},
"retry-verification": {
"href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1"
}
},
"id": "132681FA-1B4D-4181-8FF2-619CA46235B1",
"firstName": "Jane",
"lastName": "doe",
"email": "jdoe@nomail.com",
"type": "personal",
"status": "retry",
"created": "2015-09-29T19:47:28.920Z"
}
The following section will outline development tools you can take advantage of to assist in your integration with the Dwolla API. The available tools can help to improve your testing and development workflow, as well as aid in solving a difficult problem (e.g. UI generation) when integrating Dwolla into your application.
Dwolla HAL-Forms is an extension of the HAL spec and was created to describe how Dwolla represents forms in the API. The extension starts with the media type. The media type should be used as a profile link as part of the Accept header of the request in conjunction with the Dwolla HAL style media type. By including these two media-type identifiers in the Accept header, the API knows that you’re looking for a form for the given resource.
application/vnd.dwolla.v1.hal+json; profile="https://github.com/dwolla/hal-forms"
The primary benefit is the ability to dynamically generate your UI based on the state of a particular resource. Your application can easily transition state without knowing Dwolla’s business rules and what information needs to included in the actual request to transition state. When an "edit-form" link relation is returned on the resource, then your application can follow the link by making a GET request to that resource, including the header shown above. The response will include a simple JSON response body that contains information on the HTTP method, message content-type, and the request parameters used when sending the request to the Dwolla API. Note: Currently, forms are only returned for creating & editing customers, but we’re looking forward to expanding them across our existing and future endpoints.
Reference the spec for more information on the properties that can be returned in the Dwolla HAL-FORMS response. Or read a blog post from one of our developers on building out this functionality.
The Dwolla API has officially maintained software packages to make it easier for developers to get started with making requests. This section is here to provide basic instructions on how to install these packages and get up and running with them. We recommend you use a POSIX-standardized shell on your development machine, and assume that you are already familiar and set-up with any tools required for your specific technical ecosystem.
Officially maintained SDKs are available for Ruby, Node.js, Python, and C#.
The PHP SDKs is autogenerated by swagger-codegen and are versioned in accordance with our API schema. Each endpoint grouping is assigned a class and then an operation which you can use to make a request. You can choose which environment to target (e.g production vs sandbox) by providing the SDK a different API host value. These libraries are not actively maintained, therefore we encourage community contribution.
| Production | Sandbox |
|---|---|
| https://api.dwolla.com | https://api-sandbox.dwolla.com |
dwolla_v2 is available on RubyGems with source code available on our GitHub page. More information is available on the project’s README.
gem install dwolla_v2
Let’s list some Customer objects:
require 'dwolla_v2'
# Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
app_key = "..."
app_secret = "..."
$dwolla = DwollaV2::Client.new(key: app_key, secret: app_secret) do |config|
config.environment = :sandbox # optional - defaults to production
end
# create an application token
app_token = $dwolla.auths.client
customers = app_token.get "customers", limit: 10
dwollav2 is available on PyPi with
source code available on our GitHub page. More
information is available on the project’s README.
pip install dwollav2
Let’s list some Customer objects:
import dwollav2
# Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
app_key = '...'
app_secret = '...'
client = dwollav2.Client(key = app_key,
secret = app_secret,
environment = 'sandbox') # optional - defaults to production
app_token = client.Auth.client()
customers = app_token.get('customers', {'limit': 10})
dwolla-swagger-php is available on Packagist with source code available on our GitHub page. More information is available on the project’s README.
composer require dwolla/dwollaswagger
composer install
Let’s list some Customer objects:
<?php
require('../path/to/vendor/autoload.php');
DwollaSwagger\Configuration::$access_token = 'a token';
$apiClient = new DwollaSwagger\ApiClient("https://api-sandbox.dwolla.com/");
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$myCusties = $customersApi->_list(10);
?>
Dwolla.Client is available on Nuget with
source code available on our GitHub page. More
information is available on the project’s README.
Install-Package Dwolla.Client
Let’s list some Customer objects:
var client = DwollaClient.Create(isSandbox: true);
var tokenRes = await client.PostAuthAsync<AppTokenRequest, TokenResponse>(
new Uri($"{client.AuthBaseAddress}/token"),
new AppTokenRequest {Key = "...", Secret = "..."});
var headers = new Headers {{"Authorization", $"Bearer {tokenRes.Content.Token}"}};
var rootRes = (await client.GetAsync<RootResponse>(new Uri(client.ApiBaseAddress), headers)).Content;
var customers = await client.GetAsync<GetCustomersResponse>(rootRes.Links["customers"].Href, headers);
dwolla-swagger-java is not actively maintained by Dwolla, however source code is available on our GitHub page and community contribution is encouraged. More information is available on the project’s README.
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
Let’s list some Customer objects:
import io.swagger.client.ApiClient;
import io.swagger.client.api.*;
import io.swagger.client.model.*;
ApiClient a = new ApiClient();
a.setBasePath("https://api-sandbox.dwolla.com");
a.setAccessToken("a token");
CustomersApi c = new CustomersApi(a);
CustomerListResponse custies = c.list(10);
dwolla-v2 is available on NPM with source code available on our GitHub page. More information is available on the project’s README.
npm install dwolla-v2
Let’s fetch a page of customers:
const dwolla = require('dwolla-v2');
// Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
const appKey = '...';
const appSecret = '...';
const client = new dwolla.Client({
key: appKey,
secret: appSecret,
environment: 'sandbox' // optional - defaults to production
});
// create a token
client.auth.client()
.then(appToken => appToken.get('customers', { limit: 10 }))
.then(res => console.log(res.body));
Dwolla utilizes the OAuth 2 protocol to facilitate authorization. OAuth is an authorization framework that enables a third-party application to obtain access to protected resources (Transfers, Funding Sources, Customers etc.) in the Dwolla API. Access to the Dwolla API can be granted to an application either on behalf of a user or on behalf of the application itself. This section covers application auth which is meant for server-to-server applications using the Dwolla API.
Before you can get started with making OAuth requests, you’ll need to first register an application with Dwolla by logging in and navigating to the applications page. Once an application is registered you will obtain your client_id and client_secret (aka App Key and Secret), which will be used to identify your application when calling the Dwolla API. The Sandbox environment provides you with a created application once you have signed up for an account. Learn more in our getting started guide. Remember: Your client_secret should be kept a secret! Be sure to store your client credentials securely.
Access tokens are short lived: 1 hour. To refresh authorization on an application access token, your application will simply exchange its client credentials for a new app access token. Any access tokens that have been previously initialized will not be invalidated with the creation of a new one; they will simply expire within an hour of the time of their creation.
The client credentials flow is the simplest OAuth 2 grant, with a server-to-server exchange of your application’s client_id, client_secret for an OAuth application access token. In order to execute this flow, your application will send a POST requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string client_id:client_secret.
Authorization: Basic Base64(client_id:client_secret)
Production: POST https://api.dwolla.com/token
Sandbox: POST https://api-sandbox.dwolla.com/token
Including the Content-Type: application/x-www-form-urlencoded header, the request is sent to the token endpoint with grant_type=client_credentials in the body of the request:
| Parameter | Required | Type | Description |
|---|---|---|---|
| client_id | yes | string | Application key. Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications-legacy (Sandbox) for your application key. |
| client_secret | yes | string | Application secret. Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications-legacy (Sandbox) for your application secret. |
| grant_type | yes | string | This must be set to client_credentials. |
| Parameter | Description |
|---|---|
| access_token | A new access token that is used to authenticate against resources that belong to the app itself. |
| expires_in | The lifetime of the access token, in seconds. Default is 3600. |
| token_type | Always bearer. |
POST https://api-sandbox.dwolla.com/token
Authorization: Basic YkVEMGJMaEFhb0pDamplbmFPVjNwMDZSeE9Eb2pyOUNFUzN1dldXcXUyeE9RYk9GeUE6WEZ0bmJIbXR3dXEwNVI1Yk91WmVOWHlqcW9RelNSc21zUU5qelFOZUFZUlRIbmhHRGw=
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
# This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
app_token = client.Auth.client()
// Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-node
// This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
client.auth.client()
.then(function(appToken) {
return appToken.get('webhook-subscriptions');
})
.then(function(res) {
console.log(JSON.stringify(res.body));
});
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
# This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
app_token = $dwolla.auths.client
# => #<DwollaV2::Token client=#<DwollaV2::Client id="..." secret="..." environment=:sandbox> access_token="..." expires_in=3600 scope="...">
/**
* No support for this language yet. We recommend using an external REST client for making OAuth requests.
**/
{
"access_token": "SF8Vxx6H644lekdVKAAHFnqRCFy8WGqltzitpii6w2MVaZp1Nw",
"token_type": "bearer",
"expires_in": 3600
}
The “root” serves as an entry point to the API, providing your application with the ability to fetch and discover resources available based on the OAuth access_token provided in the request. If an application access token is provided in the request, the API will return links to resources that belong to the Dwolla application (i.e. “events” and “webhook-subscriptions”).
GET https://api.dwolla.com/
GET https://api-sandbox.dwolla.com/
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
},
"customers": {
"href": "https://api-sandbox.dwolla.com/customers"
}
}
}
root = app_token.get "/"
root._links.account.href # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
<?php
$rootApi = new DwollaSwagger\RootApi($apiClient);
$root = $rootApi->root();
$accountUrl = $root->_links["account"]->href; # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
root = app_token.get('/')
root.body['_links']['account']['href'] # => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'
appToken
.get('/')
.then(res => res.body._links.account.href); // => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'
An Account represents your Dwolla Master Account that was established on dwolla.com.
| Link | Description |
|---|---|
| self | URL of the Account resource |
| receive | Follow the link to create a transfer to this Account. |
| funding-sources | GET this link to list the Account’s funding sources. |
| transfers | GET this link to list the Account’s transfers. |
| customers | (optional) If this link exists, this account is authorized to create and manage Dwolla API Customers. |
| send | Follow the link to create a transfer to this Account. |
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
},
"receive": {
"href": "https://api-sandbox.dwolla.com/transfers"
},
"funding-sources": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
},
"transfers": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
},
"customers": {
"href": "https://api-sandbox.dwolla.com/customers"
},
"send": {
"href": "https://api-sandbox.dwolla.com/transfers"
}
},
"id": "ca32853c-48fa-40be-ae75-77b37504581b",
"name": "Jane Doe"
}
This section shows you how to retrieve basic account information belonging to the authorized Dwolla Master Account.
To retrieve your Account ID, you will need to call the root of the API.
GET https://api.dwolla.com/accounts/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Account unique identifier. |
| HTTP Status | Message |
|---|---|
| 403 | Not authorized to retrieve an Account by id. |
| 404 | Account not found. |
GET https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
},
"receive": {
"href": "https://api-sandbox.dwolla.com/transfers"
},
"funding-sources": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
},
"transfers": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
},
"customers": {
"href": "https://api-sandbox.dwolla.com/customers"
},
"send": {
"href": "https://api-sandbox.dwolla.com/transfers"
}
},
"id": "ca32853c-48fa-40be-ae75-77b37504581b",
"name": "Jane Doe"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
account = app_token.get account_url
account.name # => "Jane Doe"
<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';
$accountsApi = new DwollaSwagger\AccountsApi($apiClient);
$account = $accountsApi->id($accountUrl);
print($account->name); # => "Jane Doe"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
account = app_token.get(account_url)
account.body['name']
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';
appToken
.get(accountUrl)
.then(res => res.body.name); // => 'Jane Doe'
This section details how to add a bank account to a Dwolla Master Account. The bank account will have a status of unverified upon creation. Before a Dwolla Master 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.
POST https://api.dwolla.com/funding-sources
| Parameter | Required | Type | Description |
|---|---|---|---|
| accountNumber | yes | string | The bank account number. |
| routingNumber | yes | string | The bank account’s routing number. |
| bankAccountType | yes | string | Type of bank account: checking or savings. |
| name | yes | string | Arbitrary nickname for the funding source. |
| channels | no | array | An array containing a list of processing channels. ACH is the default processing channel for bank transfers. Acceptable value for channels is: “wire”. e.g. “channels”: [ “wire” ]. A funding source (Bank Account) added using the wire channel only supports a funds transfer going to the bank account from a balance. Note: channels is a premium feature that must be enabled on your account and is only available to select Dwolla customers. |
| HTTP Status | Message |
|---|---|
| 400 | Duplicate funding source or validation error. |
| 403 | Not authorized to create funding source. |
POST https://api-sandbox.dwolla.com/funding-sources
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"routingNumber": "222222226",
"accountNumber": "123456789",
"bankAccountType": "checking",
"name": "My Bank"
}
...
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3
<?php
$fundingApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSource = $fundingApi->createFundingSource([
"routingNumber" => "222222226",
"accountNumber" => "123456789",
"bankAccountType" => "checking",
"name" => "My Bank"
]);
$fundingSource; # => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
routingNumber: '222222226',
accountNumber: '123456789',
bankAccountType: 'checking',
name: 'My Bank'
}
funding_source = app_token.post "funding-sources", request_body
funding_source.response_headers[:location] # => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'routingNumber': '222222226',
'accountNumber': '123456789',
'bankAccountType': 'checking',
'name': 'My Bank'
}
funding_source = app_token.post('funding-sources', request_body)
funding_source.headers['location'] # => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'
var requestBody = {
'routingNumber': '222222226',
'accountNumber': '123456789',
'bankAccountType': 'checking',
'name': 'My Bank'
};
appToken
.post(`funding-sources`, requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'
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.
GET https://api.dwolla.com/accounts/{id}/funding-sources
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Account’s unique identifier. |
| removed | no | boolean | Filter removed funding sources. Defaults to true. Set to false to filter out removed funding sources from list (i.e. - /accounts/{id}/funding-sources?removed=false). |
| HTTP Status | Message |
|---|---|
| 403 | Not authorized to list funding sources. |
| 404 | Account not found. |
GET https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources",
"resource-type": "funding-source"
}
},
"_embedded": {
"funding-sources": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
}
},
"id": "04173e17-6398-4d36-a167-9d98c4b1f1c3",
"status": "verified",
"type": "bank",
"bankAccountType": "checking",
"name": "My Account - Checking",
"created": "2017-09-25T20:03:41.000Z",
"removed": false,
"channels": [
"ach"
],
"bankName": "First Midwestern Bank"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
},
"with-available-balance": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
},
"balance": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7/balance",
}
},
"id": "b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
"status": "verified",
"type": "balance",
"name": "Balance",
"created": "2017-08-22T18:21:51.000Z",
"removed": false,
"channels": []
}
]
}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
funding_sources = app_token.get "#{account_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe's Checking"
<?php
$accountUrl = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSources = $fsApi->getAccountFundingSources($accountUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Jane Doe’s Checking"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
funding_sources = app_token.get('%s/funding-sources' % account_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Jane Doe’s Checking'
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';
appToken
.get(`${accountUrl}/funding-sources`)
.then(res => res.body._embedded['funding-sources'][0].name); // => 'ABC Bank Checking'
This section covers how to retrieve an Account’s list of transfers. Transaction search is supported by passing in optional query string parameters such as: search which represents a term to search on, correlationId, startAmount, endAmount, startDate, endDate, and status.
GET https://api.dwolla.com/accounts/{id}/transfers
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Account unique identifier to get transfers for. |
| search | no | string | A string to search on fields: firstName, lastName, email, businessName, Customer Id, and Account Id. (/transfers?search=Doe) |
| startAmount | no | string | Only include transactions with an amount equal to or greater than startAmount. Can optionally be used with endAmount to specify an amount range. |
| endAmount | no | string | Only include transactions with an amount equal to or less than endAmount. Can optionally be used with startAmount to specify an amount range. |
| startDate | no | string | Only include transactions created after this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with endDate to specify a date range. |
| endDate | no | string | Only include transactions created before than this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with startDate to specify a date range. |
| status | no | string | Filter results on transaction status. Possible values: pending, processed, failed, reclaimed, or cancelled. |
| correlationId | no | string | A string value to search on if a correlationId was specified on a transfer or mass payment item. |
| limit | no | integer | Number of search results to return. Defaults to 25. |
| offset | no | integer | Number of search results to skip. Used for pagination. |
| HTTP Status | Message |
|---|---|
| 404 | Account not found. |
GET https://api.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"first": {
"href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers?&limit=25&offset=0",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"last": {
"href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers?&limit=25&offset=0",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
}
},
"_embedded": {
"transfers": [{
"_links": {
"cancel": {
"href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/12a0eaf9-9561-468d-bdeb-186b536aa2ed",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"funded-transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/84c77e52-d1df-4a33-a444-51911a9623e9",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
}
},
"id": "14c6bcce-46f7-e811-8112-e8dd3bececa8",
"status": "pending",
"amount": {
"value": "42.00",
"currency": "USD"
},
"created": "2018-12-03T22:00:22.980Z",
"clearing": {
"source": "standard"
},
"individualAchId": "IDOWBKVE"
}, {
"_links": {
"cancel": {
"href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"source": {
"href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
},
"source-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/12a0eaf9-9561-468d-bdeb-186b536aa2ed",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"funding-transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/customers/d295106b-ca20-41ad-9774-286e34fd3c2d",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"destination-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/500f8e0e-dfd5-431b-83e0-cd6632e63fcb",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
}
},
"id": "15c6bcce-46f7-e811-8112-e8dd3bececa8",
"status": "pending",
"amount": {
"value": "42.00",
"currency": "USD"
},
"created": "2018-12-03T22:00:22.970Z",
"clearing": {
"source": "standard"
}
}]
},
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966'
transfers = app_token.get "#{account_url}/transfers"
transfers._embedded['transfers'][0].status # => "processed"
<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966';
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transfers = $transfersApi->getAccountTransfers($accountUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "processed"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966'
transfers = app_token.get('%s/transfers' % account_url)
transfers.body['_embedded']['transfers'][0]['status'] # => "processed"
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966';
appToken
.get(`${accountUrl}/transfers`)
.then(res => res.body._embedded['transfers'][0].status); // => 'processed'
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.
GET https://api.dwolla.com/accounts/{id}/mass-payments
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Account unique identifier to get mass payments for. |
| limit | no | integer | How many results to return. Defaults to 25. |
| offset | no | integer | How many results to skip. |
| correlationId | no | string | A string value to search on if a correlationId was specified on a mass payment. |
| HTTP Status | Code | Description |
|---|---|---|
| 403 | NotAuthorized | Not authorized to list mass payments. |
| 404 | NotFound | Account not found. |
GET https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
....
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments"
},
"first": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
},
"last": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
}
},
"_embedded": {
"mass-payments": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/84c77e52-d1df-4a33-a444-51911a9623e9"
},
"items": {
"href": "https://api-sandbox.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc/items"
}
},
"id": "b4b5a699-5278-4727-9f81-a50800ea9abc",
"status": "complete",
"created": "2015-09-03T14:14:10.000Z",
"metadata": {
"UserJobId": "some ID"
},
"correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
]
},
"total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
mass_payments = account_token.get "#{account_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"
<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3';
$masspaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);
$masspayments = $masspaymentsApi->getByAccount($accountUrl, 10, 0);
$masspayments->_embedded->{'mass-payments'}[0]->status; # => "complete"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
transfers = app_token.get('%s/mass-payments' % account_url, limit = 10)
transfers.body['_embedded']['mass-payments'][0]['status'] # => "complete"
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';
appToken
.get(`${accountUrl}/mass-payments`)
.then(res => res.body._embedded['mass-payments'][0].status); // => 'complete'
A Customer represents an individual or business with whom you intend to transact with and is programmatically created and managed by a Dwolla Master account via the API. In order for a Dwolla Account to create and manage Customers, an application must obtain permission from Dwolla before being enabled in production.
With a transfer of money, at least one party must complete the identity verification process, either the sender or the receiver. This can be either the Dwolla Master Account itself or a verified Customer type. Based on your business model and funds flow, it’s your decision about which party completes this process– you may even want to have both parties complete the identity verification process. A brief description of each Customer type is below, but for a more in-depth overview of each Customer type and what their capabilities are, check out our developer resource article.
Receive-only users are restricted to a “payouts only” funds flow. A receive-only user maintains limited functionality in the API and is only eligible to receive transfers to an attached bank account. This Customer type can only interact with verified Customers and a Dwolla Master Account.
Unverified Customers have a default sending transaction limit of $5,000 per week. A week is defined as Monday to Sunday UTC time. As this Customer is not identity verified, they will only be able to transact with verified Customers or your Dwolla Master Account.
Verified Customers are defined by their ability to both send and receive money, thus, being able to fit all funds flows. They can also interact with any Customer type and hold a balance funding source within the Dwolla network. Think of the Dwolla balance as a “wallet” which a Customer can send, receive, or hold funds to within the Dwolla network. With no weekly transfer limits, this Customer type is flexible for high transaction volumes.
A verified Customer can be created as a type of either Personal or Business.
| Link | Description |
|---|---|
| self | URL of the Customer resource |
| receive | Follow the link to create a transfer to this Customer. |
| funding-sources | GET this link to list the Customer’s funding sources. |
| transfers | GET this link to list the Customer’s transfers |
| send | (optional) If this link exists, this Customer can send funds. POST to this URL to create a transfer. |
| retry-verification | If the Customer has a status of retry, POST to this link to attempt to correct their identity verification information. |
| verify-with-document | If the Verified Customer of type personal or business has a status of document, POST to this link to upload a new color photo document to verify the Customer’s identity. If type business, the controller of the business. Read about Documents. |
| verify-business-with-document | If the Verified Customer of type business has a status of document, POST to this link to upload a new color photo document to verify the identity of the business itself. Read about Documents. |
| verify-controller-and-business-with-document | If the Verified Customer of type business has a status of document, POST to this link to upload new color photo documents to verify the identity of the controller of the business as well as the business itself. Read about Documents. |
| Parameter | Description |
|---|---|
| id | Customer’s unique identifier. |
| firstName | Customer’s first name. |
| lastName | Customer’s last name. |
| Customer’s email address. | |
| type | Either unverified, personal, business, or receive-only. |
| status | If type is unverified or receive-only: status can be unverified or suspended. If type is personal or business: status can be retry, document, verified, or suspended. |
| created | ISO-8601 timestamp. |
| Status | Description |
|---|---|
| unverified | Customers of type unverified or receive-only always have this status. |
| retry | Verified Customers of type personal or business can have this status. The initial verification attempt failed because the information provided did not satisfy our verification check. You can make one additional attempt by changing some or all the attributes of the existing Customer with a POST request. If the additional attempt fails, the resulting status will be either document or suspended. |
| document | Verified Customers of type personal or business can have this status. Dwolla requires additional documentation to identify the Customer in the document status. Read about Documents. |
| verified | Verified Customers of type personal or business can have this status. The Customer is currently verified. |
| suspended | All Customer types can have a status of suspended. The Customer is suspended and may neither send nor receive funds. Contact Dwolla support for more information. |
| deactivated | All Customer types can have a status of deactivated. A deactivated Customer may neither send nor receive funds. A deactivated Customer can be reactivated which moves the Customer to the status they were in prior to being deactivated. |
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"receive": {
"href": "https://api-sandbox.dwolla.com/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"edit-form": {
"href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
"type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
"resource-type": "customer"
},
"edit": {
"href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"funding-sources": {
"href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce/funding-sources",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"transfers": {
"href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"send": {
"href": "https://api-sandbox.dwolla.com/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
}
},
"id": "9da3aa7c-2524-430b-a751-6dc722735fce",
"firstName": "Jane",
"lastName": "Doe",
"email": "janedoe@email.com",
"type": "personal",
"status": "verified",
"created": "2016-08-17T18:58:47.630Z",
"address1": "99-99 33rd St",
"address2": "Apt 8",
"city": "Some City",
"state": "NY",
"postalCode": "11101",
"phone": "5554321234"
}
This section details how to create a new Customer.
To create Receive-only Users, you’ll provide the customer’s full name and email address, type with the value of receive-only, and businessName if applicable.
To create Unverified Customers, you will only need to provide the customer’s full name and email address, as well as a businessName if applicable.
To create Verified Customers, Dwolla will require additional information to confirm the identity of the individual or business. Verified Customers can include type business or personal. For businesses, Dwolla will need to verify information about both the business and the controller for that business. Dwolla does not identity verify the Account Admin.
POST https://api.dwolla.com/customers
| HTTP Status | Message |
|---|---|
| 400 | Duplicate customer or validation error. |
| 403 | Not authorized to create customers. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | Customer’s first name. |
| lastName | yes | string | Customer’s last name. |
| 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. |
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"firstName": "Jane",
"lastName": "Merchant",
"email": "jmerchant@nomail.net",
"type": "receive-only",
"businessName": "Jane Corp llc",
"ipAddress": "99.99.99.99"
}
HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:firstName => 'Jane',
:lastName => 'Merchant',
:email => 'jmerchant@nomail.net',
:type => 'receive-only',
:businessName => 'Jane Corp llc',
:ipAddress => '99.99.99.99'
}
customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customer = $customersApi->create([
'firstName' => 'Jane',
'lastName' => 'Merchant',
'email' => 'jmerchant@nomail.net',
'type' => 'receive-only',
'businessName' => 'Jane Corp llc',
'ipAddress' => '99.99.99.99'
]);
$customer; # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'firstName': 'Jane',
'lastName': 'Merchant',
'email': 'jmerchant@nomail.net',
'type': 'receive-only',
'businessName': 'Jane Corp llc',
'ipAddress': '99.99.99.99'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
var requestBody = {
firstName: 'Jane',
lastName: 'Merchant',
email: 'jmerchant@nomail.net',
type: 'receive-only',
businessName: 'Jane Corp llc',
ipAddress: '99.99.99.99'
};
appToken
.post('customers', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | Customer’s first name. |
| lastName | yes | string | Customer’s last name. |
| yes | string | Customer’s email address. | |
| businessName | yes | string | Customer’s registered business name. (Optional if not a business entity) |
| ipAddress | no | string | Customer’s IP address. |
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"firstName": "Jane",
"lastName": "Merchant",
"email": "jmerchant@nomail.net",
"ipAddress": "99.99.99.99",
"businessName": "Jane Merchant's Business"
}
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:firstName => 'Jane',
:lastName => 'Merchant',
:email => 'jmerchant@nomail.net',
:ipAddress => '99.99.99.99'
}
customer = app_token.post "customers", request_body
customer.headers[:location] # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customer = $customersApi->create([
'firstName' => 'Jane',
'lastName' => 'Merchant',
'email' => 'jmerchant@nomail.net',
'ipAddress' => '99.99.99.99'
]);
$customer; # => "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'firstName': 'Jane',
'lastName': 'Merchant',
'email': 'jmerchant@nomail.net',
'ipAddress': '99.99.99.99'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
var requestBody = {
firstName: 'Jane',
lastName: 'Merchant',
email: 'jmerchant@nomail.net',
ipAddress: '99.99.99.99'
};
appToken
.post('customers', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
For an in-depth look at personal verified Customers creation and status handling, refer to our developer resource article.
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | An individual Customer’s first name. |
| lastName | yes | string | An individual Customer’s last name. |
| yes | string | Customer’s email address. | |
| ipAddress | no | string | Customer’s IP address. |
| type | yes | string | The Verified Customer type. Set to personal if creating a verified personal Customer. |
| address1 | yes | string | First line of the street address of the Customer’s permanent residence. Must be 50 characters or less. Note: PO Boxes are not allowed. |
| address2 | no | string | Second line of the street address of the Customer’s permanent residence. Must be 50 characters or less. Note: PO Boxes are not allowed. |
| city | yes | string | City of Customer’s permanent residence. |
| state | yes | string | Two letter abbreviation of the state in which the Customer resides, e.g. CA. |
| postalCode | yes | string | Postal code of Customer’s permanent residence. US five-digit ZIP or ZIP + 4 code. e.g. 50314. |
| dateOfBirth | yes | string | Customer’s date of birth in YYYY-MM-DD format. Must be 18 years or older. |
| ssn | yes | string | Last four digits of the Customer’s Social Security Number. |
| phone | no | string | Customer’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777. |
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@nomail.net",
"ipAddress": "10.10.10.10",
"type": "personal",
"address1": "99-99 33rd St",
"city": "Some City",
"state": "NY",
"postalCode": "11101",
"dateOfBirth": "1970-01-01",
"ssn": "1234"
}
HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customer = $customersApi->create([
'firstName' => 'John',
'lastName' => 'Doe',
'email' => 'jdoe@nomail.net',
'type' => 'personal',
'address1' => '99-99 33rd St',
'city' => 'Some City',
'state' => 'NY',
'postalCode' => '11101',
'dateOfBirth' => '1970-01-01',
# For the first attempt, only the
# last 4 digits of SSN required
# If the entire SSN is provided,
# it will still be accepted
'ssn' => '1234'
]);
$customer; # => "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:firstName => 'John',
:lastName => 'Doe',
:email => 'jdoe@nomail.net',
:type => 'personal',
:address1 => '99-99 33rd St',
:city => 'Some City',
:state => 'NY',
:postalCode => '11101',
:dateOfBirth => '1970-01-01',
# For the first attempt, only the
# last 4 digits of SSN required
# If the entire SSN is provided,
# it will still be accepted
:ssn => '1234'
}
customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'firstName': 'John',
'lastName': 'Doe',
'email': 'jdoe@nomail.net',
'type': 'personal',
'address1': '99-99 33rd St',
'city': 'Some City',
'state': 'NY',
'postalCode': '11101',
'dateOfBirth': '1970-01-01',
# For the first attempt, only the
# last 4 digits of SSN required
# If the entire SSN is provided,
# it will still be accepted
'ssn': '1234'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
var requestBody = {
firstName: 'John',
lastName: 'Doe',
email: 'jdoe@nomail.net',
type: 'personal',
address1: '99-99 33rd St',
city: 'Some City',
state: 'NY',
postalCode: '11101',
dateOfBirth: '1970-01-01',
// For the first attempt, only the
// last 4 digits of SSN required
// If the entire SSN is provided,
// it will still be accepted
ssn: '1234'
};
appToken
.post('customers', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'
For an in-depth look at business verified Customers creation and status handling, refer to our developer resource article. Dwolla will verify the identity of both the Business Owner and the Business entity.
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | The legal first name of the business owner. |
| lastName | yes | string | The legal last name of the business owner. |
| yes | string | email address of the business owner. | |
| ipAddress | no | string | ipAddress of registering user is recommended. |
| type | yes | string | Value of: business |
| dateOfBirth | yes | string | The date of birth of the business owner. Formatted in YYYY-MM-DD format. Must be 18 years or older. |
| ssn | yes | string | Last four-digits of the business owner’s social security number. |
| address1 | yes | string | Street number, street name of business’ physical address. |
| address2 | no | string | Apartment, floor, suite, bldg. # of business’ physical address |
| city | yes | string | City of business’ physical address. |
| state | yes | string | Two-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide. |
| postalCode | yes | string | Business’ US five-digit ZIP or ZIP + 4 code. |
| businessName | yes | string | Registered business name. |
| doingBusinessAs | no | string | Preferred business name – also known as fictitious name, or assumed name. |
| businessType | yes | string | Business structure. Value of soleProprietorship. |
| businessClassification | yes | string | The industry classification Id that corresponds to Customer’s business. Reference our Dev Docs to learn how to generate this Id. |
| ein | no | string | Employer Identification Number. Optional for soleProprietorship business Customers |
| website | no | string | Business’ website |
| phone | no | string | Business’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777. |
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q
{
"firstName": "Business",
"lastName": "Owner",
"email": "solePropBusiness@email.com",
"ipAddress": "143.156.7.8",
"type": "business",
"dateOfBirth": "1980-01-31",
"ssn": "6789",
"address1": "99-99 33rd St",
"city": "Some City",
"state": "NY",
"postalCode": "11101",
"businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
"businessType": "soleProprietorship",
"businessName":"Jane Corp",
"ein":"00-0000000"
}
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = 'https://api-sandbox.dwolla.com/customers/b70c3194-35fa-49e8-9243-d55a30e06d1e';
$new_customer = $customersApi->create([
'firstName' => 'Business',
'lastName' => 'Owner',
'email' => 'solePropBusiness@email.com',
'ipAddress' => '143.156.7.8',
'type' => 'business',
'dateOfBirth' => '1980-01-31',
'ssn' => '6789',
'address1' => '99-99 33rd St',
'city' => 'Some City',
'state' => 'NY',
'postalCode' => '11101',
'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
'businessType' => 'soleProprietorship',
'businessName' => 'Jane Corp',
'ein' => '00-0000000']);
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
:firstName => 'Business',
:lastName => 'Owner',
:email => 'solePropBusiness@email.com',
:ipAddress => '143.156.7.8',
:type => 'business',
:dateOfBirth => '1980-01-31',
:ssn => '6789',
:address1 => '99-99 33rd St',
:city => 'Some City',
:state => 'NY',
:postalCode => '11101',
:businessClassification => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
:businessType => 'soleProprietorship',
:businessName => 'Jane Corp',
:ein => '00-0000000'
}
customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
'firstName': 'Business',
'lastName': 'Owner',
'email': 'solePropBusiness@email.com',
'ipAddress': '143.156.7.8',
'type': 'business',
'dateOfBirth': '1980-01-31',
'ssn': '6789',
'address1': '99-99 33rd St',
'city': 'Some City',
'state': 'NY',
'postalCode': '11101',
'businessClassification': '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
'businessType': 'soleProprietorship',
'businessName': 'Jane Corp',
'ein': '00-0000000'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
var requestBody = {
firstName: 'Business',
lastName: 'Owner',
email: 'solePropBusiness@email.com',
ipAddress: '143.156.7.8',
type: 'business',
dateOfBirth: '1980-01-31',
ssn: '6789',
address1: '99-99 33rd St',
city: 'Some City',
state: 'NY',
postalCode: '11101',
businessClassification: '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
businessType: 'soleProprietorship',
businessName: 'Jane Corp',
ein: '00-0000000',
};
appToken
.post('customers', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
For an in-depth look at business verified Customers creation and status handling, refer to our developer resource article. A verified business Customer must input information on the controller and the Business entity for Dwolla. Dwolla will verify the identity of both the Controller and the Business Entity.
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | The legal first name of the Account Admin or business owner signing up the business verified Customer. |
| lastName | yes | string | The legal last name of the Account Admin or individual signing up the business verified Customer. |
| yes | string | email address of individual creating and managing the Customer account. | |
| ipAddress | no | string | ipAddress of registering user is recommended. |
| type | yes | string | Value of: business |
| address1 | yes | string | Street number, street name of business’ physical address. |
| address2 | no | string | Apartment, floor, suite, bldg. # of business’ physical address. |
| city | yes | string | City of business’ physical address. |
| state | yes | string | Two-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide. |
| postalCode | yes | string | Business’ US five-digit ZIP or ZIP + 4 code. |
| businessName | yes | string | Registered business name. |
| doingBusinessAs | no | string | Preferred business name – also known as fictitious name, or assumed name. |
| businessType | yes | string | Business structure. Possible values are corporation, llc, partnership. |
| businessClassification | yes | string | The industry classification Id that corresponds to Customer’s business. Reference the next section of our docs to learn how to generate this Id. |
| ein | yes | string | Employer Identification Number. |
| website | no | string | Business’ website |
| phone | no | string | Business’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777. |
| controller | conditional | object | A controller JSON object. |
A controller is any natural individual who holds significant responsibilities to control, manage, or direct a company or other corporate entity (i.e. CEO, CFO, General Partner, President, etc). A company may have more than one controller, but only one controller’s information must be collected.
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | String | The legal first name of the controller. |
| lastName | yes | String | The legal last name of the controller. |
| title | yes | String | Job title of the business verified Customer’s controller. IE - Chief Financial Officer |
| dateOfBirth | yes | String | The date of birth of the controller. Formatted in YYYY-MM-DD format. Must be 18 years or older. |
| ssn | conditional | String | Last four-digits of controller’s social security number. Required for US persons. |
| address | yes | object | An address JSON object. Full address of the controller’s physical address. |
| passport | conditional | object | An optional passport JSON object. Required for non-US persons. Includes passport identification number and country. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| address1 | yes | string | Street number, street name of controller’s physical address. |
| address2 | no | string | Apartment, floor, suite, bldg. # of controller’s physical address. |
| address3 | no | string | Third line of the street address of the controller’s physical address. |
| city | yes | string | City of controller’s physical address. |
| stateProvinceRegion | yes | string | Two-letter US state or territory abbreviation code of controller’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide. |
| postalCode | no | string | Controller’s’ US five-digit ZIP or ZIP + 4 code. |
| country | yes | string | Country of controller’s physical address |
A controller will only need to input Passport information if they are non-US persons and do not have a social security number.
| Parameter | Required | Type | Description |
|---|---|---|---|
| number | conditional | string | Required if controller is a non-US person and has no Social Security number. |
| country | conditional | string | Country of issued passport. |
POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q
{
"firstName": "Account",
"lastName": "Admin",
"email": "accountAdmin@email.com",
"ipAddress": "143.156.7.8",
"type": "business",
"address1": "99-99 33rd St",
"city": "Some City",
"state": "NY",
"postalCode": "11101",
"controller": {
"firstName": "John",
"lastName": "Controller",
"title": "CEO",
"ssn": "6789",
"dateOfBirth": "1980-01-31",
"address": {
"address1": "1749 18th st",
"address2": "apt 12",
"city": "Des Moines",
"stateProvinceRegion": "IA",
"postalCode": "50266",
"country": "US"
}
},
"businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
"businessType": "llc",
"businessName":"Jane Corp",
"ein":"00-0000000"
}
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = 'https://api-sandbox.dwolla.com/customers/b70c3194-35fa-49e8-9243-d55a30e06d1e';
$new_customer = $customersApi->create([
'firstName' => 'Account',
'lastName' => 'Admin',
'email' => 'accountAdmin@email.com',
'type' => 'business',
'address1' => '99-99 33rd St',
'city' => 'Some City',
'state' => 'NY',
'postalCode' => '11101',
'controller' =>
[
'firstName' => 'John',
'lastName'=> 'Controller',
'title' => 'CEO',
'dateOfBirth' => '1990-10-10',
'ssn' => '1234',
'address' =>
[
'address1' => '18749 18th st',
'address2' => 'apt 12',
'city' => 'Des Moines',
'stateProvinceRegion' => 'IA',
'postalCode' => '50265',
'country' => 'US'
],
],
'phone' => '5554321234',
'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
'businessType' => 'llc',
'businessName' => 'Jane Corp',
'ein' => '00-0000000']);
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
:firstName => 'Account',
:lastName => 'Admin',
:email => 'accountAdmin@email.com',
:type => 'business',
:address1 => '99-99 33rd St',
:city => 'Some City',
:state => 'NY',
:postalCode => '11101',
:controller => {
:firstName => 'John',
:lastName => 'Controller',
:title => 'CEO',
:dateOfBirth => '1980-01-31',
:ssn => '1234',
:address => {
:address1 => '1749 18th st',
:address2 => 'apt 12',
:city => 'Des Moines',
:stateProvinceRegion => 'IA',
:postalCode => '50266',
:country => 'US',
}
},
:businessClassification => '9ed38155-7d6f-11e3-83c3-5404a6144203',
:businessType => 'llc',
:businessName => 'Jane Corp',
:ein => '12-3456789'
}
customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
'firstName': 'Account',
'lastName': 'Admin',
'email': 'accountAdmin@email.com',
'type': 'business',
'address1': '99-99 33rd St',
'city': 'Some City',
'state': 'NY',
'postalCode': '11101',
'controller': {
'firstName': 'John',
'lastName': 'Controller',
'title': 'CEO',
'dateOfBirth': '1980-01-31',
'ssn': '1234',
'address': {
'address1': '1749 18th st',
'address2': 'apt12',
'city': 'Des Moines',
'stateProvinceRegion': 'IA',
'postalCode': '50266',
'country': 'US'
}
},
'businessClassification': '9ed38155-7d6f-11e3-83c3-5404a6144203',
'businessType': 'llc',
'businessName': 'Jane Corp',
'ein': '12-3456789'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
var requestBody = {
firstName: 'Account',
lastName: 'Admin',
email: 'accountAdmin@email.com',
type: 'business',
address1: '99-99 33rd St',
city: 'Some City',
state: 'NY',
postalCode: '11101',
controller: {
firstName: 'John',
lastName: 'Controller',
title: 'CEO',
dateOfBirth: '1980-01-31',
ssn: '1234'
address: {
address1: '1749 18th st',
address2: 'apt 12',
city: 'Des Moines',
stateProvinceRegion: 'IA',
postalCode: '50266',
country: 'US',
}
},
businessClassification: '9ed38155-7d6f-11e3-83c3-5404a6144203',
businessType: 'llc',
businessName: 'Jane Corp',
ein: '12-3456789'
};
appToken
.post('customers', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
This section shows you how to retrieve a Customer belonging to the authorized Dwolla Master Account. Each Customer id is a part of its location resource. You can pass either an id or the entire location resource to make this request.
GET https://api.dwolla.com/customers/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
| HTTP Status | Message |
|---|---|
| 403 | Not authorized to get a customer by id. |
| 404 | Customer not found. |
GET https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8"
}
},
"id": "FC451A7A-AE30-4404-AB95-E3553FCD733F",
"firstName": "Jane",
"lastName": "Doe",
"email": "janedoe@nomail.com",
"type": "unverified",
"status": "unverified",
"created": "2015-09-03T23:56:10.023Z"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
customer = app_token.get customer_url
customer.firstName # => "Jane"
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8';
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customer = $customersApi->getCustomer($customerUrl);
$customer->firstName; # => "Jane"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8'
customer = app_token.get(customer_url)
customer.body['firstName']
var customerUrl = 'https://api-sandbox.dwolla.com/customers/07D59716-EF22-4FE6-98E8-F3190233DFB8';
appToken
.get(customerUrl)
.then(res => res.body.firstName); // => 'Jane'
This section outlines how to retrieve your list of created Customers.
GET https://api.dwolla.com/customers
| Parameter | Required | Type | Description |
|---|---|---|---|
| limit | no | integer | How many results to return. |
| offset | no | integer | How many results to skip. |
| search | no | string | Searches on firstName, lastName, and email fields. (/customers?search=Doe) |
| status | no | string | Filter by Customer status or multiple Customer statuses. Possible values: unverified, retry, document, verified, suspended, or deactivated. (e.g. /customers?status=retry&status=document) |
GET https://api-sandbox.dwolla.com/customers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"first": {
"href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
},
"last": {
"href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
},
"self": {
"href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
}
},
"_embedded": {
"customers": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
}
},
"id": "FC451A7A-AE30-4404-AB95-E3553FCD733F",
"firstName": "Jane",
"lastName": "Doe",
"email": "janedoe@nomail.com",
"type": "unverified",
"status": "unverified",
"created": "2015-09-03T23:56:10.023Z"
}
]
},
"total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customers = app_token.get "customers", limit: 10
customers._embedded.['customers'][0].firstName # => "Jane"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customers = $customersApi->_list(10, 0);
$customers->_embedded->{'customers'}[0]->firstName; # => "Jane"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer = app_token.get('customers', limit = 10)
customer.body['_embedded']['customers'][0]['firstName'] # => 'Jane'
appToken
.get('customers', { limit: 10 })
.then(res => res.body._embedded['customers'][0].firstName); // => 'Jane'
This endpoint can be used to facilitate the following use cases: Update Customer information, upgrade an unverified Customer to a verified Customer, suspend a Customer, deactivate a Customer, reactivate a Customer, and update a verified Customer’s information to retry verification.
POST https://api.dwolla.com/customers/{id}
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.
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | no | string | Customer’s first name. |
| lastName | no | string | Customer’s last name. |
| no | string | Customer’s email address. | |
| businessName | no | string | Customer’s registered business name. An empty string value will unset businessName. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| no | string | Customer’s email address. | |
| ipAddress | no | string | Customer’s IP address. |
| address1 | no | string | First line of the street address of the customer’s permanent residence. Note: PO Boxes are not allowed. |
| address2 | no | string | Second line of the street address of the customer’s permanent residence. Note: PO Boxes are not allowed. |
| city | no | string | City of customer’s permanent residence. |
| state | no | string | Two letter abbreviation of the state in which the customer resides. e.g. NY. |
| postalCode | no | string | Postal code of customer’s permanent residence. Should be a five digit postal code, e.g. 50314. |
| phone | no | string | Customer’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777. |
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 |
An unverified Customer can be upgraded to a verified Customer by supplying the necessary information required to create a verified Customer. Reference this table for required information.
Unverified and Verified Customers can be suspended by specifying a status of suspended in your request. You’ll need to contact Dwolla to unsuspend a Customer.
| Parameter | Required | Type | Description |
|---|---|---|---|
| status | yes | string | Value of suspended. |
Customers can be deactivated by specifying a status of deactivated in your request. A Customer cannot be deactivated if the Customer has a suspended verification status. Customers can be systematically deactivated by Dwolla if certain ACH return codes are triggered on bank transfer failures.
| Parameter | Required | Type | Description |
|---|---|---|---|
| status | yes | string | Value of deactivated. |
Customers can be reactivated by specifying a status of reactivated in your request. Reactivated Customers will be moved to the status they were in prior to being deactivated.
| Parameter | Required | Type | Description |
|---|---|---|---|
| status | yes | string | Value of reactivated. |
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.
{
"_links": {
"deactivate": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"self": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"edit-form": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
"resource-type": "customer"
},
"edit": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"funding-sources": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/funding-sources",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"retry-verification": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"transfers": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
}
},
"id": "53863b11-1758-47c8-821f-00e6a126f97f",
"firstName": "retry",
"lastName": "doe",
"email": "jdoe@nomail.com",
"type": "personal",
"status": "retry",
"created": "2017-11-06T20:11:13.430Z",
"address1": "99-99 33rd St",
"city": "Some City",
"state": "NY",
"postalCode": "11101"
}
POST https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"firstName": "John",
"lastName": "Doe",
"email": "jdoe@nomail.com",
"ipAddress": "10.10.10.10",
"type": "personal",
"address1": "221 Corrected Address St.",
"address2": "Apt 201",
"city": "San Francisco",
"state": "CA",
"postalCode": "94104",
"dateOfBirth": "1970-07-11",
"ssn": "123-45-6789"
}
...
{
"_links": {
"deactivate": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"self": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"receive": {
"href": "https://api-sandbox.dwolla.com/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"edit-form": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
"resource-type": "customer"
},
"edit": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"funding-sources": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/funding-sources",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"transfers": {
"href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"send": {
"href": "https://api-sandbox.dwolla.com/transfers",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
}
},
"id": "53863b11-1758-47c8-821f-00e6a126f97f",
"firstName": "John",
"lastName": "Doe",
"email": "jdoe@nomail.com",
"type": "personal",
"status": "verified",
"created": "2017-11-06T20:11:13.430Z",
"address1": "221 Corrected Address St.",
"address2": "Apt 201",
"city": "San Francisco",
"state": "CA",
"postalCode": "94104"
}
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customerUrl = 'https://api.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f';
$customer = $customersApi->updateCustomer(array (
'firstName' => 'John',
'lastName' => 'Doe',
'email' => 'jdoe@nomail.com',
'ipAddress' => '10.10.10.10',
'type' => 'personal',
'address1' => '221 Corrected Address St.',
'address2' => 'Apt 201',
'city' => 'San Francisco',
'state' => 'CA',
'postalCode' => '94104',
'dateOfBirth' => '1970-07-11',
'ssn' => '123-45-6789',
), $customerUrl);
$customer->id; # => "53863b11-1758-47c8-821f-00e6a126f97f"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f'
request_body = {
"firstName" => "John",
"lastName" => "Doe",
"email" => "jdoe@nomail.com",
"ipAddress" => "10.10.10.10",
"type" => "personal",
"address1" => "221 Corrected Address St.",
"address2" => "Apt 201",
"city" => "San Francisco",
"state" => "CA",
"postalCode" => "94104",
"dateOfBirth" => "1970-07-11",
"ssn" => "123-45-6789"
}
customer = app_token.post customer_url, request_body
customer.id # => "53863b11-1758-47c8-821f-00e6a126f97f"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f'
request_body = {
"firstName": "John",
"lastName": "Doe",
"email": "jdoe@nomail.com",
"ipAddress": "10.10.10.10",
"type": "personal",
"address1": "221 Corrected Address St.",
"address2": "Apt 201",
"city": "San Francisco",
"state": "CA",
"postalCode": "94104",
"dateOfBirth": "1970-07-11",
"ssn": "123-45-6789"
}
customer = app_token.post(customer_url, request_body)
customer.body.id # => '53863b11-1758-47c8-821f-00e6a126f97f'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f';
var requestBody = {
firstName: "John",
lastName: "Doe",
email: "johndoe@dwolla.com",
ipAddress: "10.10.10.10",
type: "personal",
address1: "221 Corrected Address St.",
address2: "Fl 8",
city: "Ridgewood",
state: "NY",
postalCode: "11385",
dateOfBirth: "1990-07-11",
ssn: "202-99-1516"
};
appToken
.post(customerUrl, requestBody)
.then(res => res.body.id); // => '53863b11-1758-47c8-821f-00e6a126f97f'
{
"code": "InvalidResourceState",
"message": "Resource cannot be modified."
}
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | Customer’s first name. |
| lastName | yes | string | Customer’s last name. |
| yes | string | Customer’s email address. | |
| ipAddress | no | string | Customer’s IP address. |
| type | yes | string | Either personal or business. If business, see above for additional required information. |
| address1 | yes | string | First line of the street address of the Customer’s permanent residence. Note: PO Boxes are not allowed. |
| address2 | no | string | Second line of the street address of the Customer’s permanent residence. Note: PO Boxes are not allowed. |
| city | yes | string | City of Customer’s permanent residence. |
| state | yes | string | Two letter abbreviation of the state in which the customer resides, e.g. CA. |
| postalCode | yes | string | Postal code of Customer’s permanent residence. Should be a five digit postal code, e.g. 50314. |
| dateOfBirth | yes | string | Customer’s date of birth in YYYY-MM-DD format. Must be 18 years or older. |
| ssn | yes | string | Customer’s full Social Security Number. |
| phone | no | string | Customer’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777. |
| HTTP Status | Message |
|---|---|
| 400 | Duplicate customer or validation error. |
| 403 | Not authorized to create customers. |
Retrieve an _embedded list of business classifications that contains an _embedded list of industry classifications. An industry classification is used to identify the Customer’s business and is required by Dwolla when verifying a business in order to better analyze the nature of a business.
GET https://api.dwolla.com/business-classifications
GET https://api-sandbox.dwolla.com/business-classifications
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {},
"_embedded": {
"business-classifications": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/business-classifications/9ed3f669-7d6f-11e3-b545-5404a6144203"
}
},
"_embedded": {
"industry-classifications": [
{
"id": "9ed3f671-7d6f-11e3-803c-5404a6144203",
"name": "Gourmet foods"
},
{
"id": "9ed3f66c-7d6f-11e3-86ae-5404a6144203",
"name": "Distilleries"
},
{
...........
}
]
},
"id": "9ed3f669-7d6f-11e3-b545-5404a6144203",
"name": "Food retail and service"
}
...........
]
},
"total": 27
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
business_classifications = app_token.get "business-classifications"
business_classifications._embedded['business-classifications'][0].name # => "Food retail and service"
<?php
$businessClassificationsApi = new DwollaSwagger\BusinessclassificationsApi($apiClient);
$busClassifications = $businessClassificationsApi->_list();
$busClassifications->_embedded->{'business-classifications'}[0]->name; # => "Food retail and service"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
business_classifications = app_token.get('business-classifications')
business_classifications.body['_embedded']['business-classifications'][0]['name'] # => 'Food retail and service'
appToken
.get('business-classifications')
.then(res => res.body._embedded['business-classifications'][0].name); // => 'Food retail and service'
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.
GET https://api.dwolla.com/business-classifications/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Business classification unique identifier. |
GET https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203"
}
},
"_embedded": {
"industry-classifications": [
{
"id": "9ed3cf58-7d6f-11e3-81a4-5404a6144203",
"name": "Toys and games"
},
{
"id": "9ed3cf50-7d6f-11e3-8ae8-5404a6144203",
"name": "Music"
},
{
...........
}
]
},
"id": "9ed3a866-7d6f-11e3-a0ce-5404a6144203",
"name": "Entertainment and media"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
business_classification_url = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203'
business_classification = app_token.get business_classification_url
business_classification.name # => "Entertainment and media"
<?php
$businessClassificationUrl = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203';
$businessClassificationsApi = new DwollaSwagger\BusinessclassificationsApi($apiClient);
$busClassifications = $customersApi->getBusinessClassification($businessClassificationUrl);
$busClassifications->name; # => "Entertainment and media"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
business_classification_url = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203'
busClassification = app_token.get(business_classification_url)
busClassification.body['name']
var businessClassificationUrl = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203';
appToken
.get(businessClassificationUrl)
.then(res => res.body.name); // => 'Entertainment and media'
Verified Customers of type business are required to verify the identity of beneficial owners in addition to the controller of the business if they are one of the following business types:
For more information on how to add beneficial owners, or to learn more on whether certain business types are exempt, check out our beneficial owner developer resource article.
| Parameter | Description |
|---|---|
| id | The beneficial owner unique identifier. |
| firstName | The legal first name of the beneficial owner. |
| lastName | The legal last name of the beneficial owner. |
| address | The beneficial owner’s physical address. |
| verificationStatus | Possible values of verified, document, or incomplete. |
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/caa81a5f-ec1e-4559-8b32-d90655bfd03c",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-owner"
}
},
"id": "caa81a5f-ec1e-4559-8b32-d90655bfd03c",
"firstName": "Joe",
"lastName": "owner",
"address": {
"address1": "12345 18th st",
"address2": "Apt 12",
"address3": "",
"city": "Des Moines",
"stateProvinceRegion": "IA",
"country": "US",
"postalCode": "50265"
},
"verificationStatus": "verified"
}
This section details how to create a new beneficial owner. To create beneficial owners, you need to collect the beneficial owner’s full name, ssn, date of birth, and permanent address. Optionally, passport information must be included for foreign individuals that do not have a US issued SSN. Beneficial owners require additional information that will give Dwolla the ability to confirm the identity of the individual.
For more information on how to create a beneficial owner, refer to our developer resource article.
POST https://api.dwolla.com/customers/{id}/beneficial-owners
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | The legal first name of the beneficial owner. |
| lastName | yes | string | The legal last name of the beneficial owner. |
| ssn | conditional | string | Full nine digits of beneficial owner’s social security number. If ssn is omitted, passport is required. |
| dateOfBirth | Yes | string | beneficial owner’s date of birth in YYYY-MM-DD format. Must be 18 years or older. |
| address | Yes | object | An address JSON object. Full address of the controller’s physical address. |
| passport | conditional | object | An optional passport JSON object. Required for non-US persons. Includes passport identification number and country. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| address1 | yes | string | First line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed. |
| address2 | no | string | Second line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed. |
| address3 | no | string | Third line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed. |
| city | yes | string | City of beneficial owner’s permanent residence. |
| stateProvinceRegion | yes | string | Two-letter US state or territory abbreviation code of beneficial owner’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide. |
| country | yes | string | Country of beneficial owner’s permanent residence. Two digit ISO code, e.g. US. |
| postalCode | yes | string | Postal code of beneficial owner’s permanent residence. Should be a five digit postal code, e.g. 50314. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| number | conditional | string | Required if beneficial owner is a non-US person and has no Social Security number. |
| country | conditional | string | Country of issued passport. |
POST https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"firstName": "document",
"lastName": "owner",
"ssn": "123-46-7890",
"dateOfBirth": "1960-11-30",
"address": {
"address1": "123 Main St.",
"city": "New York",
"stateProvinceRegion": "NY",
"country": "US",
"postalCode": "10005"
}
}
HTTP/1.1 201 Created
Location: https://api.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$verified_customer = 'https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5';
$addOwner = $customersApi->addBeneficialOwner([
'firstName' => 'document',
'lastName'=> 'owner',
'dateOfBirth' => '1990-11-11',
'ssn' => '123-34-9876',
'address' =>
[
'address1' => '18749 18th st',
'address2' => 'apt 12',
'address3' => '',
'city' => 'Des Moines',
'stateProvinceRegion' => 'IA',
'postalCode' => '50265',
'country' => 'US'
],
], $verified_customer);
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5'
request_body = {
:firstName => 'John',
:lastName => 'Doe',
:ssn => '123-46-7890',
:dateOfBirth => '1970-01-01',
:address => {
:address1 => '99-99 33rd St',
:city => 'Some City',
:stateProvinceRegion => 'NY',
:country => 'US',
:postalCode => '11101'
}
}
beneficial_owner = app_token.post "#{customer_url}/beneficial-owners", request_body
beneficial_owner.response_headers[:location] # => "https://api-sandbox.dwolla.com/beneficial-owners/AB443D36-3757-44C1-A1B4-29727FB3111C"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
'firstName': 'John',
'lastName': 'Doe',
'dateOfBirth': '1970-01-01',
'ssn': '123-46-7890',
'address': {
'address1': '99-99 33rd St',
'city': 'Some City',
'stateProvinceRegion': 'NY',
'country': 'US',
'postalCode': '11101'
}
}
beneficial_owner = app_token.post('%s/beneficial-owners' % customer_url, request_body)
beneficial_owner.headers['location'] # => 'https://api-sandbox.dwolla.com/beneficial-owners/AB443D36-3757-44C1-A1B4-29727FB3111C'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8';
var requestBody = {
firstName: 'John',
lastName: 'Doe',
dateOfBirth: '1970-01-01',
ssn: '123-56-7890',
address: {
address1: '99-99 33rd St',
city: 'Some City',
stateProvinceRegion: 'NY',
country: 'US'
postalCode: '11101'
}
};
appToken
.post(`${customerUrl}/beneficial-owners`, requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F'
This section contains information on how to retrieve a beneficial owner which belongs to a Customer.
GET https://api.dwolla.com/beneficial-owners/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Beneficial owner unique identifier. |
GET https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8'
beneficial_owner = app_token.get beneficial_owner_url
beneficial_owner.firstName # => "Jane"
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8';
$beneficialOwner = $beneficialOwnersApi->getById($beneficialOwnerUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8'
beneficial_owner = app_token.get(beneficial_owner_url)
beneficial_owner.body['firstName']
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
appToken
.get(beneficialOwnerUrl)
.then(res => res.body.firstName); // => 'Jane'
This section contains information on how to retrieve a list of beneficial owners that belong to a Customer.
GET https://api.dwolla.com/customers/{id}/beneficial-owners
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
GET https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-owner"
}
},
"_embedded": {
"beneficial-owners": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/55469604-40ab-44b6-962f-de2c0837ba98",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-owner"
},
"verify-with-document": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/55469604-40ab-44b6-962f-de2c0837ba98/documents",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "document"
}
},
"id": "55469604-40ab-44b6-962f-de2c0837ba98",
"firstName": "document",
"lastName": "owner1",
"address": {
"address1": "18749 18th st",
"address2": "apt 12",
"address3": "",
"city": "Des Moines",
"stateProvinceRegion": "IA",
"country": "US",
"postalCode": "50265"
},
"verificationStatus": "document"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/caa81a5f-ec1e-4559-8b32-d90655bfd03c",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-owner"
}
},
"id": "caa81a5f-ec1e-4559-8b32-d90655bfd03c",
"firstName": "Joe",
"lastName": "owner2",
"address": {
"address1": "18749 18th st",
"address2": "apt 12",
"address3": "",
"city": "Des Moines",
"stateProvinceRegion": "IA",
"country": "US",
"postalCode": "50265"
},
"verificationStatus": "verified"
}
]
},
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'
beneficial_owners = app_token.get "#{customer_url}/beneficial-owners"
beneficial_owners._embedded['beneficial-owners'][0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customerUrl = 'https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5';
$beneficialOwnerList = $customersApi->getBeneficialOwners($customerUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'
beneficial_owners = app_token.get('%s/beneficial-owners' % customer_url)
beneficial_owners.body['id']
var customerUrl = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';
token
.get(`${customerUrl}/beneficial-owners`)
.then(res => res.body._embedded['beneficial-owners'][0].id); // => '56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
This endpoint can be used to update a beneficial owner’s information to retry verification. A beneficial owner’s information can only be updated if their verification status is incomplete.
POST https://api.dwolla.com/beneficial-owners/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| firstName | yes | string | The legal first name of the beneficial owner. |
| lastName | yes | string | The legal last name of the beneficial owner. |
| ssn | conditional | string | Full nine digits of beneficial owner’s social security number. If ssn is omitted, passport is required. |
| dateOfBirth | Yes | string | beneficial owner’s date of birth in YYYY-MM-DD format. Must be 18 years or older. |
| address | Yes | object | An address JSON object. Full address of the controller’s physical address. |
| passport | conditional | object | An optional passport JSON object. Required for non-US persons. Includes passport identification number and country. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| address1 | yes | string | First line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed. |
| address2 | no | string | Second line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed. |
| address3 | no | string | Third line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed. |
| city | yes | string | City of beneficial owner’s permanent residence. |
| stateProvinceRegion | yes | string | Two-letter US state or territory abbreviation code of beneficial owner’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide. |
| country | yes | string | Country of beneficial owner’s permanent residence. Two digit ISO code, e.g. US. |
| postalCode | yes | string | Postal code of beneficial owner’s permanent residence. Should be a five digit postal code, e.g. 50314. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| number | conditional | string | Required if beneficial owner is a non-US person and has no Social Security number. |
| country | conditional | string | Country of issued passport. |
POST https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"firstName": "beneficial",
"lastName": "owner",
"ssn": "123-54-6789",
"dateOfBirth": "1963-11-11",
"address": {
"address1": "123 Main St.",
"address2": "Apt 123",
"city": "Des Moines",
"stateProvinceRegion": "IA",
"country": "US",
"postalCode": "50309"
}
}
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-owner"
}
},
"id": "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b",
"firstName": "beneficial",
"lastName": "owner",
"address": {
"address1": "123 Main St.",
"address2": "Apt 123",
"city": "Des Moines",
"stateProvinceRegion": "IA",
"country": "US",
"postalCode": "50309"
},
"verificationStatus": "verified"
}
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
$updateBeneficialOwner = $beneficialOwnersApi->update([
'firstName' => 'beneficial',
'lastName'=> 'owner',
'dateOfBirth' => '1963-11-11',
'ssn' => '123-54-6789',
'address' =>
[
'address1' => '123 Main St.',
'address2' => 'Apt 123',
'city' => 'Des Moines',
'stateProvinceRegion' => 'IA',
'postalCode' => '50309',
'country' => 'US'
],
], $beneficialOwnerUrl);
$updateBeneficialOwner->id; # => "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'
request_body = {
:firstName => 'beneficial',
:lastName => 'owner',
:ssn => '123-54-6789',
:dateOfBirth => '1963-11-11',
:address => {
:address1 => '123 Main St',
:city => 'Des Moines',
:stateProvinceRegion => 'IA',
:country => 'US',
:postalCode => '50309'
}
}
update_beneficial_owner = app_token.post beneficial_owner_url, request_body
update_beneficial_owner.id # => "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'
request_body = {
'firstName': 'beneficial',
'lastName': 'owner',
'dateOfBirth': '1963-11-11',
'ssn': '123-54-6789',
'address': {
'address1': '123 Main St',
'city': 'Des Moines',
'stateProvinceRegion': 'IA',
'country': 'US',
'postalCode': '50309'
}
}
update_beneficial_owner = app_token.post(beneficial_owner_url, request_body)
update_beneficial_owner.body['id'] # => '00cb67f2-768c-4ee3-ac81-73bc4faf9c2b'
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
var requestBody = {
firstName: 'beneficial',
lastName: 'owner',
dateOfBirth: '1963-11-11',
ssn: '123-54-6789',
address: {
address1: '123 Main St',
city: 'Des Moines',
stateProvinceRegion: 'IA',
country: 'US'
postalCode: '50309'
}
};
appToken
.post(beneficialOwnerUrl, requestBody)
.then(res => res.body.id); // => '00cb67f2-768c-4ee3-ac81-73bc4faf9c2b'
| HTTP Status | Message |
|---|---|
| 400 | Duplicate customer or validation error. |
| 403 | Not authorized to create customers. |
Delete a beneficial owner. A removed beneficial owner cannot be retrieved after being removed.
DELETE https://api.dwolla.com/beneficial-owners/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of beneficial owner to delete. |
| HTTP Status | Message |
|---|---|
| 404 | Beneficial owner not found. |
DELETE https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/0f394602-d714-4d77-9d58-3a3e8394bcdd",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-owner"
}
},
"id": "0f394602-d714-4d77-9d58-3a3e8394bcdd",
"firstName": "B",
"lastName": "Owner",
"address": {
"address1": "123 Main St.",
"city": "New York",
"stateProvinceRegion": "NY",
"country": "US",
"postalCode": "10005"
},
"verificationStatus": "verified"
}
...
HTTP 200 OK
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'
app_token.delete beneficial_owner_url
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';
appToken.delete(beneficialOwnerUrl);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'
app_token.delete(beneficial_owner_url)
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwner = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';
$deletedBeneficialOwner = $beneficialOwnersApi->deleteById($beneficialOwner);
?>
This section contains information on how to retrieve a Customer’s beneficial ownership status.
GET https://api.dwolla.com/customers/{id}/beneficial-ownership
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
GET https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc/beneficial-ownership",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-ownership"
}
},
"status": "uncertified"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
beneficial_ownership = app_token.get "#{customer_url}/beneficial-ownership"
beneficial_ownership.status # => "uncertified"
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$newCustomer = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';
$customerOwnershipStatus = $customersApi->getOwnershipStatus($newCustomer);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
beneficial_ownership = app_token.get('%s/beneficial-ownership' % customer_url)
beneficial_ownership.body['status'] # => 'uncertified'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';
appToken
.get(`${customer_url}/beneficial-ownership`)
.then(res => res.body.status); // => "uncertified"
This section contains information on how to certify beneficial ownership for a business Verified Customer.
POST https://api.dwolla.com/customers/{id}/beneficial-ownership
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
POST https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc/beneficial-ownership
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"status": "certified"
}
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc/beneficial-ownership",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "beneficial-ownership"
}
},
"status": "certified"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
:status => "certified"
}
app_token.post "#{customer_url}/beneficial-ownership", request_body
var customerUrl = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
var requestBody = {
status: 'certified'
};
appToken.post(`${customerUrl}/beneficial-ownership`, requestBody);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
"status": "certified"
}
app_token.post('%s/beneficial-ownership' % customer_url, request_body)
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customerId = 'https://api-sandbox.dwolla.com/customers/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
$certifyCustomer = $customersApi->changeOwnershipStatus(['status' => 'certified' ], $customerId);
?>
Verified Customers of type personal or business and of status document require color photos of identifying documents to be uploaded for manual review in order to be verified. Currently, SDK support for document upload only exists for Ruby, Node.js, and Python. To upload a document using other languages, you must use an external HTTP library.
For more information on handling the Customer verification status of document, reference our Customer verification resource article.
| Parameter | Description |
|---|---|
| id | Document unique identifier |
| type | Either passport, license, idCard, or other. Must be a color scan of US Government issued identification. |
| 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, scanDobMismatch or ScanNameMismatch. |
{
"_links": {
"self": {
"href": "https://api.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
}
},
"id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
"status": "pending",
"type": "passport",
"created": "2015-09-29T21:42:16.000Z"
}
Create a document for a Customer pending verification by uploading a color scan or photo of government issued identification (see below for acceptable document types). This requires a multipart form-data POST request. The uploaded file must be a color image, in a .jpg, .jpeg, .png, or .pdf format, and less than 10MB in size.
| Customer type | Acceptable documents |
|---|---|
| Personal Verified Customer | passport, license, or idCard. Must be a color scan of US Government issued identification. |
| Business Verified Customer | Controller documents - passport, license, idCard, or other. Must be a color scan of US Government issued identification. Business documents - Refer to our guide on Handling Document status for Business Verified Customers for acceptable documents. Beneficial Owner documents - Refer to our guide on Handling Document status for Beneficial Owners for acceptable documents. |
POST https://api.dwolla.com/customers/{id}/documents
| Form Field | Description |
|---|---|
| documentType | Acceptable values of: passport, license, idCard, or other |
| file | File contents. |
| HTTP Status | Code | Description |
|---|---|---|
| 201 | Created | A document resource was created. |
| 400 | maximumNumberOfResources | Max of four files upload allowed. Please wait for Dwolla to manually check the documents. |
| 400 | invalidFileType | File types supported: .jpg, .jpeg, .png, or .pdf. |
| 403 | invalidResourceState | Resource cannot be modified. Document creation not allowed for already verified Customers or non-verified Customer types. |
| 403 | notAuthorized | Not authorized to create documents. |
| 404 | notFound | Customer not found. Check CustomerId. |
| 413 | fileTooLarge | Document requests are limited to 10 mb. |
curl -X POST
\ -H "Authorization: Bearer tJlyMNW6e3QVbzHjeJ9JvAPsRglFjwnba4NdfCzsYJm7XbckcR"
\ -H "Accept: application/vnd.dwolla.v1.hal+json"
\ -H "Cache-Control: no-cache"
\ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
\ -F "documentType=passport"
\ -F "file=@foo.png"
\ 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE/documents'
...
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0
customer_url = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'
file = Faraday::UploadIO.new('mclovin.jpg', 'image/jpeg')
document = app_token.post "#{customer_url}/documents", file: file, documentType: 'license'
document.response_headers[:location] # => "https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'
document = app_token.post('%s/documents' % customer_url, file = open('mclovin.jpg', 'rb'), documentType = 'license')
document.headers['location'] # => 'https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16'
/**
* No example for this language yet.
**/
var customerUrl = 'https://api-sandbox.dwolla.com/customers/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE';
var requestBody = new FormData();
body.append('file', fs.createReadStream('mclovin.jpg'), {
filename: 'mclovin.jpg',
contentType: 'image/jpeg',
knownLength: fs.statSync('mclovin.jpg').size
});
body.append('documentType', 'license');
appToken
.post(`${customerUrl}/documents`, requestBody)
.then(res => res.headers.get('location')); // => "https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
This section contains information on how to retrieve a list of documents that belong to a Customer.
GET https://api.dwolla.com/customers/{id}/documents
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
GET https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents"
}
},
"_embedded": {
"documents": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
}
},
"id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
"status": "pending",
"type": "passport",
"created": "2015-09-29T21:42:16.000Z"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0"
}
},
"id": "11fe0bab-39bd-42ee-bb39-275afcc050d0",
"status": "pending",
"type": "passport",
"created": "2015-09-29T21:45:37.000Z"
}
]
},
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'
documents = app_token.get "#{customer_url}/documents"
documents._embedded['documents'][0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customer = $customersApi->getCustomerDocuments($customerUrl);
$customer->total; # => 2
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2'
documents = app_token.get('%s/documents' % customer_url)
documents.body['total'] # => 2
var customerUrl = 'https://api-sandbox.dwolla.com/customers/176878b8-ecdb-469b-a82b-43ba5e8704b2';
token
.get(`${customerUrl}/documents`)
.then(res => res.body._embedded['documents'][0].id); // => '56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
Create a document for a beneficial owner pending verification by uploading a photo of the document. This requires a multipart form-data POST request. The file must be either a .jpg, .jpeg, .png, or .pdf up to 10MB in size.
POST https://api.dwolla.com/beneficial-owners/{id}/documents
| Form Field | Description |
|---|---|
| documentType | One of passport, license, idCard, or other |
| file | File contents. |
curl -X POST
\ -H "Authorization: Bearer tJlyMNW6e3QVbzHjeJ9JvAPsRglFjwnba4NdfCzsYJm7XbckcR"
\ -H "Accept: application/vnd.dwolla.v1.hal+json"
\ -H "Cache-Control: no-cache"
\ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
\ -F "documentType=passport"
\ -F "file=@foo.png"
\ 'https://api-sandbox.dwolla.com/beneficial-owners/1de32ec7-ff0b-4c0c-9f09-19629e6788ce/documents'
...
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'
file = Faraday::UploadIO.new('mclovin.jpg', 'image/jpeg')
document = app_token.post "#{beneficial_owner_url}/documents", file: file, documentType: 'license'
document.response_headers[:location] # => "https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'
document = app_token.post('%s/documents' % customer_url, file = open('mclovin.jpg', 'rb'), documentType = 'license')
document.headers['location'] # => 'https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16'
/**
* No example for this language yet.
**/
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE';
var requestBody = new FormData();
body.append('file', fs.createReadStream('mclovin.jpg'), {
filename: 'mclovin.jpg',
contentType: 'image/jpeg',
knownLength: fs.statSync('mclovin.jpg').size
});
body.append('documentType', 'license');
appToken
.post(`${beneficialOwnerUrl}/documents`, requestBody)
.then(res => res.headers.get('location')); // => "https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
This section contains information on how to retrieve a list of documents that belong to a beneficial owner.
GET https://api.dwolla.com/beneficial-owners/{id}/documents
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Beneficial owner unique identifier. |
GET https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2/documents"
}
},
"_embedded": {
"documents": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
}
},
"id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
"status": "pending",
"type": "passport",
"created": "2015-09-29T21:42:16.000Z"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0"
}
},
"id": "11fe0bab-39bd-42ee-bb39-275afcc050d0",
"status": "pending",
"type": "passport",
"created": "2015-09-29T21:45:37.000Z"
}
]
},
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2'
documents = token.get "#{beneficial_owner_url}/documents"
documents._embedded['documents'][0].id # => "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwner = 'https://api-sandbox.dwolla.com/beneficial-owners/55469604-40ab-44b6-962f-de2c0837ba98';
$listDocsBeneficialOwner = $beneficialOwnersApi->getBeneficialOwnerDocuments($beneficialOwner);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2'
documents = app_token.get('%s/documents' % beneficial_owner_url)
documents.body['total'] # => 2
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/176878b8-ecdb-469b-a82b-43ba5e8704b2';
token
.get(`${beneficialOwnerUrl}/documents`)
.then(res => res.body._embedded['documents'][0].id); // => '56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
This section contains information on how to retrieve a document by its id.
GET https://api.dwolla.com/documents/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Document unique identifier. |
GET https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
}
},
"id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
"status": "pending",
"type": "passport",
"created": "2015-09-29T21:42:16.000Z"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
document = app_token.get document_url
document.type # => "passport"
<?php
$documentUrl = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';
$documentsApi = new DwollaSwagger\DocumentsApi($apiClient);
$document = $documentsApi->getDocument($documentUrl);
$document->type; # => "passport"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
document_url = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc'
documents = app_token.get(document_url)
documents.body['type'] # => 'passport'
var documentUrl = 'https://api-sandbox.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc';
appToken
.get(document_url)
.then(res => res.body.type); // => "passport"
Add and retrieve ACH bank account information via funding sources. Customers can have a maximum of 6 funding sources. Funding sources can be created for both the Accounts and Customers resources.
| Link | Description |
|---|---|
| self | URL of the funding source resource. |
| customer | GET this link to retrieve details of the Customer. |
| remove | POST to this link to remove the funding source from the Customer. |
| balance | (Verified Customer only) GET this link to retrieve the amount available in the balance of the Customer’s Balance funding source. |
| transfer-from-balance | (Verified Customer only) if this link exists, the Customer can transfer funds from their balance. |
| transfer-to-balance | (Verified Customer only) if this link exists, funds can be transferred to the Customer’s balance. |
| transfer-send | If this link exists, the Customer can send funds to another Customer. |
| transfer-receive | The Customer can receive funds from another Customer. |
| initiate-micro-deposits | POST to this link to initiate micro-deposits on an unverified funding source. |
| verify-micro-deposits | Micro-deposits have completed to this funding source and are eligible for verification. POST to this link with the verify micro-deposit amounts and complete bank funding source verification. |
| failed-verification-micro-deposits | Micro-deposits attempts have failed due to too many failed attempts. Remove the bank and re-add to attempt verification again. |
| Parameter | Description |
|---|---|
| id | The funding source unique identifier. |
| status | Possible values are unverified or verified. Determines if the funding source has completed verification. |
| type | Type of funding source. Possible values are bank or balance. |
| bankAccountType | An optional attribute for bank funding sources that determines the type of account. Possible values are checking or savings. |
| name | Arbitrary nickname for the funding source. |
| created | ISO-8601 timestamp for when the funding source was created. |
| balance | An optional object that includes value and currency parameters. value is a string value for the amount available and currency is a string value currency code. Only returned for a Dwolla API Customer account balance. |
| removed | Determines if the funding source has been removed. A boolean true if the funding source was removed or false if the funding source is not removed. |
| channels | List of processing channels. ACH is the default processing channel for bank transfers. Possible values are ach or wire. |
| bankName | The financial institution name. |
| iavAccountHolders | An optional object that includes optional selected and other parameters. selected, a string with the account holder name(s) on file with the financial institution for the IAV selected account. other, a list of strings with name(s) of other accounts on file. Only returned for a Customer that added a bank using Dwolla IAV, and if names are returned for the selected bank account. |
| fingerprint | Fingerprint is an optional unique identifying string value returned for funding sources of type bank. This attribute can be used to check across all Dwolla API Customers if two bank accounts share the same account number and routing number. Removing a funding source does not remove the fingerprint. |
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/fc84223a-609f-42c9-866e-2c98f17ab4fb",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/241ec287-8d7a-4b69-911e-ffbea98d75ce",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
}
},
"id": "fc84223a-609f-42c9-866e-2c98f17ab4fb",
"status": "verified",
"type": "bank",
"bankAccountType": "checking",
"name": "Your Account #1 - CHECKING",
"created": "2017-08-16T20:06:34.000Z",
"removed": false,
"channels": [
"ach"
],
"bankName": "SANDBOX TEST BANK",
"iavAccountHolders": {
"selected": "account holder",
"other": [
"Jane Doe",
"GeneriCompany LLC"
]
},
"fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
}
There are two methods available for adding a bank or credit union account to a Customer. You can either collect the Customer’s bank account information and pass it to Dwolla via the new Customer funding source endpoint, or you can send the Customer through the the Instant Account Verification (IAV) flow which will add and verify a bank account within seconds.
Before a Dwolla account or Dwolla API Customer is eligible to transfer money from their bank or credit union account they need to verify ownership of the account, either via Instant Account Verification (IAV) or micro-deposits. For more information on bank account verification, reference this funding source verification resource article.
Customers can have a maximum of 6 funding sources.
POST https://api.dwolla.com/customers/{id}/funding-sources
| Parameter | Required | Type | Description |
|---|---|---|---|
| _links | no | object | A _links JSON object containing an on-demand-authorization link relation. See example raw request and response below. |
| routingNumber | yes | string | The bank account’s routing number. |
| accountNumber | yes | string | The bank account number. |
| bankAccountType | yes | string | Type of bank account: checking or savings. |
| name | yes | string | Arbitrary nickname for the funding source. Must be 50 characters or less. |
| plaidToken | no | string | A processor token obtained from Plaid for adding and verifying a bank. Reference our Plaid Link Developer Resource Article to learn more about this integration. |
| channels | no | array | An array containing a list of processing channels. ACH is the default processing channel for bank transfers. Acceptable value for channels is: “wire”. e.g. “channels”: [ “wire” ]. A funding source (Bank Account) added using the wire channel only supports a funds transfer going to the bank account from a balance. As a result, wire as a destination funding source can only be added where the Customer account type is a Verified Customer. Note: channels is a premium feature that must be enabled on your account and is only available to select Dwolla customers. |
| HTTP Status | 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. |
POST https://api-sandbox.dwolla.com/customers/99bfb139-eadd-4cdf-b346-7504f0c16c60/funding-sources
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"routingNumber": "222222226",
"accountNumber": "123456789",
"bankAccountType": "checking",
"name": "Jane Doe’s Checking"
}
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C
<?php
$fundingApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSource = $fundingApi->createCustomerFundingSource([
"routingNumber" => "222222226",
"accountNumber" => "123456789",
"bankAccountType" => "checking",
"name" => "Jane Doe’s Checking"
], "https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C");
$fundingSource; # => "https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
routingNumber: '222222226',
accountNumber: '123456789',
bankAccountType: 'checking',
name: 'Jane Doe’s Checking'
}
funding_source = app_token.post "#{customer_url}/funding-sources", request_body
funding_source.response_headers[:location] # => "https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
'routingNumber': '222222226',
'accountNumber': '123456789',
'bankAccountType': 'checking',
'name': 'Jane Doe’s Checking'
}
customer = app_token.post('%s/funding-sources' % customer_url, request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C';
var requestBody = {
'routingNumber': '222222226',
'accountNumber': '123456789',
'bankAccountType': 'checking',
'name': 'Jane Doe’s Checking'
};
appToken
.post(`${customerUrl}/funding-sources`, requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31'
Dwolla.js is a client-side library that allows you add a funding source for your Customer without having any sensitive data hit your server. This section details how to create a token that will be sent to the client and used to authenticate the HTTP request asking Dwolla to add a new funding source.
Refer to our Dwolla.js developer resource article to learn more on how to utilize this single-use funding-sources-token to add funding source for a Customer.
POST https://api.dwolla.com/customers/{id}/funding-sources-token
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
| HTTP Status | Message |
|---|---|
| 404 | Customer not found. |
POST https://api-sandbox.dwolla.com/customers/99bfb139-eadd-4cdf-b346-7504f0c16c60/funding-sources-token
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
HTTP/1.1 200 OK
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources-token"
}
},
"token": "4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'
fs_token = app_token.post "#{customer_url}/funding-sources-token"
fs_token.token # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var customerUrl = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6';
appToken
.post(`${customerUrl}/funding-sources-token`)
.then(res => res.body.token); // => 'lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'http://api.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'
app_token.post('%s/funding-sources-token' % customer_url)
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$fsToken = $customersApi->createFundingSourcesTokenForCustomer("https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6");
$fsToken->token; # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
?>
Dwolla.js is a client-side library that allows you add and verify a funding source for your Customer without having any sensitive data hit your server. This section details how to create a token that will be sent to the client and used to authenticate the HTTP request asking Dwolla to add and verify a new funding source.
Refer to our Dwolla.js developer resource article to learn more on how to utilize this single-use iav-token to add and verify a funding source for a Customer.
POST https://api.dwolla.com/customers/{id}/iav-token
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier. |
| HTTP Status | Message |
|---|---|
| 404 | Customer not found. |
POST https://api-sandbox.dwolla.com/customers/99bfb139-eadd-4cdf-b346-7504f0c16c60/iav-token
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
HTTP/1.1 200 OK
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/iav-token"
}
},
"token": "4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'
customer = app_token.post "#{customer_url}/iav-token"
customer.token # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var customerUrl = 'https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6';
appToken
.post(`${customerUrl}/iav-token`)
.then(res => res.body.token); // => 'lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'http://api.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6'
app_token.post('%s/iav-token' % customer_url)
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$iavToken = $customersApi->getCustomerIavToken("https://api-sandbox.dwolla.com/customers/06b51d56-7a6c-4535-a0cc-2c0106f56ba6");
$iavToken->token; # => "lr0Ax1zwIpeXXt8sJDiVXjPbwEeGO6QKFWBIaKvnFG0Sm2j7vL"
?>
This section covers how to retrieve a funding source by id.
GET https://api.dwolla.com/funding-sources/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of funding source to retrieve. |
| HTTP Status | Message |
|---|---|
| 404 | Funding source not found. |
GET https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/4594a375-ca4c-4220-a36a-fa7ce556449d",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"initiate-micro-deposits": {
"href": "https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31/micro-deposits",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "micro-deposits"
}
},
"id": "49dbaa24-1580-4b1c-8b58-24e26656fa31",
"status": "unverified",
"type": "bank",
"bankAccountType": "checking",
"name": "Test checking account",
"created": "2017-09-26T14:14:08.000Z",
"removed": false,
"channels": [
"ach"
],
"bankName": "SANDBOX TEST BANK",
"fingerprint": "5012989b55af15400e8102f95d2ec5e7ce3aef45c01613280d80a236dd8d6c3a"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31'
funding_source = app_token.get funding_source_url
funding_source.name # => "Test checking account"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSource = $fsApi->id($fundingSourceUrl);
$fundingSource->name; # => "Test checking account"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31'
funding_source = app_token.get(funding_source_url)
funding_source.body['name'] # => 'Test checking account'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/49dbaa24-1580-4b1c-8b58-24e26656fa31';
appToken
.get(fundingSourceUrl)
.then(res => res.body.name); // => "Test checking account"
Retrieve a list of funding sources that belong to a Customer. By default, all funding sources are returned unless the removed query string parameter is set to false in the request.
GET https://api.dwolla.com/customers/{id}/funding-sources
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer’s unique identifier. |
| removed | no | string | Filter removed funding sources. Defaults to true. Set to false to filter out removed funding sources from list (i.e. - /customers/{id}/funding-sources?removed=false). |
| HTTP Status | Message |
|---|---|
| 403 | Not authorized to list funding sources. |
| 404 | Customer not found. |
GET https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
}
},
"_embedded": {
"funding-sources": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
},
"with-available-balance": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
}
},
"id": "ab9cd5de-9435-47af-96fb-8d2fa5db51e8",
"status": "verified",
"type": "balance",
"name": "Balance",
"created": "2015-10-02T21:00:28.153Z",
"removed": false,
"channels": []
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/98c209d3-02d6-4bee-bc0f-61e18acf0e33"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
}
},
"id": "98c209d3-02d6-4bee-bc0f-61e18acf0e33",
"status": "verified",
"type": "bank",
"bankAccountType": "checking",
"name": "Jane Doe’s Checking",
"created": "2015-10-02T22:03:45.537Z",
"removed": false,
"channels": [
"ach"
],
"fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
}
]
}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'
funding_sources = app_token.get "#{customer_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe’s Checking"
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSources = $fsApi->getCustomerFundingSources($customerUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Jane Doe’s Checking"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'
funding_sources = app_token.get('%s/funding-sources' % customer_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Jane Doe’s Checking'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';
appToken
.get(`${customerUrl}/funding-sources`)
.then(res => res.body._embedded['funding-sources'][0].name); // => 'Jane Doe’s Checking'
This section covers how to update a bank funding source. The accountNumber, routingNumber, type and name are all optional attributes that can be updated on a funding source when it has an unverified status. You can choose to update only name, name and routingNumber, name and accountNumber, name and type or all four attributes. Any attribute that isn’t updated remains the same as it was prior to update, including the funding source id. The name attribute can be updated when a funding source has either an unverified or verified status.
POST https://api.dwolla.com/funding-sources/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of funding source to update. |
| name | no | string | Arbitrary nickname for the funding source. Must be 50 characters or less. |
| bankAccountType | no | string | Type of bank account: checking or savings. |
| routingNumber | no | string | The bank account’s routing number. |
| accountNumber | no | string | The bank account number. |
| HTTP Status | 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. |
POST https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"name": "Test Checking - 1234"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
"name" => "Test Checking - 1234",
}
funding_source = app_token.post "#{funding_source_url}", request_body
funding_source.name # => "Test Checking - 1234"
/**
* No example for this language yet. Coming soon.
**/
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
'name': 'Test Checking - 1234'
}
funding_source = app_token.post(funding_source_url, request_body)
funding_source.body['name'] # => 'Test Checking - 1234'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
name: "Test Checking - 1234"
};
appToken
.post(fundingSourceUrl, requestBody)
.then(res => res.body.name); // => "Test Checking - 1234"
This section covers how to initiate micro-deposits for bank verification. Reference the funding source verification resource article for more information on the micro-deposit method of bank account verification.
POST https://api.dwolla.com/funding-sources/{id}/micro-deposits
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of funding source to initiate micro-deposits to. |
| HTTP Status | Code | Description |
|---|---|---|
| 201 | Created | Micro-deposits initiated, will take 1-2 days to settle to destination bank. |
| 404 | NotFound | Funding source not found |
POST https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
Authorization: Bearer 8tJjM7iTjujLthkbVPMUcHLqMNw4uv5kG712g9j1RRBHplGpwo
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
app_token.post "#{funding_source_url}/micro-deposits"
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
appToken.post(`${fundingSourceUrl}/micro-deposits`);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
app_token.post('%s/micro-deposits' % funding_source_url)
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fsApi->microDeposits(null, $fundingSourceUrl);
?>
This section covers how to verify micro-deposits for bank verification. Reference the funding source verification resource article for more information on the micro-deposit method of bank account verification.
POST https://api.dwolla.com/funding-sources/{id}/micro-deposits
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of funding source to verify micro-deposits on. |
| amount1 | yes | string | An amount JSON object of first micro-deposit. Contains value and currency. |
| amount2 | yes | string | An amount JSON object of second micro-deposit. Contains value and currency. |
| HTTP Status | Code | Description |
|---|---|---|
| 200 | OK | Micro-deposits successfully verified. |
| 202 | TryAgainLater | Micro-deposits have not have not settled to destination bank. A Customer can verify these amounts after micro-deposits have processed to their bank. |
| 400 | ValidationError | InvalidAmount, “Wrong amount(s).” |
| 403 | InvalidResourceState | “Too many attempts.”, “Bank already verified.” |
| 404 | NotFound | Micro-deposits not initiated,Funding source not found |
| 500 | Unknown | “Verify micro-deposits returned an unknown error.” |
POST https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909/micro-deposits
Authorization: Bearer 8tJjM7iTjujLthkbVPMUcHLqMNw4uv5kG712g9j1RRBHplGpwo
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
{
"amount1": {
"value": "0.03",
"currency": "USD"
},
"amount2": {
"value": "0.09",
"currency": "USD"
}
}
HTTP 200 OK
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
:amount1 => {
:value => "0.03",
:currency => "USD"
},
:amount2 => {
:value => "0.09",
:currency => "USD"
}
}
app_token.post "#{funding_source_url}/micro-deposits", request_body
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
var requestBody = {
amount1: {
value: '0.03',
currency: 'USD'
},
amount2: {
value: '0.09',
currency: 'USD'
}
};
appToken.post(`${fundingSourceUrl}/micro-deposits`, requestBody);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909'
request_body = {
'amount1': {
'value': '0.03',
'currency': 'USD'
},
'amount2': {
'value': '0.09',
'currency': 'USD'
}
}
app_token.post('%s/micro-deposits' % funding_source_url, request_body)
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e52006c3-7560-4ff1-99d5-b0f3a6f4f909';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fsApi->microDeposits([
'amount1' => [
'value' => '0.03',
'currency' => 'USD'
],
'amount2' => [
'value' => '0.09',
'currency' => 'USD'
]],
$fundingSourceUrl
);
?>
This section covers how to retrieve the balance of a funding source. The funding source type balance only exists for Verified Customer accounts and represents a balance held in the Dwolla network.
GET https://api.dwolla.com/funding-sources/{id}/balance
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of funding source to retrieve a balance for. |
| HTTP Status | Code | Description |
|---|---|---|
| 404 | NotFound | Funding source not found. |
GET https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418/balance
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418/balance",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "balance"
},
"funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
}
},
"balance": {
"value": "4616.87",
"currency": "USD"
},
"lastUpdated": "2017-04-18T15:20:25.880Z"
}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418'
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source = app_token.get "#{funding_source_url}/balance"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSource = $fsApi->getBalance($fundingSourceUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418'
funding_source = app_token.get('%s/balance' % funding_source_url)
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418';
appToken
.get(`${fundingSourceUrl}/balance`)
.then(res => res.body.balance.amount);
This section shows how to retrieve the status of micro-deposits and check if micro-deposits are eligible for verification. If the status of micro-deposits is failed, a failure object will be returned in the response body which includes the ACH return code and description.
GET https://api.dwolla.com/funding-sources/{id}/micro-deposits
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | no | string | id of funding source to check status of validation deposits. |
| Attribute | Description |
|---|---|
| _links | A _links JSON object |
| created | ISO-8601 timestamp |
| status | Possible values: pending, processed, or failed. pending represents micro-deposits initiated and are en route to their destination. processed represents micro-deposits have reached the destination account and are awaiting verification. failed represents micro-deposits failed to clear successfully to the destination. |
| failure | Determines if micro-deposits fail to complete to a bank. Failure is an object that contains a code and description, which represents the ACH return code and description of the return. |
| HTTP Status | Code | Description |
|---|---|---|
| 200 | Ok | Pending micro-deposits exist. |
GET https://api-sandbox.dwolla.com/funding-sources/dfe59fdd-7467-44cf-a339-2020dab5e98a/micro-deposits
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/dfe59fdd-7467-44cf-a339-2020dab5e98a/micro-deposits",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "micro-deposits"
},
"verify-micro-deposits": {
"href": "https://api-sandbox.dwolla.com/funding-sources/dfe59fdd-7467-44cf-a339-2020dab5e98a/micro-deposits",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "micro-deposits"
}
},
"created": "2016-12-30T20:56:53.000Z",
"status": "failed",
"failure": {
"code": "R03",
"description": "No Account/Unable to Locate Account"
}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
funding_source = app_token.get "#{funding_source_url}/micro-deposits"
funding_source.status # => "failed"
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fundingSource = $fsApi->verifyMicroDepositsExist($fundingSourceUrl);
$fundingSource->status; # => "failed"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
funding_source = app_token.get('%s/micro-deposits' % funding_source_url)
funding_source.body['status'] # => 'failed'
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
appToken
.get(`${fundingSourceUrl}/micro-deposits`)
.then(res => res.body.status); // => "failed"
Remove a funding source by id. A removed funding source is soft deleted and can still be accessed when retrieved.
POST https://api.dwolla.com/funding-sources/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of funding source to delete. |
| removed | yes | string | Specify a value of true to remove the associated funding source. |
| HTTP Status | Message |
|---|---|
| 404 | Funding source not found. |
POST https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"removed": true
}
...
HTTP 200 OK
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c",
"type": "funding-source"
}
},
"id": "692486f8-29f6-4516-a6a5-c69fd2ce854c",
"status": "verified",
"type": "bank",
"bankAccountType": "checking",
"name": "Test bank account",
"created": "2016-06-08T21:37:30.000Z",
"removed": true,
"fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
:removed => true
}
app_token.post "#{funding_source_url}", request_body
<?php
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);
$fsApi->softDelete(['removed' => true ], $fundingSourceUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
'removed': True
}
funding_source = app_token.post(funding_source_url, request_body)
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
removed: true
};
appToken.post(fundingSourceUrl, requestBody);
A transfer represents money being transferred from a source to a destination. Transfers are available for the Customer and Account resources.
| Link | Description |
|---|---|
| self | URL of the transfer. |
| source | GET this link to retrieve the Customer that was the source of the transfer. |
| destination | GET this link to retrieve the Customer that was the destination of the transfer. |
| source-funding-source | GET this link to retrieve the funding source that was the source of the transfer. |
| destination-funding-source | GET this link to retrieve the funding source that was the destination of the transfer. |
| cancel | POST to this link to cancel the transfer (A bank transfer is cancellable up until 4pm CT on that same business day if the transfer was initiated prior to 4PM CT. If a transfer was initiated after 4pm CT, it can be cancelled anytime before 4pm CT on the following business day.) |
| fees | GET this link to retrieve the facilitator fees associated with the transfer. |
| Parameter | Description |
|---|---|
| id | Transfer unique identifier. |
| status | Either processed, pending, cancelled, or failed. |
| amount | An amount JSON object. See below. |
| created | ISO-8601 timestamp. |
| metadata | A metadata JSON object |
| clearing | A clearing JSON object. |
| achDetails | An achDetails JSON object. See below. |
| correlationId | A unique string value attached to a transfer resource which can be used for traceability between Dwolla and your application. |
| individualAchId | A unique string value matching the value on bank line related to the transfer. Appears when the debit entry clears out of the bank. The individual identifier for that ACH entry. |
| Parameter | Description |
|---|---|
| value | Amount of money |
| currency | USD |
Can be used to upgrade or downgrade the clearing time from the default ACH processing.
| Parameter | Description |
|---|---|
| source | Represents a clearing object for next-day debits into the Dwolla network. |
| destination | Represents a clearing object for same-day credits out of the Dwolla network to a bank funding source. |
| Parameter | Description |
|---|---|
| addenda | A string value passed on a transfer request and can be exposed on a Customer’s bank statement. |
| traceId | A unique string value that identifies a transaction from the source funding source to the destination funding source. This value is often used to determine where a transaction’s funds lie at a certain time. |
{
"_links": {},
"_embedded": {},
"id": "string",
"status": "string",
"amount": {
"value": "string",
"currency": "string"
},
"created": "string",
"metadata": {
"key": "value"
},
"clearing": {
"source": "standard",
"destination": "next-available"
},
"achDetails": {
"source": {
"addenda": {
"values": [
"string"
]
},
"traceId": "string"
},
"destination": {
"addenda": {
"values": [
"string"
]
},
"traceId": "string"
}
},
"correlationId": "string",
"individualAchId": "string"
}
This section covers how to initiate a transfer from either a Dwolla Account or Dwolla API Customer resource.
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 ensure that only a single transfer is created.
Refer to our idempotency key section to learn more.
POST https://api.dwolla.com/transfers
| Parameter | Required | Type | Description |
|---|---|---|---|
| _links | yes | object | A _links JSON object describing the desired source and destination of a transfer. Reference the Source and Destination object to learn more about possible values for source and destination. |
| amount | yes | object | An amount JSON object. Reference the amount JSON object to learn more. |
| metadata | no | object | A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters). |
| fees | no | array | An array of fee JSON objects that contain unique fee transfers. Reference the facilitator fee JSON object to learn more. |
| clearing | no | object | A clearing JSON object that contains source and destination keys to expedite or slow down a transfer. Reference the clearing JSON object to learn more. |
| achDetails | no | object | An ACH details JSON object which represents additional information sent along with a transfer to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. Reference the achDetails JSON object to learn more |
| correlationId | no | string | A unique string value attached to a transfer which can be used for traceability between Dwolla and your application. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _. |
| Source Type | URI | Description |
|---|---|---|
| Funding source | https://api.dwolla.com/funding-sources/{id} |
A bank or balance funding source. |
| Destination Type | URI | Description |
|---|---|---|
| Funding source | https://api.dwolla.com/funding-sources/{id} |
Destination of an Account or verified Customer’s own bank or balance funding source. OR A Customer’s bank funding source. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| value | yes | string | Amount of money |
| currency | yes | string | Possible values: USD |
The facilitator fee is a feature allowing for a flat rate amount to be removed from a payment as a fee, and sent to the creator of the Dwolla application. The fee does not affect the original payment amount, and exists as a separate Transfer resource with a unique transfer ID. Within a transfer request you can specify an optional fees request parameter, which is an array of fee objects that can represent many unique fee transfers.
For more information on collecting fees on payments, reference the facilitator fee resource article.
| Parameter | Description |
|---|---|
| _links | Contains a charge-to JSON object with a link to the associated source or destination Customer or Account resource. |
| amount | Amount of fee to charge. An amount JSON object. See above |
"fees": [
{
"_links": {
"charge-to": {
"href": "https://api-sandbox.dwolla.com/customers/d795f696-2cac-4662-8f16-95f1db9bddd8"
}
},
"amount": {
"value": "4.00",
"currency": "USD"
}
}
]
The clearing object is used in tandem with our expedited transfer feature.
Source specifies the clearing time for the source funding source involved in the transfer, and can be used to downgrade the clearing time from the default of Next-day ACH. Destination specifies the clearing time for the destination funding source involved in the transfer, and can be used to upgrade the clearing time from the default of Standard ACH to Same-day ACH. Note: The clearing request parameter is a premium feature available for Dwolla customers. Next-day ACH functionality must be enabled.
| Parameter | Required | Type | Description |
|---|---|---|---|
| source | no | string | Represents a clearing object for next-day debits into the Dwolla network. Possible values: standard |
| destination | no | string | Represents a clearing object for same-day credits out of the Dwolla network to a bank funding source. Possible values: next-available |
"clearing": {
"source": "standard",
"destination": "next-available"
}
Note: This feature is only supported for business Customer records.
The addendum record is used to provide additional information to the payment recipient about the payment. This value will be passed in on a transfer request and can be exposed on a Customer’s bank statement. Addenda records provide a unique opportunity to supply your customers with more information about their transactions. Allowing businesses to include additional details about the transaction—such as invoice numbers—provides their end users with more information about the transaction in the comfort of their own banking application.
| Parameter | Required | Type | Description |
|---|---|---|---|
| source | no | object | Represents information that is sent to a source/originating bank account along with a transfer. Include information within this JSON object for customizing details on ACH debit transfers. Can include an addenda JSON object. |
| destination | no | object | Represents information that is sent to a destination/receiving bank account along with a transfer. Include information within this JSON object for customizing details on ACH credit transfers. Can include an addenda JSON object. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| addenda | no | object | An addenda object contains a values key which is an array of comma separated string addenda values. Addenda record information is used for the purpose of transmitting transfer-related information from a business. Values must be less than or equal to 80 characters and can include spaces. Acceptable characters are: a-Z, 0-9, and special characters - _ . ~ ! * ' ( ) ; : @ & = + $ , / ? % # [ ]. Transfers must be sent to/from a business entity’s bank to guarantee addenda delivery. |
"achDetails": {
"source": {
"addenda": {
"values": ["ABC123_AddendaValue"]
}
},
"destination": {
"addenda": {
"values": ["ZYX987_AddendaValue"]
}
}
}
| HTTP Status | Error Message | Description |
|---|---|---|
| 201 | Created. | A transfer was created. |
| 400 | Funding source not found. | Double check the funding source Id, and make sure you are using the correct funding source Id. |
| 400 | Invalid funding source. | The source funding source must be verified in order to send funds. Make sure your source funding source is verified. |
| 400 | Metadata not supported for this type of transfer. | Metadata is unable to be passed in on transfers with a Balance Funding Source. |
| 400 | Sender // Receiver Restricted. | The source or destination Customer is either deactivated or suspended and not eligible for transfers. |
| 401 | Invalid access token | Access token not valid. Generate a new one and try again. |
| 403 | Forbidden | Not authorized to create a transfer. |
The reference example below shows what a request looks like when sending a transfer. Please note this example is using same-day clearing to a Dwolla API Customer’s bank account, part of Dwolla’s API.
POST https://api-sandbox.dwolla.com/transfers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77
{
"_links": {
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C"
}
},
"amount": {
"currency": "USD",
"value": "10.00"
},
"metadata": {
"paymentId": "12345678",
"note": "payment for completed work Dec. 1"
},
"fees": [
{
"_links":{
"charge-to":{
"href":"https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4"
}
},
"amount":{
"value":"2.00",
"currency":"USD"
}
}
],
"clearing": {
"destination": "next-available"
},
"achDetails": {
"source": {
"addenda": {
"values": ["ABC123_AddendaValue"]
}
},
"destination": {
"addenda": {
"values": ["ZYX987_AddendaValue"]
}
}
},
"correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
...
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:_links => {
:source => {
:href => "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
:destination => {
:href => "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C"
}
},
:amount => {
:currency => "USD",
:value => "1.00"
},
:metadata => {
:paymentId => "12345678",
:note => "payment for completed work Dec. 1"
},
:clearing => {
:destination => "next-available"
},
:achDetails => {
:source => {
:addenda => {
:values => ["ABC123_AddendaValues"]
}
},
:destination => {
:addenda => {
:values => ["ZYX987_AddendaValues"]
}
}
},
:correlationId => "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
transfer = app_token.post "transfers", request_body
transfer.response_headers[:location] # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
<?php
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transfer = $transfersApi->create([
'_links' => [
'source' => [
'href' => 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4',
],
'destination' => [
'href' => 'https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C'
]
],
'amount' => [
'currency' => 'USD',
'value' => '1.00'
],
'metadata' => [
'paymentId' => '12345678',
'note' => 'payment for completed work Dec. 1',
],
'clearing' => [
'destination' => 'next-available'
],
'correlationId' => '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
]);
$transfer; # => "https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'_links': {
'source': {
'href': 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
},
'destination': {
'href': 'https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C'
}
},
'amount': {
'currency': 'USD',
'value': '1.00'
},
'metadata': {
'paymentId': '12345678',
'note': 'payment for completed work Dec. 1'
},
'clearing': {
'destination': 'next-available'
},
'achDetails': {
'source': {
'addenda': {
'values': ['ABC123_AddendaValues']
}
},
'destination': {
'addenda': {
'values': ['ZYX987_AddendaValues']
}
}
},
'correlationId': '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
}
transfer = app_token.post('transfers', request_body)
transfer.headers['location'] # => 'https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'
var requestBody = {
_links: {
source: {
href: 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
},
destination: {
href: 'https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C'
}
},
amount: {
currency: 'USD',
value: '1.00'
},
metadata: {
paymentId: '12345678',
note: 'payment for completed work Dec. 1'
},
clearing: {
destination: 'next-available'
},
addenda: {
source: {
addenda: {
values: ['ABC123_AddendaValue']
}
},
destination: {
addenda: {
values: ['ZYX987_AddendaValue']
}
}
},
correlationId: '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
};
appToken
.post('transfers', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'
This section covers how to retrieve a transfer belonging to an Account or Customer by its id.
GET https://api.dwolla.com/transfers/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | The id of the transfer to be retrieved. |
| HTTP Status | Message |
|---|---|
| 404 | Transfer not found. |
GET https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"cancel": {
"href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"source": {
"href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
},
"source-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/12a0eaf9-9561-468d-bdeb-186b536aa2ed",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"funding-transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/customers/d295106b-ca20-41ad-9774-286e34fd3c2d",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"destination-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/500f8e0e-dfd5-431b-83e0-cd6632e63fcb",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
}
},
"id": "15c6bcce-46f7-e811-8112-e8dd3bececa8",
"status": "pending",
"amount": {
"value": "42.00",
"currency": "USD"
},
"created": "2018-12-03T22:00:22.970Z",
"clearing": {
"source": "standard"
}
},
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8'
transfer = app_token.get transfer_url
transfer.status # => "pending"
<?php
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8';
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transfer = $transfersApi->byId($transferUrl);
$transfer->status; # => "pending"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8'
transfer = account_token.get(transfer_url)
transfer.body['status'] # => 'pending'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8';
appToken
.get(transferUrl)
.then(res => res.body.status); // => 'pending'
This section details how to retrieve a Customer’s list of transfers. Transaction search is supported by passing in optional querystring parameters such as: search which represents a term to search on, correlationId, startAmount, endAmount, startDate, endDate, and status.
GET https://api.dwolla.com/customers/{id}/transfers
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier to get transfers for. |
| search | no | string | A string to be matched with firstName, lastName, email, businessName, Customer Id, and Account Id. (/transfers?search=Doe) |
| startAmount | no | string | Only include transactions with an amount equal to or greater than startAmount. Can optionally be used with endAmount to specify an amount range. |
| endAmount | no | string | Only include transactions with an amount equal to or less than endAmount. Can optionally be used with startAmount to specify an amount range. |
| startDate | no | string | Only include transactions created after this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with endDate to specify a date range. |
| endDate | no | string | Only include transactions created before than this date. ISO-8601 format: YYYY-MM-DD. Can optionally be used with startDate to specify a date range. |
| status | no | string | Filter results on transaction status. Possible values: pending, processed, failed, or cancelled. |
| correlationId | no | string | A string value to search on if a correlationId was specified on a transfer or mass payment item. |
| limit | no | integer | Number of search results to return. Defaults to 25. |
| offset | no | integer | Number of search results to skip. Used for pagination. |
| HTTP Status | Message |
|---|---|
| 403 | Not authorized to list transfers. |
| 404 | Customer not found. |
GET https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers"
},
"first": {
"href": "https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers?&limit=25&offset=0"
},
"last": {
"href": "https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers?&limit=25&offset=0"
}
},
"_embedded": {
"transfers": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/61cbc6db-19f4-e811-8112-e8dd3bececa8"
},
"source": {
"href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d"
},
"source-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/73ce02cb-8857-4f01-83fc-b6640b24f9f7"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295"
},
"destination-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ac6d4c2a-fda8-49f6-805d-468066dd474c"
},
},
"id": "461cbc6db-19f4-e811-8112-e8dd3bececa8",
"status": "pending",
"amount": {
"value": "225.00",
"currency": "USD"
},
"created": "2018-11-29 21:00:59 UTC",
"metadata": {
"foo": "bar",
"baz": "foo"
}
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/76e5541d-18f4-e811-8112-e8dd3bececa8"
},
"source": {
"href": "https://api-sandbox.dwolla.com/customers/0e309d41-a5df-4105-97da-2c6739e71a67"
},
"source-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/73ce02cb-8857-4f01-83fc-b6640b24f9f7"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295"
},
"destination-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ac6d4c2a-fda8-49f6-805d-468066dd474c"
}
},
"id": "76e5541d-18f4-e811-8112-e8dd3bececa8",
"status": "pending",
"amount": {
"value": "225.00",
"currency": "USD"
},
"created": "2015-10-02T19:40:41.437Z",
"metadata": {
"foo": "bar",
"baz": "foo"
}
}
]
},
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'http://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295'
transfers = app_token.get "#{customer_url}/transfers"
transfers._embedded['transfers'][0].status # => "pending"
<?php
$customerUrl = 'http://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295';
$TransfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transfers = $TransfersApi->getCustomerTransfers($customerUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "pending"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'http://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295'
transfers = app_token.get('%s/transfers' % customer_url)
transfers.body['_embedded']['transfers'][0]['status'] # => 'pending'
var customerUrl = 'http://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295';
appToken
.get(`${customerUrl}/transfers`)
.then(res => res.body._embedded['transfers'][0].status); // => "pending"
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.
GET https://api.dwolla.com/transfers/{id}/fees
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | The id of the transfer to retrieve fees for. |
| HTTP Status | Message |
|---|---|
| 404 | Transfer not found. |
GET https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388/fees
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"transactions": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/416a2857-c887-4cca-bd02-8c3f75c4bb0e"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
"created-from-transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388"
}
},
"id": "416a2857-c887-4cca-bd02-8c3f75c4bb0e",
"status": "pending",
"amount": {
"value": "2.00",
"currency": "usd"
},
"created": "2016-02-22T20:46:38.777Z"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/e58ae1f1-7007-47d3-a308-7e9aa6266d53"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ac6d4c2a-fda8-49f6-805d-468066dd474c"
},
"created-from-transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388"
}
},
"id": "e58ae1f1-7007-47d3-a308-7e9aa6266d53",
"status": "pending",
"amount": {
"value": "1.00",
"currency": "usd"
},
"created": "2016-02-22T20:46:38.860Z"
}
],
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'
fees = app_token.get "#{transfer_url}/fees"
fees.total # => 2
<?php
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transferFees = $transfersApi->getFeesBySource($transferUrl);
$transferFees->total; # => "2"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'
fees = app_token.get('%s/fees' % transfer_url)
fees.body['total'] # => 2
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';
appToken
.get(`${transferUrl}/fees`)
.then(res => res.body.total); // => 2
When a bank transfer fails for an Account or Customer, Dwolla returns a failure link when retrieving the transfer by its Id. This failure link is used to retrieve the ACH return code and description. For reference, the list of possible failure codes and descriptions are shown in the Transfer failures resource article.
Note: If a transfer fails to/from a bank account then the bank will automatically be removed from the Dwolla system for all ACH return codes except an R01.
GET https://api.dwolla.com/transfers/{id}/failure
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Transfer unique identifier. |
GET https://api-sandbox.dwolla.com/transfers/e6d9a950-ac9e-e511-80dc-0aa34a9b2388/failure
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/E6D9A950-AC9E-E511-80DC-0AA34A9B2388/failure"
}
},
"code": "R01",
"description": "Insufficient Funds"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'
failure = app_token.get "#{transfer_url}/failure"
failure.code # => "R01"
<?php
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transferFailure = $transfersApi->failureById($transferUrl);
$transferFailure->code; # => "R01"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388'
failure = app_token.get('%s/failure' % transfer_url)
failure.body['code'] # => 'R01'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/83eb4b5e-a5d9-e511-80de-0aa34a9b2388';
appToken
.get(`${transferUrl}/failure`)
.then(res => res.body.code); // => 'R01'
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.
POST https://api.dwolla.com/transfers/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| status | yes | string | Possible value: cancelled. |
POST https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"status": "cancelled"
}
...
{
"_links": {
"cancel": {
"href": "https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"self": {
"href": "https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"source": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
},
"source-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/73ce02cb-8857-4f01-83fc-b6640b24f9f7",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"funding-transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/3c48c13a-0fc6-e511-80de-0aa34a9b2388",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"destination-funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ac6d4c2a-fda8-49f6-805d-468066dd474c",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
}
},
"id": "3d48c13a-0fc6-e511-80de-0aa34a9b2388",
"status": "cancelled",
"amount": {
"value": "22.00",
"currency": "USD"
},
"created": "2016-01-28T22:34:02.663Z",
"metadata": {
"foo": "bar",
"baz": "boo"
}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
transfer_url = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388'
request_body = {
"status" => "cancelled",
}
transfer = app_token.post "#{transfer_url}", request_body
transfer.status # => "cancelled"
<?php
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);
$transferUrl = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388';
$transfer = $transfersApi->update([
'status' => 'cancelled',
], $transferUrl);
$transfer->status; # => "cancelled"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
transfer_url = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388'
request_body = {
'status': 'cancelled'
}
transfer = app_token.post(transfer_url, request_body)
transfer.body['status'] # => 'cancelled'
var transferUrl = 'https://api-sandbox.dwolla.com/transfers/3d48c13a-0fc6-e511-80de-0aa34a9b2388'
var requestBody = {
status: "cancelled"
};
appToken
.post('transfers', requestBody)
.then(res => res.body.status); // => "cancelled"
This section outlines how to create an on-demand bank transfer authorization for your Customer. On-demand authorization allows Customers to authorize Dwolla to transfer variable amounts from their bank account using ACH at a later point in time for products or services delivered. This on-demand authorization is supplied along with the Customer’s bank details when creating a new Customer funding source.
When on-demand authorization is enabled for your application the Customer is presented with text on a “add bank account” screen in your user interface(UI) giving authorization to Dwolla for future variable payments. Note: On-demand payments come as part of our Dwolla API and requires additional approval before getting started. Please contact Sales for more information on enabling.
POST https://api.dwolla.com/on-demand-authorizations
| HTTP Status | Code | Description |
|---|---|---|
| 403 | Forbidden | The supplied credentials are not authorized for this resource. |
POST https://api-sandbox.dwolla.com/on-demand-authorizations
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/on-demand-authorizations/30e7c028-0bdf-e511-80de-0aa34a9b2388"
}
},
"bodyText": "I agree that future payments to Company ABC inc. will be processed by the Dwolla payment system from the selected account above. In order to cancel this authorization, I will change my payment settings within my Company ABC inc. account.",
"buttonText": "Agree & Continue"
}
on_demand_authorization = app_token.post "on-demand-authorizations"
on_demand_authorization.buttonText # => "Agree & Continue"
<?php
$onDemandApi = new DwollaSwagger\OndemandauthorizationsApi($apiClient);
$onDemandAuth = $onDemandApi->createAuthorization();
$onDemandAuth->_links["self"]->href; # => "https://api-sandbox.dwolla.com/on-demand-authorizations/30e7c028-0bdf-e511-80de-0aa34a9b2388"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
on_demand_authorization = app_token.post('on-demand-authorizations')
on_demand_authorization.body['buttonText'] # => 'Agree & Continue'
appToken
.post('on-demand-authorizations')
.then(res => res.body.buttonText); // => "Agree & Continue"
Dwolla mass payments allows you to easily send up to 5,000 payments one API request. The payments are funded from a single user’s specified funding source and processed asynchronously upon submission.
Dwolla Mass Payments are meant for batches of multiple payments. If you are initiating a single payment to a singular Customer, we recommend using our /transfers endpoint.
Your mass payment will initially be pending and then processed. As the service processes your mass payment, each item is processed one after the other, at a rate between 0.5 sec. - 1 sec. / item. Therefore, you can expect a 1000-item mass payment to be completed between 8-16 minutes.
A mass payment offers a significant advantage over repeatedly calling the Transfers endpoint for each individual transaction. A key benefit is that a bank-funded mass payment only incurs a single ACH debit from the bank account to fund the entire batch of payments. The alternative approach will incur an ACH debit from the bank funding source for each individual payment. Those who used this approach have reported incurring fees from their financial institutions for excessive ACH transactions.
| Parameter | Description |
|---|---|
| id | Mass payment unique identifier. |
| status | Either deferred: A created mass payment that can be processed at a later time. pending: A mass payment that is pending and awaiting processing. A mass payment has a pending status for a brief period of time and cannot be cancelled. processing: A mass payment that is processing. complete: A mass payment successfully completed processing. |
| created | ISO-8601 timestamp. |
| metadata | A metadata JSON object. |
| total | The sum amount of all items in the mass payment. |
| totalFees | The sum amount of all fees charged for the mass payment. |
| correlationId | A unique string value attached to a mass payment resource which can be used for traceability between Dwolla and your application. |
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payments/da835c07-1e12-4212-8b93-a7e0013dfd98",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "mass-payment"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"items": {
"href": "https://api-sandbox.dwolla.com/mass-payments/da835c07-1e12-4212-8b93-a7e0013dfd98/items",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "mass-payment-item"
}
},
"id": "da835c07-1e12-4212-8b93-a7e0013dfd98",
"status": "complete",
"created": "2017-08-31T19:18:02.000Z",
"metadata": {
"batch": "batch1"
},
"total": {
"value": "0.02",
"currency": "USD"
},
"totalFees": {
"value": "0.00",
"currency": "USD"
},
"correlationId": "d028beed-8152-481d-9427-21b6c4d99644"
}
This section covers how to initiate a mass payment from your Dwolla Master Account or Verified Customer resource. A mass payment contains a list of items representing individual payments. Optionally, mass payments can contain metadata and a correlationId on the mass payment itself as well as items contained in the mass payment, which can be used to pass along additional information with the mass payment and item respectively. If a correlationId is included on a mass payment item it will be passed along to the transfer created from the item and can be searched on.
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 mass payment fails due to a network connection issue, you can reattempt the request with the same idempotency key to ensure that only a single mass payment is created.
Refer to our idempotency key section to learn more.
A mass payment can be created with a status of deferred, which allows you to create the mass payment and defer processing to a later time. To trigger processing on a deferred mass payment, you’ll update the mass payment with a status of pending. A deferred mass payment can be cancelled by updating the mass payment with a status of cancelled.
POST https://api.dwolla.com/mass-payments
| Parameter | Required | Type | Description |
|---|---|---|---|
| _links | yes | object | A _links JSON object describing the desired source of a mass payment. Reference the Source and Destination object to learn more about possible values for source and destination. |
| items | yes | array | an array of item JSON objects that contain unique payments. See below |
| metadata | no | object | A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters). |
| status | no | string | Acceptable value is: deferred. |
| achDetails | no | object | An ACH details JSON object which represents additional information sent along with a transfer created from a mass payment item to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. See below |
| correlationId | no | string | A unique string value attached to a mass payment which can be used for traceability between Dwolla and your application. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _. |
| Source Type | URI | Description |
|---|---|---|
| Funding source | https://api.dwolla.com/funding-sources/{id} |
A bank or balance funding source of an Account or verified Customer. |
| Destination Type | URI | Description |
|---|---|---|
| Funding source | https://api.dwolla.com/funding-sources/{id} |
Destination of a Verified Customer’s own bank or balance funding source, an Unverified Customer’s bank funding source, or a Receive-only User’s bank funding source. |
| Parameter | Description |
|---|---|
| _links | A _links JSON object describing the desired destination of a mass payment. See above for possible values for destination. |
| amount | An amount JSON object containing currency and value keys. |
| metadata | A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters). |
| correlationId | A unique string value attached to a mass payment item which can be used for traceability between Dwolla and your application. The correlationId will be passed along to a transfer that is created from an item and can be searched on. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _. |
| achDetails | An ACH details JSON object which represents additional information sent along with a transfer created from a mass payment item to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| value | yes | string | Amount of money |
| currency | yes | string | Possible values: USD |
The addendum record is used to provide additional information to the payment recipient about the payment. This value will be passed in on a transfer request and can be exposed on a customer’s bank statement. Addenda records provide a unique opportunity to supply your customers with more information about their transactions. Allowing businesses to include additional details about the transaction—such as invoice numbers—provides their end users with more information about the transaction in the comfort of their own banking application.
| Parameter | Required | Type | Description |
|---|---|---|---|
| source | no | object | Represents information that is sent to a source/originating bank account along with a transfer. Include information within this JSON object for customizing details on ACH debit transfers. Can include an addenda JSON object. |
| destination | no | object | Represents information that is sent to a destination/receiving bank account along with a transfer from a mass payment item. Include information within this JSON object for customizing details on ACH credit transfers. Can include an addenda JSON object. |
| Parameter | Required | Type | Description |
|---|---|---|---|
| addenda | no | object | An addenda object contains a values key which is an array of comma separated string addenda values. Addenda record information is used for the purpose of transmitting transfer-related information. Values must be less than or equal to 80 characters and can include spaces. Acceptable characters are: a-Z, 0-9, and special characters - _ . ~! * ' ( ) ; : @ & = + $ , / ? % # [ ]. Will not show up on bank statements from balance-sourced transfers. |
"achDetails": {
"source": {
"addenda": {
"values": ["ABC123_AddendaValue"]
}
}
},
"achDetails": {
"destination": {
"addenda": {
"values": ["ZYX987_AddendaValue"]
}
}
}
| HTTP Status | Code | Description |
|---|---|---|
| 201 | Created | A mass payment resource was created |
| 400 | ValidationError | Can be: Items exceeded maximum count of 5000, Invalid amount, Invalid metadata, Invalid job item correlation ID, or Invalid funding source. |
| 401 | NotAuthorized | OAuth token does not have Send scope. |
POST https://api-sandbox.dwolla.com/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77
{
"_links": {
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
}
},
"achDetails": {
"source": {
"addenda": {
"values": ["ABC123_AddendaValue"]
}
}
},
"items": [
{
"_links": {
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
}
},
"amount": {
"currency": "USD",
"value": "1.00"
},
"metadata": {
"payment1": "payment1"
},
"achDetails": {
"destination": {
"addenda": {
"values": ["ZYX987_AddendaValue"]
}
}
},
"correlationId": "ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841"
},
{
"_links": {
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
}
},
"amount": {
"currency": "USD",
"value": "5.00"
},
"metadata": {
"payment2": "payment2"
},
"achDetails": {
"destination": {
"addenda": {
"values": ["ZYX987_AddendaValue"]
}
}
}
}
],
"metadata": {
"batch1": "batch1"
},
"correlationId": "6d127333-69e9-4c2b-8cae-df850228e130"
}
...
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/mass-payments/d093bcd1-d0c1-41c2-bcb5-a5cc011be0b7
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:_links => {
:source => {
:href => "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
}
},
:achDetails => {
:source => {
:addenda => {
:values => ["ABC123_AddendaValue"]
}
}
},
:items => [
{
:_links => {
:destination => {
:href => "https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db"
}
},
:amount => {
:currency => "USD",
:value => "1.00"
},
:metadata => {
:payment1 => "payment1"
},
:correlationId => "ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841",
:achDetails => {
:destination => {
:addenda => {
:values => ["ABC123_AddendaValue"]
}
}
}
},
{
:_links => {
:destination => {
:href => "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
}
},
:amount => {
:currency => "USD",
:value => "5.00"
},
:metadata => {
:payment2 => "payment2"
},
:achDetails => {
:destination => {
:addenda => {
:values => ["ABC123_AddendaValue"]
}
}
}
}
],
:metadata => {
:batch1 => "batch1"
},
:correlationId => "6d127333-69e9-4c2b-8cae-df850228e130"
}
mass_payment = app_token.post "mass-payments", request_body
mass_payment.response_headers[:location] # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"
<?php
$massPaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);
$massPayment = $massPaymentsApi->create([
'_links' =>
[
'source' =>
[
'href' => 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4',
],
],
'achDetails' =>
[
'source' => [
'addenda' => [
'values' => ['ABC123_AddendaValue']
]
]
],
'items' =>
[
[
'_links' =>
[
'destination' =>
[
'href' => 'https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db',
],
],
'amount' =>
[
'currency' => 'USD',
'value' => '1.00',
],
'metadata' =>
[
'payment1' => 'payment1',
],
'correlationId' => 'ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841',
'achDetails' =>
[
'source' => [
'addenda' => [
'values' => ['ABC123_AddendaValue']
]
]
]
],
[
'_links' =>
[
'destination' =>
[
'href' => 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd',
],
],
'amount' =>
[
'currency' => 'USD',
'value' => '5.00',
],
'metadata' =>
[
'payment2' => 'payment2',
],
'achDetails' =>
[
'source' => [
'addenda' => [
'values' => ['ABC123_AddendaValue']
]
]
]
],
],
'metadata' =>
[
'batch1' => 'batch1',
],
'correlationId' => '6d127333-69e9-4c2b-8cae-df850228e130',
]);
$massPayment; # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'_links': {
'source': {
'href': 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
}
},
'achDetails': {
'addenda': {
'values': ['ABC123_AddendaValue']
}
},
'items': [
{
'_links': {
'destination': {
'href': 'https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db'
}
},
'amount': {
'currency': 'USD',
'value': '1.00'
},
'metadata': {
'payment1': 'payment1'
},
'correlationId': 'ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841',
'achDetails': {
'addenda': {
'values': ['ABC123_AddendaValue']
}
}
},
{
'_links': {
'destination': {
'href': 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd'
}
},
'amount': {
'currency': 'USD',
'value': '5.00'
},
'metadata': {
'payment2': 'payment2'
},
'achDetails': {
'addenda': {
'values': ['ABC123_AddendaValue']
}
}
}
],
'metadata': {
'batch1': 'batch1'
},
'correlationId': '6d127333-69e9-4c2b-8cae-df850228e130'
}
mass_payment = app_token.post('mass-payments', request_body)
mass_payment.headers['location'] # => 'https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4'
var requestBody = {
_links: {
source: {
href: 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
}
},
achDetails: {
source: {
addenda: {
values: ['ABC123_AddendaValue']
}
}
}
items: [
{
_links: {
destination: {
href: 'https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db'
}
},
amount: {
currency: 'USD',
value: '1.00'
},
metadata: {
payment1: 'payment1'
},
correlationId: 'ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841',
achDetails: {
destination: {
addenda: {
values: ['ABC123_AddendaValue']
}
}
}
},
{
_links: {
destination: {
href: 'https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd'
}
},
amount: {
currency: 'USD',
value: '5.00'
},
metadata: {
payment2: 'payment2'
},
achDetails: {
destination: {
addenda: {
values: ['ABC123_AddendaValue']
}
}
}
}
],
metadata: {
batch1: 'batch1'
},
correlationId: '6d127333-69e9-4c2b-8cae-df850228e130'
}
appToken
.post('mass-payments', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4'
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.
GET https://api.dwolla.com/mass-payments/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | The id of the mass payment to retrieve information for. |
| HTTP Status | Code | Description |
|---|---|---|
| 404 | NotFound | Mass payment not found. |
GET https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
"items": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items"
}
},
"id": "eb467252-808c-4bc0-b86f-a5cd01454563",
"status": "processing",
"created": "2016-03-18T19:44:16.000Z",
"metadata": {}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_url = "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
mass_payment = app_token.get mass_payment_url
mass_payment.status # => "processing"
<?php
$massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';
$massPaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);
$massPayment = $massPaymentsApi->byId($massPaymentUrl);
$massPayment->status; # => "processing"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'
mass_payment = app_token.get(mass_payment_url)
mass_payment.body['status'] # => 'processing'
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';
appToken
.get(massPaymentUrl)
.then(res => res.body.status); // => 'processing'
This section covers how to update a mass payment’s status to pending which triggers processing on a created and deferred mass payment, or cancelled which cancels a created and deferred mass payment.
POST https://api.dwolla.com/mass-payments/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of mass payment to update. |
| status | yes | string | Either pending or cancelled depending on the action you want to take on a deferred mass payment. |
| HTTP Status | Code | Description |
|---|---|---|
| 404 | NotFound | Mass payment not found. |
| 400 | ValidationError | Invalid status. Allowed types are pending, cancelled. |
POST https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"status": "pending"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
"status" => "pending",
}
mass_payment = app_token.post "#{mass_payment_url}", request_body
mass_payment.status # => "pending"
/**
* No example for this language yet. Coming soon.
**/
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
'status': 'pending'
}
mass_payments = app_token.post('mass-payments', request_body)
mass_payments.body['status'] # => 'pending'
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
status: "pending"
};
appToken
.post(massPaymentUrl, requestBody)
.then(res => res.body.status); // => "pending"
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.
GET https://api.dwolla.com/mass-payments/{id}/items
| 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). |
Individual mass payment items can have a status of failed. If an item has a status of failed, an _embedded object will be returned within the item which contains a list of errors. Each error object includes a top-level error code, a message with a detailed description of the error, and a path which is a JSON pointer to the specific field in the request that has a problem. You can utilize both the failure code and message to get a better understanding of why the particular item failed.
| Code | Message | Description |
|---|---|---|
| InsufficientFunds | “Insufficient funds.” | The source funding source has insufficient funds, and as a result failed to create a transfer. |
| Invalid | “Receiver not found.” | The destination was not a valid Customer or Funding Source. |
| Invalid | “Receiver cannot be the owner of the source funding source.” | The destination of the transfer cannot be the same as the source. |
| RequiresFundingSource | “Receiver requires funding source.” | The destination of the mass payment item does not have an active funding source attached. |
| Restricted | “Receiver restricted.” | The destination customer is either deactivated or suspended and is not eligible to receive funds. |
| HTTP Status | Code | Description |
|---|---|---|
| 403 | Forbidden | Not authorized to list mass payment items. |
| 404 | NotFound | Mass payment not found. |
GET https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items"
},
"first": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items?limit=25&offset=0"
},
"last": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563/items?limit=25&offset=0"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payment-items/2f845bc9-41ed-e511-80df-0aa34a9b2388"
},
"mass-payment": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
},
"transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/fa3999db-41ed-e511-80df-0aa34a9b2388"
}
},
"id": "2f845bc9-41ed-e511-80df-0aa34a9b2388",
"status": "success",
"amount": {
"value": "1.00",
"currency": "USD"
},
"metadata": {
"item1": "item1"
}
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payment-items/30845bc9-41ed-e511-80df-0aa34a9b2388",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "mass-payment-item"
},
"mass-payment": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "mass-payment"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
}
},
"_embedded": {
"errors": [
{
"code": "RequiresFundingSource",
"message": "Receiver requires funding source.",
"path": "/items/destination/href",
"_links": {}
}
]
},
"id": "30845bc9-41ed-e511-80df-0aa34a9b2388",
"status": "failed",
"amount": {
"value": "0.02",
"currency": "USD"
},
"metadata": {
"item2": "item2"
}
}
]
},
"total": 2
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'
mass_payment_items = app_token.get "#{mass_payment_url}/items"
mass_payment_items.total # => 2
<?php
$massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563';
$massPaymentItemsApi = new DwollaSwagger\MasspaymentitemsApi($apiClient);
$massPaymentItems = $massPaymentItemsApi->getMassPaymentItems($massPaymentUrl);
$massPaymentItems->total; # => "2"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_url = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'
mass_payment_items = app_token.get('%s/items' % mass_payment_url)
mass_payment_items.body['total'] # => "2"
var massPaymentUrl = 'https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563'
appToken
.get(`${massPaymentUrl}/items`)
.then(res => res.body.total); // => 2
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.
GET https://api.dwolla.com/mass-payment-items/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | The id of the item to be retrieved in a mass payment. |
| HTTP Status | Code | Description |
|---|---|---|
| 403 | Forbidden | Not authorized to list mass payment items. |
| 404 | NotFound | Mass payment not found. |
GET https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388"
},
"mass-payment": {
"href": "https://api-sandbox.dwolla.com/mass-payments/eb467252-808c-4bc0-b86f-a5cd01454563"
},
"destination": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd"
},
"transfer": {
"href": "https://api-sandbox.dwolla.com/transfers/fa3999db-41ed-e511-80df-0aa34a9b2388"
}
},
"id": "2f845bc9-41ed-e511-80df-0aa34a9b2388",
"status": "success",
"amount": {
"value": "1.00",
"currency": "USD"
},
"metadata": {
"item1": "item1"
}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
mass_payment_item_url = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388'
mass_payment_item = app_token.get mass_payment_item_url
mass_payment_item.status # => "success"
<?php
$massPaymentItemUrl = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388';
$massPaymentItemsApi = new DwollaSwagger\MasspaymentitemsApi($apiClient);
$massPaymentItem = $massPaymentItemsApi->byId($massPaymentItemUrl);
$massPaymentItem->status; # => "success"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
mass_payment_item_url = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388'
mass_payment_item = app_token.get(mass_payment_item_url)
mass_payment_item.body['status'] # => 'success'
var massPaymentItemUrl = 'https://api-sandbox.dwolla.com/mass-payment-items/c1c7d293-63ec-e511-80df-0aa34a9b2388';
appToken
.get(massPaymentItemUrl)
.then(res => res.body.status); // => 'success'
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.
GET https://api.dwolla.com/customers/{id}/mass-payments
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Customer unique identifier to get mass payments for. |
| limit | no | integer | How many results to return. Defaults to 25. |
| offset | no | integer | How many results to skip. |
| correlationId | no | string | A string value to search on if a correlationId was specified on a mass payment. |
| HTTP Status | Code | Description |
|---|---|---|
| 403 | NotAuthorized | Not authorized to list mass payments. |
| 404 | NotFound | Customer not found. |
GET https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
....
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments"
},
"first": {
"href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments?limit=25&offset=0"
},
"last": {
"href": "https://api-sandbox.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d/mass-payments?limit=25&offset=0"
}
},
"_embedded": {
"mass-payments": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/mass-payments/89ca72d2-63bf-4a8f-92ef-a5d00140aefa"
},
"source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/e1c972d4-d8d9-4c30-861a-9081dcbaf4ab"
},
"items": {
"href": "https://api-sandbox.dwolla.com/mass-payments/89ca72d2-63bf-4a8f-92ef-a5d00140aefa/items"
}
},
"id": "89ca72d2-63bf-4a8f-92ef-a5d00140aefa",
"status": "complete",
"created": "2016-03-21T19:27:34.000Z",
"metadata": {
"masspay1": "masspay1"
},
"correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
]
},
"total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'
mass_payments = app_token.get "#{customer_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"
<?php
$customerUrl = 'http://api-sandbox.dwolla.com/customers/01B47CB2-52AC-42A7-926C-6F1F50B1F271';
$masspaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);
$masspayments = $masspaymentsApi->getByCustomer($customerUrl);
$masspayments->_embedded->{'mass-payments'}[0]->status; # => "complete"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b'
mass_payments = app_token.get('%s/mass-payments' % customer_url)
mass_payments.body['_embedded']['mass-payments'][0]['status'] # => 'complete'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/ca32853c-48fa-40be-ae75-77b37504581b';
appToken
.get(`${customerUrl}/mass-payments`, { limit: 10 })
.then(res => res.body._embedded['mass-payments'][0].status); // => "complete"
When the state of a resource changes, Dwolla creates a new event resource to record the change. When an Event is created, a Webhook will be created to deliver the Event to any URLs specified by your active Webhook Subscriptions.
| Parameter | Description |
|---|---|
| _links | Contains links to the event, associated resource, and the Account associated with the event. |
| id | Event id |
| created | ISO-8601 timestamp when event was created |
| topic | Type of event |
| resourceId | id of the resource associated with the event. |
{
"_links": {
"self": {
"href": "https://api.dwolla.com/events/f8e70f48-b7ff-47d0-9d3d-62a099363a76"
},
"resource": {
"href": "https://api.dwolla.com/transfers/48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
},
"account": {
"href": "https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
}
},
"id": "f8e70f48-b7ff-47d0-9d3d-62a099363a76",
"created": "2015-10-16T15:58:15.000Z",
"topic": "transfer_created",
"resourceId": "48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
}
| Topic | Description |
|---|---|
| account_suspended | A Dwolla Master Account was suspended. |
| account_activated | A Dwolla Master Account moves from deactivated or suspended to active state of verification. |
| Topic | Description |
|---|---|
| funding_source_added | A funding source was added to a Dwolla account. |
| funding_source_removed | A funding source was removed from a Dwolla account. |
| funding_source_verified | A funding source was marked as verified. |
| funding_source_unverified | A funding source has been systematically unverified. This is generally a result of a transfer failure. View our developer resource article to learn more. |
| funding_source_negative | A Dwolla Master Account balance has gone negative. You are responsible for ensuring a zero or positive Dwolla balance for your account. If your balance funding source has gone negative, you are responsible for making the Dwolla account whole. Dwolla will notify you via a webhook and separate email of the negative balance. If no action is taken, Dwolla will debit your attached billing source. |
| funding_source_updated | A funding source has been updated. This can also be fired as a result of a correction after a bank transfer processes. For example, a financial institution can issue a correction to change the bank account type from checking to savings. |
| microdeposits_added | Two <=10¢ transfers to a Dwolla Master Account’s linked bank account were initiated. |
| microdeposits_failed | The two <=10¢ transfers to a Dwolla Master Account’s linked bank account failed to clear successfully. |
| microdeposits_completed | The two <=10¢ transfers to a Dwolla Master Account’s linked bank account have cleared successfully. |
| microdeposits_maxattempts | The funding source has reached its max verification attempts limit of three. The funding source can no longer be verified with the completed micro-deposit amounts. |
| Topic | Description |
|---|---|
| bank_transfer_created | A bank transfer was created. Represents funds moving either from a Dwolla Master Account’s bank to the Dwolla network or from the Dwolla network to a Dwolla Master Account’s bank. |
| bank_transfer_cancelled | A pending bank transfer has been cancelled, and will not process further. Represents a cancellation of funds either transferring from a Dwolla Master Account’s bank to the Dwolla network or from the Dwolla network to a Dwolla Master Account’s bank. |
| bank_transfer_failed | A 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 Dwolla Master Account’s bank to the Dwolla network or from the Dwolla network to a Dwolla Master Account’s bank. |
| bank_transfer_completed | A bank transfer has cleared successfully. Represents funds clearing either from a Dwolla Master Account’s bank to the Dwolla network or from the Dwolla network to a Dwolla Master Account’s bank. |
| transfer_created | A transfer was created. Represents fund moving either from a Dwolla Master Account’s balance to a verified Customer’s balance or from a Dwolla Master Account’s balance to a verified Customer’s balance. |
| transfer_cancelled | A pending transfer has been cancelled, and will not process further. Represents a cancellation of funds either transferring from a Dwolla Master Account’s balance to a verified Customer’s balance or from a Dwolla Master Account’s balance to a verified Customer’s balance. |
| transfer_failed | A transfer failed to clear successfully. Represents funds failing to clear either from a Dwolla Master Account’s balance to a verified Customer’s balance or from a Dwolla Master Account’s balance to a verified Customer’s balance. |
| transfer_completed | A transfer has cleared successfully. Represents funds clearing either from a Dwolla Master Account’s balance to a verified Customer’s balance or from a Dwolla Master Account’s balance to a verified Customer’s balance. |
| Topic | Description |
|---|---|
| mass_payment_created | A mass payment was created. |
| mass_payment_completed | A mass payment completed. |
| mass_payment_cancelled | A created and deferred mass payment was cancelled. |
| Topic | Description |
|---|---|
| customer_created | A Customer was created. |
| customer_verification_document_needed | Additional documentation is needed to verify a Customer. |
| customer_verification_document_uploaded | A verification document was uploaded for a Customer. |
| customer_verification_document_failed | A verification document has been rejected for a Customer. |
| customer_verification_document_approved | A verification document was approved for a Customer. |
| customer_reverification_needed | Incomplete information was received for a Customer; updated information is needed to verify the Customer. |
| customer_verified | A Customer was verified. |
| customer_suspended | A Customer was suspended. |
| customer_activated | A Customer moves from deactivated or suspended to an active status. |
| customer_deactivated | A Customer was deactivated. |
| Topic | Description |
|---|---|
| customer_beneficial_owner_created | Beneficial owner successfully created. |
| customer_beneficial_owner_removed | An individual beneficial owner has been successfully removed from the Customer |
| customer_beneficial_owner_verification_document_needed | Additional documentation is needed to verify an individual beneficial owner. |
| customer_beneficial_owner_verification_document_uploaded | A verification document was uploaded for beneficial owner. |
| customer_beneficial_owner_verification_document_failed | A verification document has been rejected for a beneficial owner. |
| customer_beneficial_owner_verification_document_approved | A verification document was approved for a beneficial owner. |
| customer_beneficial_owner_reverification_needed | A previously verified beneficial owner status has changed due to either a change in the beneficial owner’s information or at request for more information from Dwolla. The individual will need to verify their identity within 30 days. |
| customer_beneficial_owner_verified | A beneficial owner has been verified. |
| Topic | Description |
|---|---|
| customer_funding_source_added | A funding source was added to a Customer. |
| customer_funding_source_removed | A funding source was removed from a Customer. |
| customer_funding_source_verified | A Customer’s funding source was marked as verified. |
| customer_funding_source_unverified | A funding source has been systematically unverified. This is generally a result of a transfer failure. View our developer resource article to learn more. |
| customer_funding_source_negative | A Customer’s balance has gone negative. You are responsible for ensuring a zero or positive Dwolla balance for Customer accounts created by your application. If a Customer balance funding source has gone negative, you are responsible for making the Dwolla Customer account whole. Dwolla will notify you via a webhook and separate email of the negative balance. If no action is taken, Dwolla will debit your attached billing source. |
| customer_funding_source_updated | A Customer’s funding source has been updated. This can also be fired as a result of a correction after a bank transfer processes. For example, a financial institution can issue a correction to change the bank account type from checking to savings. |
| customer_microdeposits_added | Two <=10¢ transfers to a Customer’s linked bank account were initiated. |
| customer_microdeposits_failed | The two <=10¢ transfers to a Customer’s linked bank account failed to clear successfully. |
| customer_microdeposits_completed | The two <=10¢ transfers to a Customer’s linked bank account have cleared successfully. |
| customer_microdeposits_maxattempts | The Customer has reached their max verification attempts limit of three. The Customer can no longer verify their funding source with the completed micro-deposit amounts. |
| Topic | Description |
|---|---|
| customer_bank_transfer_created | A bank transfer was created for a Customer. Represents funds moving either from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank. |
| customer_bank_transfer_creation_failed | An attempt to initiate a transfer to a verified Customer’s bank was made, but failed. Transfers initiated to a verified Customer’s bank must pass through the verified Customer’s balance before being sent to a receiving bank. Dwolla will fail to create a transaction intended for a verified Customer’s bank if the funds available in the balance are less than the transfer amount. |
| customer_bank_transfer_cancelled | A pending Customer bank transfer has been cancelled, and will not process further. Represents a cancellation of funds either transferring from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank. |
| customer_bank_transfer_failed | A Customer bank transfer failed to clear successfully. Usually, this is a result of an ACH failure (insufficient funds, etc.). Represents funds failing to clear either from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank. |
| customer_bank_transfer_completed | A bank transfer that was created for a Customer has cleared successfully. Represents funds clearing either from a verified Customer’s bank to the Dwolla network or from the Dwolla network to a verified Customer’s bank. |
| customer_transfer_created | A transfer was created for a Customer. Represents funds transferring from a verified Customer’s balance or unverified Customer’s bank |
| customer_transfer_cancelled | A pending transfer has been cancelled, and will not process further. Represents a cancellation of funds transferring either to an unverified Customer’s bank or to a verified Customer’s balance. |
| customer_transfer_failed | A Customer transfer failed to clear successfully. Represents funds failing to clear either to an unverified Customer’s bank or to a verified Customer’s balance. |
| customer_transfer_completed | A Customer transfer has cleared successfully. Represents funds clearing either to an unverified Customer’s bank or to a verified Customer’s balance. |
| Topic | Description |
|---|---|
| customer_mass_payment_created | A Verified Customer’s mass payment was created. |
| customer_mass_payment_completed | A Verified Customer’s mass payment completed. |
| customer_mass_payment_cancelled | A Verified Customer’s created and deferred mass payment was cancelled. |
| customer_balance_inquiry_completed | Upon checking a Customer’s bank balance, Dwolla will immediately return an HTTP 202 with response body that includes a status of processing. This event will be triggered when the bank balance check has completed processing. |
Retrieve a list of events for the application. Note: Dwolla will only guarantee access to events through the API over a rolling 30-day period.
GET https://api.dwolla.com/events
| Parameter | Required | Type | Description |
|---|---|---|---|
| limit | no | integer | How many results to return |
| offset | no | integer | How many results to skip |
| HTTP Status | Message |
|---|---|
| 404 | Resource not found. |
GET https://api-sandbox.dwolla.com/events
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/events"
},
"first": {
"href": "https://api-sandbox.dwolla.com/events?limit=25&offset=0"
},
"last": {
"href": "https://api-sandbox.dwolla.com/events?limit=25&offset=150"
},
"next": {
"href": "https://api-sandbox.dwolla.com/events?limit=25&offset=25"
}
},
"_embedded": {
"events": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/events/78e57644-56e4-4da2-b743-059479f2e80f"
},
"resource": {
"href": "https://api-sandbox.dwolla.com/transfers/47CFDDB4-1E74-E511-80DB-0AA34A9B2388"
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
}
},
"id": "78e57644-56e4-4da2-b743-059479f2e80f",
"created": "2015-10-16T15:58:18.000Z",
"topic": "bank_transfer_created",
"resourceId": "47CFDDB4-1E74-E511-80DB-0AA34A9B2388"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/events/f8e70f48-b7ff-47d0-9d3d-62a099363a76"
},
"resource": {
"href": "https://api-sandbox.dwolla.com/transfers/48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
}
},
"id": "f8e70f48-b7ff-47d0-9d3d-62a099363a76",
"created": "2015-10-16T15:58:15.000Z",
"topic": "transfer_created",
"resourceId": "48CFDDB4-1E74-E511-80DB-0AA34A9B2388"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/events/9f0167e0-dce6-4a1a-ad26-30015d6f1cc1"
},
"resource": {
"href": "https://api-sandbox.dwolla.com/transfers/08A166BC-1B74-E511-80DB-0AA34A9B2388"
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
}
},
"id": "9f0167e0-dce6-4a1a-ad26-30015d6f1cc1",
"created": "2015-10-16T15:37:03.000Z",
"topic": "bank_transfer_created",
"resourceId": "08A166BC-1B74-E511-80DB-0AA34A9B2388"
}
]
},
"total": 3
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
events = app_token.get "events"
events.total # => 3
<?php
$eventsApi = new DwollaSwagger\EventsApi($apiClient);
$events = $eventsApi->events();
$events->total; # => 3
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
events = app_token.get('events')
events.body['total'] # => 3
appToken
.get('events')
.then(res => res.body.total); // => 3
This section covers how to retrieve an event by id.
GET https://api.dwolla.com/events/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | ID of application event to get. |
| HTTP Status | Message |
|---|---|
| 404 | Application event not found. |
GET https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095"
},
"resource": {
"href": "https://api-sandbox.dwolla.com/transfers/09A166BC-1B74-E511-80DB-0AA34A9B2388"
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8"
}
},
"id": "81f6e13c-557c-4449-9331-da5c65e61095",
"created": "2015-10-16T15:37:02.000Z",
"topic": "customer_transfer_created",
"resourceId": "09A166BC-1B74-E511-80DB-0AA34A9B2388"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
event_url = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'
event = app_token.get event_url
event.topic # => "customer_transfer_created"
<?php
$eventUrl = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095';
$eventsApi = new DwollaSwagger\EventsApi($apiClient);
$event = $eventsApi->id($eventUrl);
$event->topic; # => "customer_transfer_created"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
event_url = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095'
event = app_token.get(event_url)
event.body['topic'] # => 'customer_transfer_created'
var eventUrl = 'https://api-sandbox.dwolla.com/events/81f6e13c-557c-4449-9331-da5c65e61095';
appToken
.get(eventUrl)
.then(res => res.body.topic); // => 'customer_transfer_created'
Create a webhook subscription to receive POST requests from Dwolla (called webhooks) when events associated with your application occur. Webhooks are sent to a URL which you provide when creating a webhook subscription. While we see most applications maintain one webhook subscription, you can have up to ten active webhook subscriptions in Sandbox, and up to five in Production at a time. Refer to the events section for the list of events that trigger webhooks.
Dwolla will automatically pause subscribed webhook endpoints that are no longer reachable. The webhook subscription will be paused after 400 consecutive failures. This will help us ensure that unavailable endpoints don’t cause delays or issues in delivery of notifications for other API customers. Webhook subscriptions can be unpaused by calling this endpoint.
When your application receives a webhook, it should respond with a HTTP 2xx status code to indicate successful receipt. If Dwolla receives a status code greater than or equal to 3xx, or your application fails to respond within 10 seconds of the attempt, another attempt will be made. Dwolla will not follow redirects and will treat them as a failure.
Dwolla will re-attempt delivery 8 times over the course of 72 hours according to the backoff schedule below. If a webhook was successfully received but you would like the information again, you can call retrieve a webhook by its Id.
| Retry number | Interval (relative to last retry) | Interval (relative to original attempt) |
|---|---|---|
| 1 | 15 min | 15 min |
| 2 | 45 min | 1 h |
| 3 | 2 h | 3 h |
| 4 | 3 h | 6 h |
| 5 | 6 h | 12 h |
| 6 | 12 h | 24 h |
| 7 | 24 h | 48 h |
| 8 | 24 h | 72 h |
| Parameter | Description |
|---|---|
| id | Webhook subscription unique identifier. |
| url | Subscribed url where Dwolla should deliver the webhook notification. |
| paused | A boolean true or false value indicating if the webhook subscription is paused. A webhook subscription will be automatically paused after 400 consecutive failures. In addition, a subscription can be paused or unpaused by calling this endpoint in the API. |
| created | ISO-8601 timestamp |
This section details how to create a webhook subscription to deliver webhooks to a specified URL.
POST https://api.dwolla.com/webhook-subscriptions
| 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. |
| HTTP Status | Code | Description |
|---|---|---|
| 400 | MaxNumberOfResources | The maximum number of subscriptions has been reached. |
POST https://api-sandbox.dwolla.com/webhook-subscriptions
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q
{
"url": "http://myapplication.com/webhooks",
"secret": "sshhhhhh"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:url => "http://myawesomeapplication.com/destination",
:secret => "your webhook secret"
}
subscription = app_token.post "webhook-subscriptions", request_body
subscription.response_headers[:location] # => "https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"
var requestBody = {
url: 'http://myawesomeapplication.com/destination',
secret: 'your webhook secret'
};
appToken
.post('webhook-subscriptions', requestBody)
.then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'url': 'http://myapplication.com/webhooks',
'secret': 'sshhhhhh'
}
retries = app_token.post('webhook-subscriptions', request_body)
retries.body['total'] # => 1
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$subscription = $webhookApi->create(array (
'url' => 'http://myapplication.com/webhooks',
'secret' => 'sshhhhhh',
));
$subscription; # => "https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216"
?>
This section details how to retrieve a webhook subscription by its id.
GET https://api.dwolla.com/webhook-subscriptions/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Webhook subscription unique identifier. |
| HTTP Status | Message |
|---|---|
| 404 | Webhook subscription not found. |
GET https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/webhook-subscriptions/077dfffb-4852-412f-96b6-0fe668066589"
},
"webhooks": {
"href": "https://api-sandbox.dwolla.com/webhook-subscriptions/077dfffb-4852-412f-96b6-0fe668066589/webhooks"
}
},
"id": "077dfffb-4852-412f-96b6-0fe668066589",
"url": "http://myapplication.com/webhooks",
"created": "2015-10-28T16:20:47+00:00"
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
webhook_subscription = app_token.get webhook_subscription_url
webhook_subscription.created # => 2015-10-28T16:20:47+00:00
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';
appToken
.get(webhookSubscriptionUrl)
.then(res => res.body.created); // => '2016-04-20T15:49:50.340Z'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
webhook_subscription = app_token.get(webhook_subscription_url)
webhook_subscription.body['created'] # => '2015-10-28T16:20:47+00:00'
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$retrieved = $webhookApi->id('https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');
$retrieved->created; # => 2015-10-28T16:20:47+00:00
?>
This section details how to pause a webhook subscription. When a webhook subscription is paused, Dwolla will continue to create webhooks but not send them to your subscribed webhook url. This is useful if your webhook endpoint is unavailable and you want to temporarily disable webhook requests.
POST https://api.dwolla.com/webhook-subscriptions/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Webhook unique identifier. |
| paused | yes | boolean | Specify a value of true to pause the associated webhook subscription or false to unpause a paused subscription. |
POST https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q
{
"paused": true
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
request_body = {
:paused => true
}
subscription = app_token.post "#{webhook_subscription_url}", request_body
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
paused: true
};
appToken
.post(webhookSubscriptionUrl, requestBody)
.then(res => res.body.paused); // => 'true'
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
request_body = {
'paused': true
}
subscription = app_token.post(webhook_subscription_url, request_body)
subscription.body['paused'] # => true
<?php
$webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$subscription = $webhookApi->updateSubscription(array (
'paused' => true
), $webhookSubscriptionUrl);
?>
This section covers how to retrieve a list of webhook subscriptions that belong to an application.
GET https://api.dwolla.com/webhook-subscriptions
GET https://api-sandbox.dwolla.com/webhook-subscriptions
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/webhook-subscriptions"
}
},
"_embedded": {
"webhook-subscriptions": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/webhook-subscriptions/f4d21628-fde2-4d3a-b69a-0a7cb42adc4c"
},
"webhooks": {
"href": "https://api-sandbox.dwolla.com/webhook-subscriptions/f4d21628-fde2-4d3a-b69a-0a7cb42adc4c/webhooks"
}
},
"id": "f4d21628-fde2-4d3a-b69a-0a7cb42adc4c",
"url": "https://destination.url",
"created": "2015-08-19T21:43:49.000Z"
}
]
},
"total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscriptions = app_token.get "webhook-subscriptions"
webhook_subscriptions.total # => 1
appToken
.get('webhook-subscriptions')
.then(res => res.body.total); // => 1
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscriptions = app_token.get('webhook-subscriptions')
webhook_subscriptions.body['total'] # => 1
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$retrieved = $webhookApi->_list();
$retrieved->total; # => 1
?>
Delete a Webhook Subscription to stop receiving Webhooks at the URL specified. If using an SDK, the request was successful unless an exception was thrown stating otherwise.
DELETE https://api.dwolla.com/webhook-subscriptions/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Webhook unique identifier. |
| HTTP Status | Message |
|---|---|
| 404 | Webhook subscription not found. |
DELETE https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
app_token.delete webhook_subscription_url
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';
appToken.delete(webhookSubscriptionUrl);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
app_token.delete(webhook_subscription_url)
<?php
$webhookApi = new DwollaSwagger\WebhooksubscriptionsApi($apiClient);
$webhookApi->deleteById('https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');
?>
This section covers how to view all fired webhooks for a webhook subscription. Note: Dwolla will only guarantee access to webhook data through the API over a rolling 30-day period.
GET https://api.dwolla.com/webhook-subscriptions/{id}/webhooks
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Webhook subscription unique identifier. |
| limit | no | integer | How many results to return. Defaults to 25. |
| offset | no | integer | How many results to skip. |
GET https://api-sandbox.dwolla.com/webhook-subscriptions/10d4133e-b308-4646-b276-40d9d36def1c/webhooks
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {},
"total": 0,
"_embedded": {
"webhooks": [
{
"_links": {},
"id": "string",
"topic": "string",
"accountId": "string",
"eventId": "string",
"subscriptionId": "string",
"attempts": [
{
"id": "string",
"request": {
"created": "2015-07-23T14:19:37.006Z",
"url": "string",
"headers": [
{
"name": "string",
"value": "string"
}
],
"body": "string"
},
"response": {
"created": "2015-07-23T14:19:37.006Z",
"headers": [
{
"name": "string",
"value": "string"
}
],
"statusCode": 0,
"body": "string"
}
}
}
]
}
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
hooks = app_token.get "#{webhook_subscription_url}/webhooks"
hooks.total # => 5
var webhookSubscriptionUrl = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216';
appToken
.get(`${webhookSubscriptionUrl}/webhooks`)
.then(res => res.body.total); // => 5
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_subscription_url = 'https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216'
hooks = app_token.get('%s/webhooks' % webhook_subscription_url)
hooks.body['total'] # => 5
<?php
$webhookApi = new DwollaSwagger\WebhooksApi($apiClient);
$hooks = $webhookApi->hooksById('https://api-sandbox.dwolla.com/webhook-subscriptions/5af4c10a-f6de-4ac8-840d-42cb65454216');
$hooks->total; # => 5
?>
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.
| 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 |
| Parameter | Description |
|---|---|
| id | Unique id of webhook delivery attempt. |
| request | Request JSON object |
| response | Response JSON object |
| Parameter | Description |
|---|---|
| created | ISO-8601 timestamp |
| url | URL where data was sent to/received from |
| headers | Array of objects with keys name and value representative of HTTP headers |
| body | An Event for the webhook |
This section covers how to retrieve a single webhook.
GET https://api.dwolla.com/webhooks/{id}
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Id of webhook to retrieve. |
| HTTP Status | Message |
|---|---|
| 404 | Webhook not found. |
GET https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8"
},
"subscription": {
"href": "https://api-sandbox.dwolla.com/webhook-subscriptions/a0943041-7a5c-4e8f-92de-b55711ef3a83"
},
"retry": {
"href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
},
"event": {
"href": "https://api-sandbox.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50"
}
},
"id": "9ece9660-aa34-41eb-80d7-0125d53b45e8",
"topic": "transfer_created",
"accountId": "ca32853c-48fa-40be-ae75-77b37504581b",
"eventId": "03c7e14c-7f15-44a2-bcf7-83f2f7e95d50",
"subscriptionId": "a0943041-7a5c-4e8f-92de-b55711ef3a83",
"attempts": [
{
"id": "d4d16621-c6b0-40cb-8dc3-0469fa9dc4e8",
"request": {
"timestamp": "2015-10-27T17:07:34.304Z",
"url": "https://myapp.runscope.net",
"headers": [
{
"name": "X-Dwolla-Topic",
"value": "transfer_created"
},
{
"name": "X-Request-Signature",
"value": "bd93780bd7e1ad77ab821094aaa0f9e3dece5ee3"
}
],
"body": "{\"id\":\"03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\",\"resourceId\":\"81BA6F36-CD7C-E511-80DB-0AA34A9B2388\",\"topic\":\"transfer_created\",\"timestamp\":\"2015-10-27T17:07:34.207Z\",\"_links\":{\"self\":{\"href\":\"https://api.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\"},\"account\":{\"href\":\"https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b\"},\"resource\":{\"href\":\"https://api.dwolla.com/transfers/81BA6F36-CD7C-E511-80DB-0AA34A9B2388\"}}}"
},
"response": {
"timestamp": "2015-10-27T17:07:34.308Z",
"headers": [
{
"name": "Date",
"value": "Tue, 27 Oct 2015 17:07:34 GMT"
},
{
"name": "Content-Type",
"value": "application/json; charset=UTF-8"
},
{
"name": "Content-Length",
"value": "1093"
},
{
"name": "Connection",
"value": "keep-alive"
},
{
"name": "Access-Control-Allow-Credentials",
"value": "true"
},
{
"name": "Access-Control-Allow-Methods",
"value": "GET, PUT, POST, PATCH, DELETE, OPTIONS, HEAD"
},
{
"name": "Server",
"value": "Runscope-Gateway/1.0"
},
{
"name": "Runscope-Message-Id",
"value": "97aa5bbd-784f-4007-80cc-8f56919000a0"
},
{
"name": "Access-Control-Allow-Origin",
"value": "*"
}
],
"statusCode": 200,
"body": "{\"body\":\"{\"id\":\"03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\",\"resourceId\":\"81BA6F36-CD7C-E511-80DB-0AA34A9B2388\",\"topic\":\"transfer_created\",\"timestamp\":\"2015-10-27T17:07:34.207Z\",\"_links\":{\"self\":{\"href\":\"https://api-sandbox.dwolla.com/events/03c7e14c-7f15-44a2-bcf7-83f2f7e95d50\"},\"account\":{\"href\":\"https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b\"},\"resource\":{\"href\":\"https://api.dwolla.com/transfers/81BA6F36-CD7C-E511-80DB-0AA34A9B2388\"}}}\",\"files\":[],\"form\":{},\"fragment\":\"\",\"headers\":{\"Connection\":[\"close\"],\"Content-Length\":[\"453\"],\"Content-Type\":[\"application/json; charset=UTF-8\"],\"Host\":[\"myapp.runscope.net\"],\"User-Agent\":[\"dwolla-webhooks/1.0\"],\"X-Dwolla-Topic\":[\"transfer_created\"],\"X-Request-Signature\":[\"bd93780bd7e1ad77ab821094aaa0f9e3dece5ee3\"]},\"host\":\"myapp.runscope.net\",\"method\":\"POST\",\"params\":{},\"path\":\"/\",\"region\":\"us5\",\"runscope_host\":\"prod078.runscope.in\",\"scheme\":\"https\",\"source\":\"capture\",\"source_ip\":\"52.24.10.184\",\"timestamp\":1.4459656543078682e+09,\"url\":\"https://myapp.runscope.net/\"}"
}
}
]
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'
webhook = app_token.get webhook_url
webhook.topic # => "transfer_created"
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';
$webhooksApi = new DwollaSwagger\WebhooksApi($apiClient);
$webhook = $webhooksApi->id($webhookUrl);
$webhook->topic; # => "transfer_created"
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'
webhook = app_token.get(webhook_url)
webhook.body['topic'] # => 'transfer_created'
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';
appToken
.get(webhookUrl)
.then(res => res.body.topic); // => 'transfer_created'
This section details how to retry a webhook by id.
POST https://api.dwolla.com/webhooks/{id}/retries
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Id of webhook to retry. |
| HTTP Status | Message |
|---|---|
| 404 | Webhook not found. |
POST https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries/5aa27a0f-cf99-418d-a3ee-67c0ff99a494
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'
app_token.post "#{webhook_url}/retries"
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';
$webhooksApi = new DwollaSwagger\WebhooksApi($apiClient);
$webhooksApi->retryWebhook($webhookUrl);
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'
app_token.post('%s/retries' % webhook_url)
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';
appToken.post(`${webhookUrl}/retries`);
This section covers how to retrieve webhook retries by id.
This endpoint requires an OAuth application access token.
GET https://api.dwolla.com/webhooks/{id}/retries
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Id of webhook to get retries for. |
| HTTP Status | Message |
|---|---|
| 404 | Webhook not found. |
GET https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries"
}
},
"_embedded": {
"retries": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8/retries/5aa27a0f-cf99-418d-a3ee-67c0ff99a494"
},
"webhook": {
"href": "https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8"
}
},
"id": "5aa27a0f-cf99-418d-a3ee-67c0ff99a494",
"timestamp": "2015-11-02T17:43:26.000Z"
}
]
},
"total": 1
}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'
retries = app_token.get "#{webhook_url}/retries"
retries.total # => 1
<?php
$webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';
$webhooksApi = new DwollaSwagger\WebhooksApi($apiClient);
$retries = $webhooksApi->retriesById($webhookUrl);
$retries->total; # => 1
?>
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
webhook_url = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8'
retries = app_token.get('%s/retries' % webhook_url)
retries.body['total'] # => 1
var webhookUrl = 'https://api-sandbox.dwolla.com/webhooks/9ece9660-aa34-41eb-80d7-0125d53b45e8';
appToken
.get(`${webhookUrl}/retries`)
.then(res => res.body.total); // => 1
Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.