NAV
json php ruby python node.js

Introduction

  _          _ _             
 | |__   ___| | | ___        
 | '_ \ / _ \ | |/ _ \       
 | | | |  __/ | | (_) |      
 |_| |_|\___|_|_|\___/     _ 
 __      _____  _ __| | __| |
 \ \ /\ / / _ \| '__| |/ _` |
  \ V  V / (_) | |  | | (_| |
   \_/\_/ \___/|_|  |_|\__,_|

Welcome to the Dwolla API documentation. Dwolla’s Web API enables you to send money, retrieve transaction data, request money, add bank accounts, accept payments, and a whole lot more.

Sample code is available in PHP, Ruby, Python, and Node.JS in the dark area to the right. JSON is shown by default but the tabs on the top right can be used to switch the language in which the examples are displayed in.

Helper Libraries

We'll show you sample code on this pane!
Quote of the day:

<erno> hm. I've lost a machine.. literally _lost_. it responds to ping, it works completely, I just can't figure out where in my apartment it is.

A handful of libraries are officially maintained, and others are community maintained.

Making Requests

POST https://www.dwolla.com/oauth/rest/transactions/send
Content-Type: application/json

{
    amount: 15.23,
    destinationId: 'gordon@dwolla.com',
    destinationType: 'Email',
    pin: 1234
}
...

GET https://www.dwolla.com/oauth/rest/transactions?client_id=XYZ&client_secret=JJJ&limit=10

POST requests must have a JSON encoded body and the Content-Type: application/json header.

GET requests have parameters provided in the querysting.

All requests must be made over HTTPS. Any HTTP requests are met with a HTTP 302 to its HTTPS equivalent.

Responses

Happy response

{
    "Success": true,
    "Message": "Success",
    "Response": 71332,
    "_links": null
}

Unsuccessful response

{
    "Success": false,
    "Message": "Invalid access token.",
    "Response": null,
    "_links": null
}

Responses are always JSON encoded and are contained in an envelope.

That means every API response contains:

Most API responses will contain:

Facilitator Fees

By enabling the facilitator fee application feature, you can set your own percentage or flat fee from incoming transactions. Transactions created via the Send endpoint and transactions resulting from an Off-Site Gateway checkout can have a facilitator fee attached to it. Facilitator fees can also be attached to Money Requests created by your application. When the Money Request is fulfilled, the facilitator fee will be paid out.

Facilitator fees can be up to 50% of the transaction amount and must be at least $0.01. They do not affect the original transaction amount, and exist as a separate Transaction resource with a unique Transaction ID.

Metadata

Metadata can be supplied for Send, MassPay Items, Money Requests, Refunds, and Checkouts in the metadata property. The metadata property is a JSON object (a collection of “key”: “value” pairs). A maximum of 10 key-value pairs can be stored. Keys and values must be strings of maximum length 255 characters.

{
    "Shipment ID": "d289e89ej893r3r",
    "TShirtSize": "Small",
    "DeliveryOption": "Rush Shipping",
    "InvoiceDate": "12-06-2014",
    "Priority": "High",
    "blah": "blah"
}

Visibility / Access

Metadata is intended as an expansion of the existing notes field (a string of max length 255), in order to allow applications to store more data with resources.

Unlike the notes field, which is visible to:

  1. the application that created the transaction
  2. the recipient and sender of the transaction (through the Dwolla.com dashboard)
  3. any future applications that view the transaction

metadata is only visible to the application that created the transaction. No other application, nor the sender or receiver may access the metadata field.

Warnings

Currently, there are 2 bugs we are aware of:

  1. If an metadata collection contains two duplicate keys, a HTTP 500 XML response will be thrown instead of a proper error response.
  2. Keys which start with a number or symbol (ex. “10”, “10abc”, “$abc”) are rejected.

Errors

When an API request results in an error, Dwolla typically responds with a HTTP status code of 200 and response body containing a JSON object containing an error Message, with Success set to false and Response being null.

However, in special cases, where there is an uncaught exception on our system, or when the API request is malformed (JSON syntax error, duplicated keys) Dwolla will return an HTTP 500 with an XML response body. We realize that having two different response formats for errors is far from ideal, and is something we aim to fix in future versions of the API.

Standard HTTP 200 JSON response:
{
    "Success": false,
    "Message": "Access token is empty.",
    "Response": null
}
HTTP 500 XML response:
<Fault>
    xmlns="http://schemas.microsoft.com/ws/2005/05/envelope/none">
    <Code>
        <Value>Receiver</Value>
        <Subcode>
            <Value 
                xmlns:a="http://schemas.microsoft.com/net/2005/12/windowscommunicationfoundation/dispatcher">a:InternalServiceFault
            </Value>
        </Subcode>
    </Code>
    <Reason>
        <Text xml:lang="en-US">The server was unable to process the request due to an internal error.  For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the &lt;serviceDebug&gt; configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs.</Text>
    </Reason>
</Fault>
HTTP Status Response Type Meaning
200 JSON Normal errors
500 XML Results from an invalid request or uncaught server exception

General Errors

The following errors are common across all API endpoints.

Error String Description
Access token is empty. No OAuth access token has been supplied.
Invalid access token. No OAuth access token has been supplied.
Token does not have access to requested resource. Token must have {…} scope access. The given OAuth token does not have access to the requested scope used. Please review the scopes list.
Invalid account status for user of this access token. The account associated with the given OAuth token is in an invalid status.
Application is either not verified or suspended. The application used to generate the OAuth token has been unverified or suspended.
Account temporarily locked Too many failed attempts have been made to access this account. The account has been temporarily locked for 30 minutes.
Unexpected error has occurred. Something unexpected happened. It has been logged on our end and will be reviewed shortly.

Authentication

You’ll need to provide your Application key and secret when you initialize our libraries.

var Dwolla = require('dwolla')("key here", "secret here");

Dwolla.setToken("token goes here");
require 'dwolla'

# set API keys
Dwolla::api_key = "blahblahblah"
Dwolla::api_secret = "shhhhhh"

# set an OAuth access token
Dwolla::token = "JRRTolkien"
<?php
// Any dwolla-php subclass can be configured in the following manner
require '../vendor/autoload.php';
$Account = new Dwolla\Account();

$Account->settings->sandbox = false;
$Account->settings->debug = true;

$Account->settings->client_id = "Key";
$Account->settings->client_secret = "Secret";
$Account->settings->oauth_token = "OAuth token";
?>
from dwolla import accounts, constants

# Configure the library (change these)
constants.sandbox=False

constants.client_id = "zbDwIC0dWCVU7cQtfvGwVwVjvxwQfjaTgkVi+FZOmKqPBzK5JG"
constants.client_secret = "ckmgwJz9h/fZ09unyXxpupCyrmAMe0bnUiMHF/0+SDaR9RHe99"
constants.access_token = "aK6DdCVlIsR1hKvTbp8VCwnvci8cwaTLlW9edtbHJVmKoopnoe"

# Use the endpoints under accounts()
print accounts.basic('some ID')

Invalid or Expired Access Token Response:

{
  "Success": false,
  "Message": "Invalid access token.",
  "Response": null
}
{
  "Success": false,
  "Message": "Expired access token.",
  "Response": null
}

To interact with the API, you will need API keys. Create a consumer application in order to get an Application key and secret.

Some API endpoints only require your application key and secret (for instance, creating a checkout or looking up a user), but most require an OAuth access_token.

For endpoints that require an OAuth access token, it should be included in the Authorization HTTP header like so:

Authorization: Bearer <T0K3N_H3R3>

OAuth

  /$$$$$$   /$$$$$$              /$$     /$$      
 /$$__  $$ /$$__  $$            | $$    | $$      
| $$  \ $$| $$  \ $$ /$$   /$$ /$$$$$$  | $$$$$$$ 
| $$  | $$| $$$$$$$$| $$  | $$|_  $$_/  | $$__  $$
| $$  | $$| $$__  $$| $$  | $$  | $$    | $$  \ $$
| $$  | $$| $$  | $$| $$  | $$  | $$ /$$| $$  | $$
|  $$$$$$/| $$  | $$|  $$$$$$/  |  $$$$/| $$  | $$
 \______/ |__/  |__/ \______/    \___/  |__/  |__/                                                          

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

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

The access_token can then be used to make API calls which require user authentication like Send or List Transactions.

Token lifetimes

Access tokens are short lived: 1 hour.

Refresh tokens are long lived: 60 days.

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

Request Authorization

<?php

$OAuth = new Dwolla\OAuth();
$OAuth->settings->client_id = $apiKey;
$OAuth->settings->client_secret = $apiSecret;

$url = $OAuth->genAuthUrl("https://myredirect.com/redirect");

?>
# Generate OAuth URL with redirect to requestb.in
print(oauth.genauthurl("http://requestb.in/122rdhc1"))
// where to send the user after they grant permission:
var redirect_uri = "https://www.myredirect.com/redirect";  

// generate OAuth initiation URL
var authUrl = Dwolla.authUrl(redirect_uri);
redirect_uri = "https://www.myredirect.com/redirect"
authUrl = Dwolla::OAuth.get_auth_url(redirect_uri)

Example initiation URL:

https://www.dwolla.com/oauth/v2/authenticate?client_id=abcdefg&response_type=code&redirect_uri=https%3A%2F%2Fwww.myredirect.com%2Fredirect&scope=send|transactions

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

URL Format:

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

Parameter Optional Description
client_id Application key
response_type This must always be set to code
redirect_uri URL where the user will be redirected to afterwards
scope Permissions you are requesting. See below for list of available scopes. Scopes are delimited by a pipe (“|”)
verified_account yes Require new users opting to register for Dwolla to create a fully-verified Dwolla account instead of a default lightweight Direct account. true or false
dwolla_landing yes An optional override that force displays either the login or create an account screen. Valid values are: login, register, or null.

OAuth Scopes

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

Scope Name Description
AccountInfoFull Access detailed account profile
Contacts Access the user’s contacts
Transactions Access the user’s transaction data
Balance Access the user’s Dwolla account balance
Send Send money on the user’s behalf
Request Send money requests, list them, fulfill them
Funding Access the user’s funding sources (i.e. connected bank accounts)
ManageAccount Manage the user’s account settings
Scheduled Allow scheduling one-time and recurring payments.

Finish Authorization

<?php

$OAuth = new Dwolla\OAuth();
$OAuth->settings->client_id = $apiKey;
$OAuth->settings->client_secret = $apiSecret;

$authorizationCode = "J9kkk2JbX7Yjl4L28fM13il46QI=";
$redirect_uri = "https://www.myredirect.com/redirect";
$result = $OAuth->get($authorizationCode, $redirect_uri);

print_r($result);
?>
# Get access key and refresh token pair
access_set = oauth.get("Z/KHDIyWO/LboIGn3wGGs1+sRWg=", "http://requestb.in/122rdhc1")
print(access_set)
{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr",
  "code": "h6TvQZH+5BsV//O43uOJ0uRkBLk=",
  "grant_type": "authorization_code",
  "redirect_uri": "https://www.myredirect.com/redirect"
}
Dwolla.finishAuth(authorizationCode, redirect_uri, function(error, auth) {
  var access_token = auth.access_token;
  var refresh_token = auth.refresh_token;
});
info = Dwolla::OAuth.get_token(code, redirect_uri)
token = info['access_token']
refresh_token = info['refresh_token']

Successful Response:

{
    "access_token": "YLAZSreh165CAD2tPhAEzFCYYIrVyFomLWUDMGFBZIw9KtIg4q",
    "expires_in": 3600,
    "refresh_token": "Pgk+l9okjwTCfsvIvEDPrsomE1er1txeyoaAkTIBAuXza8WvZY",
    "refresh_expires_in": 5184000,
    "token_type": "bearer"
}

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

HTTP Request

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

Parameter Description
client_id Application key
client_secret Application secret
code The authorization code included in the redirect URL
grant_type This must be set to authorization_code
redirect_uri The same redirect_uri specified in the intiation step

Response Parameters

Parameter Description
access_token A new access token with requested scopes
expires_in The lifetime of the access token, in seconds. Default is 3600.
refresh_token New refresh token
refresh_expires_in The lifetime of the refresh token, in seconds. Default is 5184000.
token_type Always bearer.

Refresh Authorization

{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr",
  "refresh_token": "Pgk+l9okjwTCfsvIvEDPrsomE1er1txeyoaAkTIBAuXza8WvZY",
  "grant_type": "refresh_token"
}
# Exchange your expiring refresh token in "access_set" for another
# access/refresh token pair

print(oauth.refresh(access_set['refresh_token']))
Dwolla.refreshAuth(refreshToken, function(error, auth) {
  var new_access_token = auth.access_token;
  var new_refresh_token = auth.refresh_token;
});
info = Dwolla::OAuth.refresh_auth(refresh_token)
token = info['access_token']
refresh_token = info['refresh_token']
<?php

$OAuth = new Dwolla\OAuth();
$OAuth->settings->client_id = $apiKey;
$OAuth->settings->client_secret = $apiSecret;

$refreshToken = "Cr72k48ogBXh+PLwZ/gq2hAtRYSTQl+NW9W0fTxYjaYKRdEsKI";

$result = $OAuth->refresh($refreshToken);
?>

Successful Response:

{
    "access_token": "hr1tSJk23tOv9RxR8cQuDpUD/kpUgf0cb9WfKtRoPxTw8ymbVt",
    "expires_in": 3600,
    "refresh_token": "lqopeyjq5AJln5fpMedElUULz+XBNNw9nAkIinxE0g4aEzxmDc",
    "refresh_expires_in": 5184000,
    "token_type": "bearer"
}

Invalid or Expired Refresh Token Response:

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

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

NOTE: The refresh_token you receive will change every time you exchange either an authorization_code or refresh_token for a new token pair. Only the most recently issued refresh_token will allow you to receive a new pair.

HTTP Request

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

Parameter Description
client_id Application key
client_secret Application secret
refresh_token A valid refresh token
grant_type This must be set to refresh_token

Response Parameters

Parameter Description
access_token A new access token with requested scopes
expires_in The lifetime of the access token, in seconds. Default is 3600.
refresh_token New refresh token
refresh_expires_in The lifetime of the refresh token, in seconds. Default is 5184000.
token_type Always bearer.

Catalog

      __...--~~~~~-._   _.-~~~~~--...__
    //               `V'               \\ 
   //                 |                 \\ 
  //__...--~~~~~~-._  |  _.-~~~~~~--...__\\ 
 //__.....----~~~~._\ | /_.~~~~----.....__\\
====================\\|//====================
                    `---`  
/**
 * Retrieve the catalog of endpoints that 
 * are available to the OAuth token which you just 
 * retrieved.
 */
print_r($OAuth->catalog("Your Access Token"));
# Retrieve the catalog of endpoints that are 
# available to the OAuth token passed in
[ Dwolla::OAuth.catalog("Another access token")
# Retrieve the catalog of endpoints that
# are available to the current OAuth token!

print(oauth.catalog())
// Get links to the endpoints elligible for use with
// the passed OAuth token
Dwolla.catalog("Access token here!", function(error, links) {
    console.log(links);
});

Response: Full user with token that contains Send, Scheduled, and Requests.

{
    "Success": true,
    "Message": "Success",
    "Response": {},
    "_links": {
        "self": {
            "href": "http://uat.dwolla.com/oauth/rest/catalog"
        },
        "send": {
            "href": "http://uat.dwolla.com/oauth/rest/transactions/send"
        },
        "createScheduled": {
            "href": "http://uat.dwolla.com/oauth/rest/transactions/scheduled"
        },
        "fulfill": {
            "href": "http://uat.dwolla.com/oauth/rest/requests/{request_id}/fulfill",
            "templated": true
        }
    }
}

Response: Direct user with token that contains Send, Scheduled, and Requests.

{
    "Success": true,
    "Message": "Success",
    "Response": {},
    "_links": {
        "self": {
            "href": "http://uat.dwolla.com/oauth/rest/catalog"
        },
        "sendWithoutPin": {
            "href": "http://uat.dwolla.com/oauth/rest/transactions/send"
        },
        "createScheduledWithoutPin": {
            "href": "http://uat.dwolla.com/oauth/rest/transactions/scheduled"
        },
        "fulfillWithoutPin": {
            "href": "http://uat.dwolla.com/oauth/rest/requests/{request_id}/fulfill",
            "templated": true
        }
    }
}

Fetch a list of endpoints available to the user. The Catalog endpoint is an initial step toward supporting HAL.

Currently, it only includes links to the Send, Create Scheduled, and Fulfill Request endpoints. In the future, it will be extended to include all endpoints available to a user.

Use this endpoint to determine whether or not the user needs to provide a PIN in order to use the Send, Create Scheduled, or Fulfill Request endpoints. Since Direct users do not have a PIN, for instance, the sendWithoutPin key will be included in _links instead of the regular send which you would see for Full users. The URI remains the same in either case, but for any link with “WithoutPin” appended to it, you will not need to ask the user for their PIN and may omit the pin parameter when calling the endpoint.

HTTP Request

GET https://www.dwolla.com/oauth/rest/catalog

Webhooks

Webhook notifications are used to notify your application when particular events occur relating to Transactions or Requests that your application facilitated / created. There are four kinds of webhook notifications:

Webhook notifications are JSON-encoded POST requests, and will contain the Content-Type: application/json header. There is currently no way to retrieve past Webhook notifications.

Security


function validate_webhook_signature(body, secret, signature) {
  var crypto = require('crypto');

  hash = crypto
    .createHmac('sha1', secret)
    .update(body)
    .digest('hex');

  return (hash == signature);
}

All webhook notifications include the X-Dwolla-Signature header so that you can verify that it originated from Dwolla. The signature is a SHA-1 HMAC hash of the request body, with the secret key being the application secret (client_secret).

TransactionStatus

POST https://www.example.com/payments/webhook
Content-Type: application/json
X-Dwolla-Signature: d0a74b17a31334edc4e6698c59e460c61bb7f21a

{
    "Id": "4444962",
    "Type": "Transaction",
    "Subtype": "Status",
    "Created": "2014-01-22T16:55:04Z",
    "Triggered": "2014-01-22T16:55:04Z",
    "Value": "processed",
    "Transaction": {
        "Type": "money_sent",
        "Notes": "",
        "Id": 4444962,
        "Source": {
            "Id": "812-687-7049",
            "Name": "Gordon Zheng",
            "Type": "Dwolla"
        },
        "Destination": {
            "Id": "812-713-9234",
            "Name": "Reflector by Dwolla",
            "Type": "Dwolla"
        },
        "Amount": 0.01,
        "SentDate": "2014-01-22T16:55:04Z",
        "ClearingDate": "2014-01-22T16:55:04Z",
        "Status": "processed"
    },
    "Metadata": {
        "InvoiceDate": "12-06-2014",
        "Priority": "High",
        "TShirtSize": "Small",
        "blah": "blah"
    }

}

When the status of a Transaction that your application facilitated changes (e.g. transaction clears successfully, or fails, or is cancelled), Dwolla will send a TransactionStatus webhook.

TransactionReturned

POST https://www.example.com/payments/webhook
Content-Type: application/json
X-Dwolla-Signature: d0a74b17a31334edc4e6698c59e460c61bb7f21a

{
    "Type": "Transaction",
    "Subtype": "Returned",
    "SenderTransactionId": "489977",
    "ReceiverTransactionId": "489978",
    "ReturnCode": "01",
    "ReturnDescription": "Insufficient Funds"
}

Notifies your application when a bank-funded transaction facilitated by your application is returned by the financial institution.

RequestFulfilled

POST https://www.example.com/requests/callback
Content-Type: application/json
X-Dwolla-Signature: f71c2f49a87b6d0a662f449b7dbb83a5c918e237

{
    "Id": 2254043,
    "Source": {
        "Id": "812-552-5953",
        "Name": "Gordon Zheng",
        "Type": "Dwolla"
    },
    "Destination": {
        "Id": "812-687-7049",
        "Name": "Gordon Zheng",
        "Type": "Dwolla"
    },
    "Amount": 0.0100,
    "Notes": "",
    "DateRequested": "2014-01-21T19:07:12Z",
    "Status": "Paid",
    "Transaction": {
        "RequestId": 2254043,
        "Id": 4439897,
        "Source": {
            "Id": "812-687-7049",
            "Name": "Gordon Zheng",
            "Type": "Dwolla"
        },
        "Destination": {
            "Id": "812-552-5953",
            "Name": "Ben Milne",
            "Type": "Dwolla"
        },
        "Amount": 0.01,
        "SentDate": "2014-01-21T19:07:44Z",
        "ClearingDate": "2014-01-21T19:07:44Z",
        "Status": "processed"
    },
    "DateCancelled": "",
    "SenderAssumeAdditionalFees": false,
    "AdditionalFees": [],
    "Metadata": {
        "InvoiceDate": "12-06-2014",
        "Priority": "High",
        "TShirtSize": "Small",
        "blah": "blah"
    }
}

Notifies your application when a Money Request created by your application is fulfilled.

RequestCancelled

Notifies your application when a Money Request created by your application is cancelled.

POST https://www.example.com/requests/callback
Content-Type: application/json
X-Dwolla-Signature: f71c2f49a87b6d0a662f449b7dbb83a5c918e237

{
    "Id": 2254042,
    "Source": {
        "Id": "812-552-5953",
        "Name": "Gordon Zheng",
        "Type": "Dwolla"
    },
    "Destination": {
        "Id": "812-687-7049",
        "Name": "Ben Milne",
        "Type": "Dwolla"
    },
    "Amount": 0.0100,
    "Notes": "",
    "DateRequested": "2014-01-21T19:06:51Z",
    "Status": "Cancelled",
    "CancelledBy": "812-687-7049",
    "DateCancelled": "2014-01-21T19:07:30Z",
    "SenderAssumeAdditionalFees": false,
    "AdditionalFees": [],
    "Metadata": {
        "InvoiceDate": "12-06-2014",
        "Priority": "High",
        "TShirtSize": "Small",
        "blah": "blah"
    }
}

Send Money

  __                      ___    ___               
 /\ \                    /\_ \  /\_ \              
 \_\ \  __  __  __    ___\//\ \ \//\ \      __     
 /'_` \/\ \/\ \/\ \  / __`\\ \ \  \ \ \   /'__`\   
/\ \L\ \ \ \_/ \_/ \/\ \L\ \\_\ \_ \_\ \_/\ \L\.\_ 
\ \___,_\ \___x___/'\ \____//\____\/\____\ \__/.\_\
 \/__,_ /\/__//__/   \/___/ \/____/\/____/\/__/\/_/


/**
 *   Send money ($5.50) to email address gordon@dwolla.com
 **/

<?php
$Transactions = new Dwolla\Transactions();
$Transactions->settings->oauth_token = "foo";
$Transactions->settings->pin = 9999;

$result = $Transactions->send('gordon@dwolla.com', 5.50, [
  'destinationType' => 'Email'
]);

print_r($result);

?>
#   Send money ($1.00) to a Dwolla ID 812-626-8794

transactionId = Dwolla::Transactions.send({
  :destinationId => '812-626-8794', 
  :amount => 1.00, 
  :pin => "9999"})

puts transactionId
# Send $5.50 to a Dwolla ID and print the transaction ID
print(transactions.send('812-197-4121', 5.50))
/**
 *   Send money ($1.00) to an email address, with a note
 **/

// optional params:
var params = {
  destinationType: 'Email', 
  notes: 'Thanks for the coffee!'
};

Dwolla.send(pin, 'gordon@dwolla.com', 1.00, params, function(err, data) {
   if (err) { console.log(err); }
   console.log(data);
});

{
  "amount": 0.01,
  "destinationId": "gordon@dwolla.com",
  "destinationType": "Email",
  "pin": 4321
}

If successful, you’ll receive this response:

343947    // resulting Transacton ID
113533 # Sender transaction ID
{
    "Success": true,
    "Message": "Success",
    "Response": 12345
}
341523   # resulting transaction ID
341523   // resulting transaction ID

Send money from an authorized user’s account to any Dwolla account ID, phone number, or e-mail address. You can send money to any phone number or email address – if the recipient doesn’t yet have a Dwolla account, they’ll be sent an SMS or email notifying them of the payment and prompting them to sign up to claim the funds.

Facilitator fees allow you, as the application facilitating a payment, to take a cut up to 50% of the payment amount. By default, the facilitator fee is sent to the application owner’s account, but you can have them sent to other recipients by declaring additional facilitator fees in the optional additionalFees array.

HTTP Request

POST https://www.dwolla.com/oauth/rest/transactions/send

Parameter Optional? Description
destinationId no Email, Dwolla ID, or phone number of recipient.
pin no The PIN associated with the sender’s account.
amount no Amount of funds to transfer to destination user.
destinationType yes Type of destination user. Defaults to ‘Dwolla’. Possible values are Dwolla, Email, and Phone.
fundsSource yes ID of funding source to use for transaction (defaults to Balance).
notes yes Note to attach to the resulting transaction. Will be visible from dwolla.com dashboard to both sender and recipient. Max 250 characters.
additionalFees yes Array of additional facilitator fee objects. [{"destinationId": "", "amount": 0.01}, ...]
metadata yes Optional JSON object of a maximum of 10 key-value pairs (each key and value must be less than 255 characters). Read more
assumeAdditionalFees yes Set to true if the sending user will assume all additional facilitator fees, false if the destination user will assume the fees. Defaults to false.
facilitatorAmount yes Amount of the facilitator fee to override. Only applicable if the facilitator fee feature is enabled. If set to 0, facilitator fee is disabled for transaction. Cannot exceed 50% of the amount.

Response

If successful, the response is simply the Sender’s Transaction ID for the resulting payment. Read more about Transactions.

Errors

Error String Description
Insufficient balance. The source account does not have sufficient balance in the selected funding source.
The account is limited to $x per transaction. on: The source account has exceeded it’s sending transaction limit
Amount must be at least $0.01. on: The amount to send must be greater than $0.01
Invalid account PIN The supplied PIN is invalid or incorrect.
Invalid SSN for this account. The source account is pending SSN validation.
Invalid funding source provided: {…} The specified funding source doesn’t exist or is invalid.

Checkouts

 _        ,
(_\______/________
   \-|-|/|-|-|-|-|/
    \==/-|-|-|-|-/
     \/|-|-|-|,-'
      \--|-'''
       \_j________
       (_)     (_)

"Shopping Trolley" - hjw

Create a checkout on our Off-Site Gateway.

Checkout sessions must be completed by the user within 15 minutes of their creation.

There are two types of checkouts:

Standard Checkout

A standard checkout means the payment is placed automatically and immediately after the user clicks the Submit button on the confirmation screen.

PayLater Checkout

A PayLater checkout means the user is redirected back to your site after clicking Continue on the confirmation screen. No payment is created yet.

You will have 15 minutes to complete the Checkout in order to place the payment.

To create a PayLater Checkout, set checkoutWithApi to true.

Create a Checkout

<?php

$Checkouts = new Dwolla\Checkouts();
$Checkouts->settings->client_id = $apiKey;
$Checkouts->settings->client_secret = $apiSecret;

$purchaseOrder = [
  'destinationId' => '812-742-3301',
  'total' => '33.99'
];

$result = $Checkouts->create($purchaseOrder, [
  'redirect' => 'https://myredirect.com/redirect'
]);

print_r($result);

?>
{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr",
  "callback": "http://www.something.com/callback",
  "redirect": "http://www.something.com/return",
  "allowGuestCheckout": "true",
  "checkoutWithApi": "false",
  "orderId": "foo123",
  "allowFundingSources": "true",
  "additionalFundingSources": "true",
  "purchaseOrder": {
        "orderItems": [
            {
                "name": "Prime Rib Sandwich", 
                "description": "A somewhat tasty non-vegetarian sandwich", 
                "quantity": "1", 
                "price": "15.00"
            }
        ],
    "destinationId": "812-740-4294",
    "total": 15.00,
    "notes": "blahhh",
    "metadata": {
        "key1": "something",
        "key2": "another thing"
    }
  }
}
var purchaseOrder = {
 destinationId: '812-740-4294',
 total: '5.00'
};

var params = {
 allowFundingSources: true,
 orderId: 'blah',
};

dwolla.createCheckout(redirect_uri, purchaseOrder, params, function(err, checkout) {
 if (err) console.log(err);

 console.log(checkout.checkoutURL);
});
# Create checkout session with items from
# http://docs.dwolla.com/#checkouts

test = checkouts.create({
    'orderItems': {
        frozenset({
            'name': 'Prime Rib Sandwich',
            'description': 'A somewhat tasty non-vegetarian sandwich',
            'quantity': '1',
            'price': '15.00'
        })
    },
    'destinationId': '812-740-4294',
    'total': 15.00,
    'notes': 'blahhh',
    'metadata': frozenset({
        'key1': 'something',
        'key2': 'another thing'
    })})
# Set redirect URL, callback URL
Dwolla::OffsiteGateway.redirect = 'http://dwolla.com/payment_redirect'
Dwolla::OffsiteGateway.callback = 'http://dwolla.com/payment_callback'

# Add products
Dwolla::OffsiteGateway.add_product('Macbook Air', '13" Macbook Air; Model #0001', 499.99, 1)

# Generate a checkout sesssion
pp Dwolla::OffsiteGateway.get_checkout_url('812-734-7288')

If successful, you’ll get this back:

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "CheckoutId": "684862bc-8d94-4e53-9c41-26398b4b7fac"
    }
}
{u'URL': u'https://www.dwolla.com/payment/checkout/684862bc-8d94-4e53-9c41-26398b4b7fac'}
https://www.dwolla.com/payment/checkout/684862bc-8d94-4e53-9c41-26398b4b7fac
array (
  'CheckoutId' => 'f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
  'URL' => 'https://uat.dwolla.com/payment/checkout/f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
)
https://www.dwolla.com/payment/checkout/684862bc-8d94-4e53-9c41-26398b4b7fac

Simply append the resulting CheckoutId to this URI: https://www.dwolla.com/payment/checkout/

https://www.dwolla.com/payment/checkout/684862bc-8d94-4e53-9c41-26398b4b7fac

Then send your user there!

HTTP Request

POST https://www.dwolla.com/oauth/rest/offsitegateway/checkouts

Parameter Optional? Description
client_id Your Application Key
client_secret Your Application Secret
callback Dwolla will POST a Callback containing results of the checkout when it is completed.
redirect User will be redirected to this URL after successfully checking out, or cancelling.
purchaseOrder A purchaseOrder JSON object. See below.
checkoutWithApi yes Create a PayLater checkout. Defaults to false.
allowGuestCheckout yes Enable Dwolla Direct experience for users without a Dwolla account
orderId yes Custom string to identify the checkout. Not persisted in resulting transaction.
allowFundingSources yes Allow the user to pay with a funding source other than their account Balance. Defaults to false.
additionalFundingSources yes If allowFundingSources enabled, use this to filter the types of funding sources allowed.
credit: Only allow Dwolla Credit, if both the merchant and user support it
banks: Only allow bank (ACH) funding sources
fisync: Only allow FiSync-enabled bank funding sources
realtime: Only allow credit and fisync sources
true: Allow all funding source types
false: Do not allow any funding sources
profileId yes This feature allows a recipient to display a different avatar and name, to collect money on a different person/entity’s behalf. Requires special permission to use. Contact us if you’re interested!

PurchaseOrder Object

Parameter Optional? Description
destinationId Dwolla ID of the user who will receive the payment in this checkout.
total Total checkout amount.
tax yes Order tax total. For order display purposes only, not persisted.
discount yes Order discount (must be negative). For order display purposes only, not persisted.
shipping yes Order shipping total. For order display purposes only, not persisted.
notes yes A note of max 250 chars. to attach to the resulting payment.
facilitatorAmount yes Amount of the facilitator fee to override. Only applicable if the facilitator fee feature is enabled. If set to 0, facilitator fee is disabled for transaction.
metadata yes An object containing up to 10 key-value pairs of your choice which is persisted with the resulting transaction. Learn about Metadata
orderItems yes An array of JSON object(s) which contain a name, description, quantity, and price.

Errors

Error String Description
Shipping rate cannot be less than $0. Specified shipping must be greater than $0
Tax cannot be less than $0. Specified tax must be greater than $0
Discount cannot be greater than $0. Specified discount must be less than $0
Total cannot be less than $.01. Total amount of PO must be greater than $0.01
Invalid total. Invalid total in reference to the orderItems in the PO
Notes length is too long. Maximum of 250 character is allowed. Specified notes is greater than the allowed 250 character limit
Price on all order items cannot be less than $0.
Quantity on all order items cannot be less than 1. OrderItems specified must contain a quantity greater than 1
Order item name length must be between 1 and 100 characters. Order item name must be greater than 1 & less than 100 characters
Order item description length must not exceed 200 characters. Order item description must be greater than 1 & less than 200 characters

Retrieve a Checkout

<?php
$Checkouts = new Dwolla\Checkouts();
$Checkouts->settings->client_id = $apiKey;
$Checkouts->settings->client_secret = $apiSecret;

$result = $Checkouts->get("19bca7f7-d92a-4a98-b685-7f0e4a372994");

var_export($result);
?>
# Get information about the checkout with ID abdflkjdf34443

checkouts.get("abdflkjdf34443")
var checkoutId = 'a9d7c86a-0d0d-4466-b228-e15584a1315a';
dwolla.getCheckout(checkoutId, function(err, response) {
  console.log(response);
});
This method is not yet supported in dwolla-ruby.

Response:

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "CheckoutId": "684862bc-8d94-4e53-9c41-26398b4b7fac",
        "Discount": null,
        "Shipping": null,
        "Tax": null,
        "Total": 15,
        "Status": "Completed",
        "FundingSource": "Balance",
        "TransactionId": 69960,
        "ProfileId": null,
        "DestinationTransactionId": 69959,
        "OrderItems": [
            {
                "Description": "A somewhat tasty non-vegetarian sandwich",
                "Name": "Prime Rib Sandwich",
                "Price": 15,
                "Quantity": 1
            }
        ],
        "Metadata": null
    }
}
{ 
  CheckoutId: 'd0429a55-c338-4139-b273-48d2f8c45693',
  Discount: null,
  Shipping: null,
  Tax: null,
  Total: 5,
  Status: 'Completed',
  FundingSource: 'Balance',
  TransactionId: 290142,
  ProfileId: null,
  DestinationTransactionId: 290141,
  OrderItems: [],
  Metadata: null 
}
{ 
  u'CheckoutId': u'd0429a55-c338-4139-b273-48d2f8c45693',
  u'Discount': null,
  u'Shipping': null,
  u'Tax': null,
  u'Total': 5,
  u'Status': u'Completed',
  u'FundingSource': u'Balance',
  u'TransactionId': 290142,
  u'ProfileId': null,
  u'DestinationTransactionId': 290141,
  u'OrderItems': [],
  u'Metadata': null 
}
array (
  'CheckoutId' => 'f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
  'Discount' => NULL,
  'Shipping' => NULL,
  'Tax' => NULL,
  'Total' => 33.99,
  'Status' => 'Created',
  'FundingSource' => NULL,
  'TransactionId' => NULL,
  'ProfileId' => NULL,
  'DestinationTransactionId' => NULL,
  'OrderItems' =>
  array (
  ),
  'Metadata' => NULL,
)
This method is not yet supported in dwolla-ruby.

Fetch an existing checkout by its checkoutId to get its status and details.

HTTP Request

GET https://www.dwolla.com/oauth/rest/offsitegateway/checkouts/{checkoutId}?client_id={key}&client_secret={secret}

Response Parameters

This returns the CheckoutId, Discount, Shipping, Tax, Total, OrderItems, ProfileId, Metadata of the checkout and some additional information:

Parameter Description
Status Status of the checkout.
Possible values: Created, ReadyForApiCheckout, Expired, Completed
FundingSource Type of funding source used to complete the checkout.
Possible values: Balance, Bank, null
TransactionId For the resulting payment, this is the Sender’s Transaction ID.
DestinationTransactionId For the resulting payment, this is the Recipient’s Transaction ID.

Complete a PayLater Checkout

{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr"
}
# Complete the checkout

checkouts.complete('Order ID here')
var checkoutId = 'a9d7c86a-0d0d-4466-b228-e15584a1315a';

dwolla.completeCheckout(checkoutId, function(err, response) {
  console.log(response);
});
<?php

$Checkouts = new Dwolla\Checkouts();
$Checkouts->settings->client_id = $apiKey;
$Checkouts->settings->client_secret = $apiSecret;

$result = $Checkouts->complete("19bca7f7-d92a-4a98-b685-7f0e4a372994");

print_r($result);
?>
This method is not yet supported in dwolla-ruby.

If successful, you’ll get back:

This method is not yet supported in dwolla-ruby.
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Amount": 15,
        "CheckoutId": "041f503b-bf68-4d35-83b3-bc6304a98e78",
        "ClearingDate": "",
        "OrderId": "foo",
        "TestMode": false,
        "TransactionId": 69958,
        "DestinationTransactionId": 69957
    }
}
array (
  'CheckoutId' => 'f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
  'ClearingDate' => NULL,
  'Amount' => 33.99,
  'OrderId' => NULL,
  'TransactionId' => 290144,
  'DestinationTransactionId' => 290143,
  'TestMode' => false
)
{ 
  Amount: 5,
  CheckoutId: 'a9d7c86a-0d0d-4466-b228-e15584a1315a',
  ClearingDate: '',
  OrderId: 'blah',
  TestMode: false,
  TransactionId: 290144,
  DestinationTransactionId: 290143 
}

Otherwise, you might get an error like this one:

{
    "Success":false,
    "Message":"There are insufficient funds for this transaction.",
    "Response":null
}
DwollaPHP: An API error was encountered.
Server Message:

Invalid purchase order.
"There are insufficient funds for this transaction."
This method is not yet supported in dwolla-ruby.

Finish a PayLater checkout. This will attempt to create the payment.

HTTP Request

POST https://www.dwolla.com/oauth/rest/offsitegateway/checkouts/{id}/complete

Response Parameters

Parameter Description
Amount Payment amount
CheckoutId Same Checkout ID you passed in!
OrderId Any order ID provided when the checkout was created. Otherwise, null.
TestMode Boolean. True if Checkout.test was set to true when checkout was created.
TransactionId For the resulting payment, this is the Sender’s Transaction ID.
DestinationTransactionId For the resulting payment, this is the Recipient’s Transaction ID.

Funding Sources

===========================================
#                  BANK                   #
#=========================================#
#   ____        ___________        ____   #
#  |    |      |     |     |      |    |  #      
#  |    |      |     |     |      |    |  #
#  |____|      |   --|--   |      |____|  #
#              |     |     |              #
###########################################

"Bank" - capablemonkey
[
  {
      "Id": "Balance",
      "Name": "My Dwolla Balance",
      "Type": "",
      "Verified": "true",
      "ProcessingType": ""
  },
  {
      "Id": "c58bb9f7f1d51d5547e1987a2833f4fa",
      "Name": "Donations Collection Fund - Savings",
      "Type": "Savings",
      "Verified": "true",
      "ProcessingType": "ACH"
  },
  {
      "Id": "c58bb9f7f1d51d5547e1987a2833f4fb",
      "Name": "Donations Payout Account - Checking",
      "Type": "Checking",
      "Verified": "true",
      "ProcessingType": "FiSync"
  }
]

Dwolla accounts have funding sources, such as linked bank accounts or a line of credit. Funds can be added from a bank funding source (ACH or FiSync) into an user’s account Balance, and vice versa, funds can be withdrawn from a user’s account balance to a bank funding source.

Payments funded by a real-time funding source such as the user’s account balance, a FiSync enabled bank account, or line of Credit clear instantly. On the other hand, transactions funded by ACH bank funding sources require 2-5 business days before the funds will be made available to the recipient.

ACH funding sources can be added and verified via the API.

It’s important to note that the ID of a funding source is an arbitrary string identifer, not a bank account number, which means you don’t need to worry about protecting it to the same standard as you would for sensitive information like a bank account number.

Funding Source Types

Type Description Clearing time
Balance Every Dwolla user has an account balance. Payments funded by a user’s balance clear instantly. Instant
ACH A traditional bank account associated with the account. 2-5 business days
FiSync A linked bank account with a participating FiSync bank. Instant
Credit A line of credit via Dwolla Credit. Currently, only business accounts that have undergone review may accept credit-funded payments. Instant
Sweep A special funding source type available to accounts with Sweep functionality. Instant

Funding Source Resource

Parameter Description
Id Funding Source ID (this is an arbitrary, generated ID)
Name Arbitrary nickname for the funding source
Type Possible values: Savings, Checking, or empty string for Dwolla Account Balance and Credit: ""
Verified "true" if funding source is verified. Funding sources must be verified before funds can be added to a Dwolla balance or withdrawn from it.
ProcessingType Possible values: ACH, FiSync, or empty string: ""

List Funding Sources

/**
 *   Fetch all funding sources for the
 *   authorized user
 **/

Dwolla.fundingSources(function(err, data) {
   console.log(data);
});
# Get a list of funding sources associated
# with the account under the current OAuth token

print(fundingsources.get())
#   Fetch all funding sources for the
#   authorized user

pp Dwolla::FundingSources.get
<?php
$fundingSources = new Dwolla\fundingSources();
$fundingSources->settings->oauth_token = "foo";

$result = $fundingSources->get();

print_r($result);

?>

Response:

array (
  0 =>
  array (
    'Id' => 'Balance',
    'Name' => 'My Dwolla Balance',
    'Type' => '',
    'Verified' => true,
    'ProcessingType' => '',
  ),
  1 =>
  array (
    'Id' => '5da016f7769bcb1de9938a30d194d5a7',
    'Name' => 'Blah - Checking',
    'Type' => 'Checking',
    'Verified' => true,
    'ProcessingType' => 'ACH',
  ),
  2 =>
  array (
    'Id' => '7bf971a12543f560119318e67aa76035',
    'Name' => 'Some Nickname - Checking',
    'Type' => 'Checking',
    'Verified' => false,
    'ProcessingType' => 'ACH',
  ),
)
[
{
    "Id": "Balance",
    "Name": "My Dwolla Balance",
    "Type": "",
    "Verified": "true",
    "ProcessingType": ""
},
{
    "Id": "c58bb9f7f1d51d5547e1987a2833f4fa",
    "Name": "Donations Collection Fund - Savings",
    "Type": "Savings",
    "Verified": "true",
    "ProcessingType": "ACH"
},
{
    "Id": "Credit",
    "Name": "Credit",
    "Type": "",
    "Verified": "true",
    "ProcessingType": ""
},
{
    "Id": "c58bb9f7f1d51d5547e1987a2833f4fb",
    "Name": "Donations Payout Account - Checking",
    "Type": "Checking",
    "Verified": "true",
    "ProcessingType": "FiSync"
}
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Id": "Balance",
            "Name": "My Dwolla Balance",
            "Type": "",
            "Verified": "true",
            "ProcessingType": ""
        },
        {
            "Id": "c58bb9f7f1d51d5547e1987a2833f4fa",
            "Name": "Donations Collection Fund - Savings",
            "Type": "Savings",
            "Verified": "true",
            "ProcessingType": "ACH"
        },
        {
            "Id": "Credit",
            "Name": "Credit",
            "Type": "",
            "Verified": "true",
            "ProcessingType": ""
        },
        {
            "Id": "c58bb9f7f1d51d5547e1987a2833f4fb",
            "Name": "Donations Payout Account - Checking",
            "Type": "Checking",
            "Verified": "true",
            "ProcessingType": "FiSync"
        }
    ]
}
[ 
    { 
        Id: 'Balance',
        Name: 'My Dwolla Balance',
        Type: '',
        Verified: true,
        ProcessingType: '' 
    },

    { 
        Id: '5da016f7769bcb1de9938a30d194d5a7',
        Name: 'Blah - Checking',
        Type: 'Checking',
        Verified: true,
        ProcessingType: 'ACH' 
    } 
]
[
  {
    "Id"             => "Balance",
    "Name"           => "My Dwolla Balance",
    "Type"           => "",
    "Verified"       => true,
    "ProcessingType" => ""
  },
  {
    "Id"             => "5da016f7769bcb1de9938a30d194d5a7",
    "Name"           => "Blah - Checking",
    "Type"           => "Checking",
    "Verified"       => true,
    "ProcessingType" => "ACH"
  }
]

Enumerate a user’s funding sources.

HTTP Request

GET https://www.dwolla.com/oauth/rest/fundingsources/

Request Parameters

The following querystring parameters are optional:

Param Description
destinationId Only show funding sources that a particular recipient can accept a payment from. See the section below.
destinationType The type of the recipient. Possible values: Email, Dwolla, Phone. Defaults to Dwolla
processingTypes Processing types to return. By default, all types returned. Delimited by commas. e.g. processingTypes=ach,fisync
verified Only show funding sources with verified values of either true or false

Filtering funding sources

You can limit the results of this query to only the funding sources that a particular user can receive a payment from. This is helpful, for instance, if the user account you’re trying to send money to has opted-in to not accept payments funded via an ACH funding source. In another case, only select merchant accounts have the ability to receive a Credit funded transaction, so Credit would not appear in the list of funding sources when filtered.

To do so, provide the destinationId and destinationType params in your request. For example, if I only want to see funding sources that the user account ID 812-713-9234 can accept:

GET https://www.dwolla.com/oauth/rest/fundingsources/?destinationId=812-713-9234&destinationType=Dwolla

Errors

Error String Description
No verified funding sources. Could not find any funding sources for the given OAuth token.

Get a Funding Source

/**
 *   Retrieve a funding source by its ID
 **/

var fundingSource = "c58bb9f7f1d51d5547e1987a2833f4fb";

dwolla.fundingSourceById(fundingSource, function(err, res) {
    console.log(res);
})
# Get information about a funding ID

print(fundingsources.info('12345678'))
# Retrieve a funding source by its ID

pp Dwolla::FundingSources.get("5da016f7769bcb1de9938a30d194d5a7")
<?php 

$fundingSources = new Dwolla\fundingSources();
$fundingSources->settings->oauth_token = "foo";

$result = $fundingSources->info('5da016f7769bcb1de9938a30d194d5a7');

var_export($result);
?>

Response:

array (
  'Balance' => NULL,
  'Id' => '5da016f7769bcb1de9938a30d194d5a7',
  'Name' => 'Blah - Checking',
  'Type' => 'Checking',
  'Verified' => true,
  'ProcessingType' => 'ACH',
)
{
  "Id"             => "5da016f7769bcb1de9938a30d194d5a7",
  "Name"           => "Blah - Checking",
  "Type"           => "Checking",
  "Verified"       => true,
  "ProcessingType" => "ACH"
}
{
"Id": "12345678",
"Name": "Donations Payout Account - Checking",
"Type": "Checking",
"Verified": true,
"ProcessingType": "FiSync"
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "c58bb9f7f1d51d5547e1987a2833f4fb",
        "Name": "Donations Payout Account - Checking",
        "Type": "Checking",
        "Verified": true,
        "ProcessingType": "FiSync"
    }
}
{ 
    Id: '5da016f7769bcb1de9938a30d194d5a7',
    Name: 'Blah - Checking',
    Type: 'Checking',
    Verified: true,
    ProcessingType: 'ACH' 
} 

Look up a particular funding source by its funding source ID.

HTTP Request

GET https://www.dwolla.com/oauth/rest/fundingsources/{id}

Errors

Error String Description
No verified funding source matching Id {…} Could not find a funding source with the given ID for the given OAuth token.

Withdraw to a Funding Source

var fundingSource = "c58bb9f7f1d51d5547e1987a2833f4fb";
dwolla.withdrawToFundingSource(pin, 5.00, fundingSource, function(err, res) {
  console.log(res);
})
{
    amount: 300.52,
    pin: 9999
}
# Withdraw $5 from Dwolla to funding ID
# '12345678'.

print(fundingsources.withdraw(5.00, '12345678'))
puts Dwolla::FundingSources.withdraw('funding_source_id', {
  :amount => 12.95, 
  :pin => @pin
})
<?php

$fundingSources = new Dwolla\fundingSources();
$fundingSources->settings->oauth_token = "foo";
$fundingSources->settings->pin = 9999;

$result = $fundingSources->withdraw(5.00, '5da016f7769bcb1de9938a30d194d5a7');

var_export($result);

?>

Response:

{ 
        "Id": 12345678,
        "Amount": 5,
        "Date": "2014-09-05T06:40:56Z",
        "Type": "withdrawal",
        "UserType": "Dwolla",
        "DestinationId": "33be0db8a99c1a03e01e7c6dd54dff26",
        "DestinationName": "Blah",
        "Destination": { 
            "Id": "33be0db8a99c1a03e01e7c6dd54dff26", 
            "Name": "Blah", 
            "Type": "Dwolla", 
            "Image": ""
        },
        "SourceId": "812-742-8722",
        "SourceName": "Cafe Kubal",
        "Source": {
            "Id": "812-742-8722",
            "Name": "Cafe Kubal",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-742-8722" 
        },
        "ClearingDate": "2014-09-08T00:00:00Z",
        "Status": "pending",
        "Notes": null,
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null 
      }
}
array (
  'Id' => 346098,
  'Amount' => 5,
  'Date' => '2014-10-22T19:49:45Z',
  'Type' => 'withdrawal',
  'UserType' => 'Dwolla',
  'DestinationId' => '33be0db8a99c1a03e01e7c6dd54dff26',
  'DestinationName' => 'Blah',
  'Destination' =>
  array (
    'Id' => '33be0db8a99c1a03e01e7c6dd54dff26',
    'Name' => 'Blah',
    'Type' => 'Dwolla',
    'Image' => '',
  ),
  'SourceId' => '812-742-8722',
  'SourceName' => 'Cafe Kubal',
  'Source' =>
  array (
    'Id' => '812-742-8722',
    'Name' => 'Cafe Kubal',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
  ),
  'ClearingDate' => '2014-10-24T00:00:00Z',
  'Status' => 'pending',
  'Notes' => NULL,
  'Fees' => NULL,
  'OriginalTransactionId' => NULL,
  'Metadata' => NULL,
)
{
  "Id"                    => 341600,
  "Amount"                => 12.95,
  "Date"                  => "2014-10-20T03:10:56Z",
  "Type"                  => "withdrawal",
  "UserType"              => "Dwolla",
  "DestinationId"         => "33be0db8a99c1a03e01e7c6dd54dff26",
  "DestinationName"       => "Blah",
  "Destination"           => {
    "Id"    => "33be0db8a99c1a03e01e7c6dd54dff26",
    "Name"  => "Blah",
    "Type"  => "Dwolla",
    "Image" => ""
  },
  "SourceId"              => "812-742-8722",
  "SourceName"            => "Cafe Kubal",
  "Source"                => {
    "Id"    => "812-742-8722",
    "Name"  => "Cafe Kubal",
    "Type"  => "Dwolla",
    "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
  },
  "ClearingDate"          => "2014-10-21T00:00:00Z",
  "Status"                => "pending",
  "Notes"                 => nil,
  "Fees"                  => nil,
  "OriginalTransactionId" => nil,
  "Metadata"              => nil
}
{
    "Success": true,
    "Message": "Success",
    "Response": { 
        "Id": 327843,
        "Amount": 5,
        "Date": "2014-09-05T06:40:56Z",
        "Type": "withdrawal",
        "UserType": "Dwolla",
        "DestinationId": "33be0db8a99c1a03e01e7c6dd54dff26",
        "DestinationName": "Blah",
        "Destination": { 
            "Id": "33be0db8a99c1a03e01e7c6dd54dff26", 
            "Name": "Blah", 
            "Type": "Dwolla", 
            "Image": ""
        },
        "SourceId": "812-742-8722",
        "SourceName": "Cafe Kubal",
        "Source": {
            "Id": "812-742-8722",
            "Name": "Cafe Kubal",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-742-8722" 
        },
        "ClearingDate": "2014-09-08T00:00:00Z",
        "Status": "pending",
        "Notes": null,
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null 
      }
}

{ 
    Id: 327843,
    Amount: 5,
    Date: '2014-09-05T06:40:56Z',
    Type: 'withdrawal',
    UserType: 'Dwolla',
    DestinationId: '33be0db8a99c1a03e01e7c6dd54dff26',
    DestinationName: 'Blah',
    Destination: { 
        Id: '33be0db8a99c1a03e01e7c6dd54dff26', 
        Name: 'Blah', 
        Type: 'Dwolla', 
        Image: '' 
    },
    SourceId: '812-742-8722',
    SourceName: 'Cafe Kubal',
    Source: { 
        Id: '812-742-8722',
        Name: 'Cafe Kubal',
        Type: 'Dwolla',
        Image: 'http://uat.dwolla.com/avatars/812-742-8722' 
    },
    ClearingDate: '2014-09-08T00:00:00Z',
    Status: 'pending',
    Notes: null,
    Fees: null,
    OriginalTransactionId: null,
    Metadata: null 
}

Withdraw funds from a user’s account balance to one of the user’s bank funding sources. A new Transaction of type withdrawal is created as a result.

HTTP Request

POST https://www.dwolla.com/oauth/rest/fundingsources/{id}/withdraw

Request Parameters

Parameter Description
amount Amount to withdraw from balance to funding source
pin User account PIN

Errors

Error String Description
Invalid funding source. The funding source specified is either empty or invalid.
Invalid financial institution. Could not find a funding source with the given ID.
The amount supplied is invalid. The amount parameter is either missing, empty, or invalid (contains illegal characters).
The amount is too small. Please send at least $1.00. The minimum withdraw amount is $1.00. Please adjust the withdraw amount.
Not enough funds in the Dwolla balance to complete the withdrawal. There are not enough funds in the account’s Dwolla balance to complete the withdrawl.

Add money from a Funding Source

{
  amount: 5,
  pin: 9999
}
# Deposit $10 into Dwolla from funding ID
# '12345678'.

print(fundingsources.deposit(10.00, '12345678'))
puts Dwolla::FundingSources.deposit('5da016f7769bcb1de9938a30d194d5a7', {
  :amount => 12.95, 
  :pin => '9999'
})
var fundingSource = "c58bb9f7f1d51d5547e1987a2833f4fb";

dwolla.depositFromFundingSource(pin, 5.00, fundingSource, function(err, res) {
  console.log(res);
})
<?php
$fundingSources = new Dwolla\fundingSources();
$fundingSources->settings->oauth_token = "foo";
$fundingSources->settings->pin = 9999;

$result = $fundingSources->deposit(5.00, '5da016f7769bcb1de9938a30d194d5a7');

var_export($result);
?>

Response:

array (
  'Id' => 346099,
  'Amount' => 5,
  'Date' => '2014-10-22T19:51:01Z',
  'Type' => 'deposit',
  'UserType' => 'Dwolla',
  'DestinationId' => '812-742-8722',
  'DestinationName' => 'Cafe Kubal',
  'Destination' =>
  array (
    'Id' => '812-742-8722',
    'Name' => 'Cafe Kubal',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
  ),
  'SourceId' => '33be0db8a99c1a03e01e7c6dd54dff26',
  'SourceName' => 'Blah',
  'Source' =>
  array (
    'Id' => '33be0db8a99c1a03e01e7c6dd54dff26',
    'Name' => 'Blah',
    'Type' => 'Dwolla',
    'Image' => '',
  ),
  'ClearingDate' => '2014-10-28T00:00:00Z',
  'Status' => 'pending',
  'Notes' => NULL,
  'Fees' => NULL,
  'OriginalTransactionId' => NULL,
  'Metadata' => NULL,
)
{ 
       "Id": 12345678,
       "Amount": 5,
       "Date": "2014-09-05T06:40:56Z",
       "Type": "deposit",
       "UserType": "Dwolla",
       "DestinationId": "33be0db8a99c1a03e01e7c6dd54dff26",
       "DestinationName": "Blah",
       "Destination": {
           "Id": "812-742-8722",
           "Name": "Cafe Kubal",
           "Type": "Dwolla",
           "Image": "http://uat.dwolla.com/avatars/812-742-8722" 
       },
       "SourceId": "812-742-8722",
       "SourceName": "Cafe Kubal",
       "Source": { 
           "Id": "33be0db8a99c1a03e01e7c6dd54dff26", 
           "Name": "Blah", 
           "Type": "Dwolla", 
           "Image": ""
       },
       "ClearingDate": "2014-09-08T00:00:00Z",
       "Status": "pending",
       "Notes": null,
       "Fees": null,
       "OriginalTransactionId": null,
       "Metadata": null 
}
{
  "Id"                    => 341601,
  "Amount"                => 12.95,
  "Date"                  => "2014-10-20T03:12:36Z",
  "Type"                  => "deposit",
  "UserType"              => "Dwolla",
  "DestinationId"         => "812-742-8722",
  "DestinationName"       => "Cafe Kubal",
  "Destination"           => {
    "Id"    => "812-742-8722",
    "Name"  => "Cafe Kubal",
    "Type"  => "Dwolla",
    "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
  },
  "SourceId"              => "33be0db8a99c1a03e01e7c6dd54dff26",
  "SourceName"            => "Blah",
  "Source"                => {
    "Id"    => "33be0db8a99c1a03e01e7c6dd54dff26",
    "Name"  => "Blah",
    "Type"  => "Dwolla",
    "Image" => ""
  },
  "ClearingDate"          => "2014-10-23T00:00:00Z",
  "Status"                => "pending",
  "Notes"                 => nil,
  "Fees"                  => nil,
  "OriginalTransactionId" => nil,
  "Metadata"              => nil
}
{ 
  Id: 327844,
  Amount: 5,
  Date: '2014-09-05T06:40:57Z',
  Type: 'deposit',
  UserType: 'Dwolla',
  DestinationId: '812-742-8722',
  DestinationName: 'Cafe Kubal',
  Destination: { 
    Id: '812-742-8722',
    Name: 'Cafe Kubal',
    Type: 'Dwolla',
    Image: 'http://uat.dwolla.com/avatars/812-742-8722'
  },
  SourceId: '33be0db8a99c1a03e01e7c6dd54dff26',
  SourceName: 'Blah',
  Source: { 
    Id: '33be0db8a99c1a03e01e7c6dd54dff26', 
    Name: 'Blah', 
    Type: 'Dwolla', 
    Image: '' 
  },
  ClearingDate: '2014-09-10T00:00:00Z',
  Status: 'pending',
  Notes: null,
  Fees: null,
  OriginalTransactionId: null,
  Metadata: null 
}
{
    "Success": true,
    "Message": "Success",
    "Response": { 
        "Id": 327843,
        "Amount": 5,
        "Date": "2014-09-05T06:40:56Z",
        "Type": "deposit",
        "UserType": "Dwolla",
        "DestinationId": "33be0db8a99c1a03e01e7c6dd54dff26",
        "DestinationName": "Blah",
        "Destination": {
            "Id": "812-742-8722",
            "Name": "Cafe Kubal",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-742-8722" 
        },
        "SourceId": "812-742-8722",
        "SourceName": "Cafe Kubal",
        "Source": { 
            "Id": "33be0db8a99c1a03e01e7c6dd54dff26", 
            "Name": "Blah", 
            "Type": "Dwolla", 
            "Image": ""
        },
        "ClearingDate": "2014-09-08T00:00:00Z",
        "Status": "pending",
        "Notes": null,
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null 
      }
}

Add funds from a user’s bank funding source to the user’s Dwolla account balance. A new Transaction of type deposit is created as a result.

HTTP Request

POST https://www.dwolla.com/oauth/rest/fundingsources/{id}/deposit

Request Parameters

Parameter Description
amount Amount to withdraw from balance to funding source
pin User account PIN

Errors

Error String Description
Invalid funding source. The funding source specified is either empty or invalid.
Invalid financial institution. Could not find a funding source with the given ID.
The amount supplied is invalid. The amount parameter is either missing, empty, or invalid (contains illegal characters).
The amount is too small. Please send at least $1.00. The minimum amount to add to a balance is $1.00. Please adjust the amount of funds being added to a Dwolla balance.
The account is limited to {…} per transaction The maximum amount of money being added to a Dwolla balance for this account is {…}. Please adjust the amount of money being added to a Dwolla balance.

Add new Funding Source

<?php
$fundingSources = new Dwolla\fundingSources();
$fundingSources->settings->oauth_token = "foo";

$routingNo = "113024915";
$accountNo = "9999999999";
$accountType = "Checking";
$nickname = "My Bank Account";
$result = $fundingSources->add($accountNo, $routingNo, $accountType, $nickname);

var_export($result);
?>
# Add a funding source to the account associated
# with the current OAuth token.
#
# '12345678' is the account number.
# '00000000' is the routing number.
# 'Checking' is the account type.
# 'My Bank' is a user defined account identifier string.

print(fundingsources.add('12345678', '00000000', 'Checking', 'My Bank'))
/**
 * Add a funding source with account number '12345678',
 * routing number '87654321', of type 'Checking' and with
 * name 'My Bank'
 */

var account = '12345678';
var routing = '87654321';

Dwolla.addFundingSource(account, routing, 'Checking', 'My Bank', function(err, data) {
    console.log(data);
});
#   Add a new funding source (bank account).
puts Dwolla::FundingSources.add({
  :routing_number => 113024915, 
  :account_number => 99999999, 
  :account_type => "Checking", 
  :name => "Some Nickname"
})

{
    "account_number": "12345678",
    "routing_number": "87654321",
    "account_type": "Checking",
    "name": "My Bank"
}

Response:

array (
  'Id' => '377d8ed651c2b799784aa2aa10762c37',
  'Name' => 'My Bank Account - Checking',
  'Type' => 'Checking',
  'Verified' => false,
  'ProcessingType' => 'ACH',
)
{
  "Id"             => "7bf971a12543f560119318e67aa76035",
  "Name"           => "Some Nickname - Checking",
  "Type"           => "Checking",
  "Verified"       => false,
  "ProcessingType" => "ACH"
}
{
        "Id": "34da835f235cd25302ef0c5c1cb1d4b9",
        "Name": "My Bank",
        "Type": "Checking",
        "Verified": false,
        "ProcessingType": "ACH"
}
{ 
  Id: '5da016f7769bcb1de9938a30d194d5a7',
  Name: 'My Bank',
  Type: 'Checking',
  Verified: false,
  ProcessingType: 'ACH' 
} 
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "34da835f235cd25302ef0c5c1cb1d4b9",
        "Name": "My Bank",
        "Type": "Checking",
        "Verified": false,
        "ProcessingType": "ACH"
    }
}

Add a new ACH bank account as a funding source for the authenticated user. Once created, the funding source will need to be verified before it can be used. Two micro-deposits will be made, and their amounts must be verified using the Verify endpoint or manually by the user on www.dwolla.com.

HTTP Request

POST https://www.dwolla.com/oauth/rest/fundingsources/

Request Parameters

Parameter Description
account_number The bank account number
routing_number The bank account’s routing number.
account_type Type of bank account: Checking or Savings.
name Arbitrary nickname for the funding source

Errors

Error String Description
Maximum number of bank accounts reached. Users can only have 2 linked funding sources at once.
User must be verified. The user account associated with the given OAuth token is not currently verified. Please verify the user before adding a funding source.
Invalid account type. Invalid bank account type. See request parameters for valid account types.
Invalid account name. Invalid bank account name. See request parameters for valid account names.
Please verify the routing number. It appears invalid. Invalid bank routing number.
Please verify the account number. It appears invalid. Invalid bank account number.
Please verify the SSN of the token holder. It appears invalid. The SSN number of the user associated with the given OAuth token is invalid, or missing.
You have already added this account. This funding source is already linked to the user with the given OAuth token.
There have been too many invalid attempts made with this account. Please wait 30 minutes and try again. There have been too many invalid attempts made with this account. Please wait 30 minutes and try again.
It looks like we’re having problems connecting to your bank. We will automatically process your transaction as soon as we are able to connect. It looks like we’re having problems connecting to your bank. We will automatically process your transaction as soon as we are able to connect.

Verify a Funding Source

<?php
$fundingSources = new Dwolla\fundingSources();
$fundingSources->settings->oauth_token = "foo";

$deposit1 = 0.04;
$deposit2 = 0.02;

$result = $fundingSources->verify($deposit1, $deposit2, "377d8ed651c2b799784aa2aa10762c37");

var_export($result);
?>
puts Dwolla::FundingSources.verify("7bf971a12543f560119318e67aa76035", {
  :deposit1 => 0.01, 
  :deposit2 => 0.04, 
})
# Verify the newly created account with via
# the two micro-deposits.
#
# '0.04' is the first deposit.
# '0.02' is the second deposit.
# '12345678' is the account number.

print(fundingsources.verify(0.04, 0.02, '12345678'))
{
    "deposit1": "0.01",
    "deposit2": "0.04"
}
/**
 * Verify funding source ID '12345678' 
 * with micro-deposits of 0.02 and 0.05
 */

var fundingSource = "c58bb9f7f1d51d5547e1987a2833f4fb";

Dwolla.verifyFundingSource('0.02', '0.05', fundingSource, function(err, data) {
    console.log(data);
});

Response:

array (
  'Id' => '377d8ed651c2b799784aa2aa10762c37',
  'Name' => 'My Bank Account - Checking',
  'Type' => 'Checking',
  'Verified' => true,
  'ProcessingType' => 'ACH',
)
{
        "Id": "12345678",
        "Name": "My Checking Account - Checking",
        "Type": "Checking",
        "Verified": true,
        "ProcessingType": "ACH"
}
{
  "Id"             => "7bf971a12543f560119318e67aa76035",
  "Name"           => "Some Nickname - Checking",
  "Type"           => "Checking",
  "Verified"       => true,
  "ProcessingType" => "ACH"
}
{ 
  Id: '5da016f7769bcb1de9938a30d194d5a7',
  Name: 'My Bank',
  Type: 'Checking',
  Verified: true,
  ProcessingType: 'ACH' 
} 
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "34da835f235cd25302ef0c5c1cb1d4b9",
        "Name": "My Checking Account - Checking",
        "Type": "Checking",
        "Verified": true,
        "ProcessingType": "ACH"
    }
}

Verify the amounts of the 2 micro-deposits sent to a funding source.

HTTP Request

POST https://www.dwolla.com/oauth/rest/fundingsources/{id}/verify

Request Parameters

Parameter Description
deposit1 First amount
deposit2 Second amount

Errors

Error String Description
Invalid funding source ID. The funding source specified is either empty or invalid.
Bank has already been verified. The bank account has already been verified.
Maximum number of verification attempts already reached. Maximum number of verification attempts for this bank account already reached. Please contact customer support.
deposit1 amount isn’t a valid or positive number. The amount specified for ‘deposit1’ isn’t a valid or positive number.
deposit2 amount isn’t a valid or positive number. The amount specified for 'deposit2’ isn’t a valid or positive number.
deposit1 amount should be less than $.15 (ie: enter $.05 for 5 cents) The amount specified for 'deposit1’ should be less than 15 cents.
deposit2 amount should be less than $.15 (ie: enter $.05 for 5 cents) The amount specified for 'deposit2’ should be less than 15 cents.
The verification deposits have not had enough time to clear the system. Please allow 2-3 days from when the bank was added before attempting to verify the account. Please allow 2-3 business days before attempting to verify this funding source.
One or both of the amounts do not match our records. The specified deposit amounts are incorrect.

Transactions

{
    "Id": 4443952,
    "Amount": 0.01,
    "Date": "2014-01-22T13:09:38Z",
    "Type": "money_sent",
    "UserType": "Dwolla",
    "DestinationId": "812-713-9234",
    "DestinationName": "Peter Douglas",
    "Destination": {
        "Id": "812-713-9234",
        "Name": "Peter Douglas",
        "Type": "Dwolla",
        "Image": "http://uat.dwolla.com/avatars/812-713-9234"
    },
    "SourceId": "812-629-2658",
    "SourceName": "Tom Walker",
    "Source": {
        "Id": "812-713-9234",
        "Name": "Tom Walker",
        "Type": "Dwolla",
        "Image": "http://uat.dwolla.com/avatars/812-713-9234"
    },
    "ClearingDate": "",
    "Status": "processed" ,
    "Notes": "don't spend it all in one place!",
    "OriginalTransactionId": null,
    "Metadata": null ,
    "Fees": null
}
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$$,,,$$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$"OOO"$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$!OOO!$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$,"OOO",$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$,"OOOOOOO",$$$$$$$$$$$$$
$$$$$$$$$$$$!"OOOOOOOOOOO"!$$$$$$$$$$$
$$$$$$$$$$,"OOOOOOOOOOOOOOO",$$$$$$$$$
$$$$$$$$,1OOOOOOOOOOOOOOOOOOO7,$$$$$$$
$$$$$$,!OOOOOOOOOOOOOOOOOOOOOO"$$$$$$$
$$$$$$!OOOOOOOOO/""""'\OOOOOOOO1$$$$$$
$$$$$$"OOOOOOOOOO"$$$$!OOOOOOOO"$$$$$$
$$$$$$"OOOOOOOOOOO!$$$",OOOOOOO!$$$$$$
$$$$$$$",OOOOOOOOOO",$$$"""""""$$$$$$$
$$$$$$$$"!OOOOOOOOOOO",$$$$$$$$$$$$$$$
$$$$$$$$$$",OOOOOOOOOOO",$$$$$$$$$$$$$
$$$$$$$$$$$$"OOOOOOOOOOOO",$$$$$$$$$$$
$$$$$$$$$$$$$"!OOOOOOOOOOOO"+$$$$$$$$$
$$$$$$$$$$$$$$$"==OOOOOOOOOOO,$$$$$$$$
$$$$$$$$,,,,,,$$$$",OOOOOOOOOO",$$$$$$
$$$$$$,"OOOOOO',$$$$",OOOOOOOOO!$$$$$$
$$$$$$1OOOOOOOO."~~~"OOOOOOOOOO!$$$$$$
$$$$$$!OOOOOOOOOOOOOOOOOOOOOOO1$$$$$$$
$$$$$$",OOOOOOOOOOOOOOOOOOOOO,"$$$$$$$
$$$$$$$",OOOOOOOOOOOOOOOOOOO!$$$$$$$$$
$$$$$$$$$1OOOOOOOOOOOOOOOO,1$$$$$$$$$$
$$$$$$$$$$"~~,OOOOOOOOOO,"$$$$$$$$$$$$
$$$$$$$$$$$$$$"""1OOO1"'$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$!OOO!$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$,OOO,$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$$"""$$$$$$$$$$$$$$$$$
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
$$$$$ "DWOLLA DWOLLA BILL YA'LL" $$$$$
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$

Any movement of money, whether it’s a payment, fee, withdrawal, or adding funds to a Dwolla balance, is recorded as an individual Transaction. For instance, adding money from a funding source into your Dwolla account balance creates a Transaction of type deposit.

How Transactions Work

When a payment is sent, 2 or more transactions are created. At least one is created to credit the recipient’s account balance, and another one to debit the sender’s account balance.

As a simple example, let’s say Bob sends $5 to Alice from his account balance. From this action, two Transactions are created:

  1. Transaction 512010: credits Alice’s account with $5
  2. Transaction 512011: deducts $5 from Bob’s account

It’s important to keep in mind that when Bob looks at this payment, he will see the credit transaction’s ID: 512010. This is called the Sender’s Transaction ID.

Similarly, when Alice looks up this payment, she will see a different transaction of ID 512011, which we call the Recipient’s Transaction ID.

Additional Transactions

For a particular payment, additional transactions are created:

Learn how to correlate the sender’s and recipient’s transaction ID with this guide.

Transaction Types

Type Description
money_sent Payment sent by a user
money_received Payment received by a user
deposit Funds deposited from a Funding Source (e.g. bank account) to the user’s Dwolla account balance
withdrawal Funds withdrawn from the user’s Dwolla account balance to an associated Funding Source

Transaction Statuses

Status Description
pending Bank-funded payment awaiting clearance; typically requires 3 - 5 business days to clear.
processed Transaction has cleared successfully.
failed Transaction failed to clear successfully. Usually, this is a result of an ACH failure (insufficient funds, etc.).
cancelled A pending transaction has been canceled, and will not process further.
reclaimed The payment was returned to the sender after being unclaimed by the recipient for a period of time.

Transaction Resource

{
  "Amount": 1,
  "Date": "2014-01-22T13:11:10Z",
  "UserType": "Email",
  "DestinationId": "bob@dwolla.com",
  "DestinationName": "bob@dwolla.com,
  "Destination": {
      "Id": "bob@dwolla.com",
      "Name": "bob@dwolla.com",
      "Type": "Email",
      "Image": ""
  },
  "Id": 12345,
  "SourceId": "812-111-2222",
  "SourceName": "Alice",
  "Source": {
      "Id": "812-111-2222",
      "Name": "Alice",
      "Type": "Dwolla",
      "Image": "http://uat.dwolla.com/avatars/812-111-2222"
  },
  "Type": "money_sent",
  "Status": "processed" ,
  "ClearingDate": "",
  "Notes": "Thank you for lunch!",
  "OriginalTransactionId": null,
  "Metadata": {
      "some meta info":  "foobar",
      "aProfoundRealization": "pretzels"
  },
  "Fees": [
      {
          "Id": 1646163,
          "Amount": 0.1,
          "Type": "Facilitator Fee"
      }
  ]
}
Property Description
Amount Amount of funds involved.
Date Timestamp of when the transaction was created. ISO-8601 format.
UserType Type of destination. Can be Dwolla if money was sent to a Dwolla ID, Email, or PhoneNumber.
DestinationId Dwolla ID, email address, or phone number of recipient.
DestinationName Full name of recipient Dwolla user, if available. Otherwise, email or phone number of non-user.
Destination JSON object describing the DestinationId, DestinationName, recipient type (possible values: Dwolla, Email, Phone), and avatar URL of recipient, if available.
Id Unique Transaction ID. Incrementally generated integer. Currently, Transaction IDs are 7 digits long in production, but will eventually grow longer.
SourceId Dwolla ID of the sender’s account
SourceName Full name of the sender
Source JSON object describing the SourceId, DestinationName, and avatar URL of sender, if available. Type will always be Dwolla.
Type Transaction type See above
Status Transaction Status. See above
ClearingDate For bank funded payments, this is the expected clearing date. Otherwise, for real time payments (e.g. funded by Balance), this will be an empty string: ""
Notes Note attached to the payment. Max 250 characters.
OriginalTransactionId If the transaction is a refund, this is the transaction ID of the original transaction which was refunded. Otherwise, null.
Metadata JSON object with max 10 key-value pairs. Keys and values are strings of max length 255. null if not provided or visible to application. Read more
Fees Array of any facilitator fees incurred by this payment. Otherwise, null.

List a user’s transactions

/**
 * Retrieve the 10 most recent transactions for
 * the authorized user
 */

Dwolla.transactions(function(err, data) {
  console.log(data);
});
#   Get 10 most recent transactions
puts Dwolla::Transactions.get
<?php
$Transactions = new Dwolla\Transactions();
$Transactions->settings->oauth_token = "foo";

$result = $Transactions->get();

var_export($result);
?>
# Fetch the 10 most recent transactions
print(transactions.get())

Response:

array (
  0 =>
  array (
    'Id' => 346099,
    'Amount' => 5,
    'Date' => '2014-10-22T19:51:01Z',
    'Type' => 'deposit',
    'UserType' => 'Dwolla',
    'DestinationId' => '812-742-8722',
    'DestinationName' => 'Cafe Kubal',
    'Destination' =>
    array (
      'Id' => '812-742-8722',
      'Name' => 'Cafe Kubal',
      'Type' => 'Dwolla',
      'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
    ),
    'SourceId' => '33be0db8a99c1a03e01e7c6dd54dff26',
    'SourceName' => 'Blah',
    'Source' =>
    array (
      'Id' => '33be0db8a99c1a03e01e7c6dd54dff26',
      'Name' => 'Blah',
      'Type' => 'Dwolla',
      'Image' => '',
    ),
    'ClearingDate' => '2014-10-28T00:00:00Z',
    'Status' => 'pending',
    'Notes' => NULL,
    'Fees' => NULL,
    'OriginalTransactionId' => NULL,
    'Metadata' => NULL,
  ),
  1 =>
  array (
  ...
  ),
)
[
    {
        "Id": 113533,
        "Amount": 5.50,
        "Date": "2014-12-13T05:07:15Z",
        "Type": "money_sent",
        "UserType": "Email",
        "DestinationId": "812-197-4121",
        "DestinationName": "Some Name",
        "Destination": {
            "Id": "812-197-4121",
            "Name": "Some Name",
            "Type": "dwolla",
            "Image": ""
        },
        "SourceId": "812-202-3784",
        "SourceName": "David Stancu",
        "Source": {
            "Id": "812-202-3784",
            "Name": "David Stancu",
            "Type": "Dwolla",
            "Image": "https://dwolla-avatars.s3.amazonaws.com/812-202-3784/ac045522"
        },
        "ClearingDate": "",
        "Status": "cancelled",
        "Notes": "",
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null
    },
    ...
]
[
  {
    "Id"                    => 331506,
    "Amount"                => 15.25,
    "Date"                  => "2014-09-17T18:18:46Z",
    "Type"                  => "withdrawal",
    "UserType"              => "Dwolla",
    "DestinationId"         => "33be0db8a99c1a03e01e7c6dd54dff26",
    "DestinationName"       => "Blah",
    "Destination"           => {
      "Id"    => "33be0db8a99c1a03e01e7c6dd54dff26",
      "Name"  => "Blah",
      "Type"  => "Dwolla",
      "Image" => ""
    },
    "SourceId"              => "812-742-8722",
    "SourceName"            => "Cafe Kubal",
    "Source"                => {
      "Id"    => "812-742-8722",
      "Name"  => "Cafe Kubal",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "ClearingDate"          => "2014-09-19T00:00:00Z",
    "Status"                => "pending",
    "Notes"                 => nil,
    "Fees"                  => nil,
    "OriginalTransactionId" => nil,
    "Metadata"              => nil
  },
  { ... },
  { ... }
]
[
   {
      "Id":328979,
      "Amount":10.01,
      "Date":"2014-09-09T04:49:41Z",
      "Type":"money_sent",
      "UserType":"Dwolla",
      "DestinationId":"812-232-2342",
      "DestinationName":"Joe Schmoe",
      "Destination":{
         "Id":"812-232-2342",
         "Name":"Joe Schmoe",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-232-2342"
      },
      "SourceId":"812-742-8722",
      "SourceName":"Cafe Kubal",
      "Source":{
         "Id":"812-742-8722",
         "Name":"Cafe Kubal",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-742-8722"
      },
      "ClearingDate":"",
      "Status":"processed",
      "Notes":"",
      "Fees":null,
      "OriginalTransactionId":null,
      "Metadata":null
  },
  { 
    ... 
  },
  { 
    ... 
  }
]
{
  "Success": true,
  "Message": "Success",
  "Response": [
    {
      "Id": 5569196,
      "Amount": 0.01,
      "Date": "2014-08-13T05:17:15Z",
      "Type": "money_sent",
      "UserType": "Email",
      "DestinationId": "ejfwefjwfk02022@gmail.com",
      "DestinationName": "ejfwefjwfk02022@gmail.com",
      "Destination": {
        "Id": "ejfwefjwfk02022@gmail.com",
        "Name": "ejfwefjwfk02022@gmail.com",
        "Type": "Email",
        "Image": ""
      },
      "SourceId": "812-687-7049",
      "SourceName": "Gordon Zheng",
      "Source": {
        "Id": "812-687-7049",
        "Name": "Gordon Zheng",
        "Type": "Dwolla",
        "Image": "https://dwolla-avatars.s3.amazonaws.com/812-687-7049/ac044552"
      },
      "ClearingDate": "",
      "Status": "cancelled",
      "Notes": "",
      "Fees": null,
      "OriginalTransactionId": null,
      "Metadata": null
    },
    ...
  ]
}

Retrieve the transaction history of the authenticated user.

HTTP Request

GET https://www.dwolla.com/oauth/rest/transactions

Example:

To get the latest 200 transactions of type money_sent, fee, and deposit:

GET https://www.dwolla.com/oauth/rest/transactions?types=money_sent,fee,deposit&limit=200

Request Parameters

Parameter Description
types Types of transactions to return. By default, all types returned. Possible values: money_sent, money_received, deposit, withdrawal, fee. Delimited by ,
limit Number of transactions to return. Max 200. Defaults to 10.
skip Number of transactions to skip.
sinceDate Earliest date and time for which to retrieve transactions. Must be ISO-8601 formatted. Example: 2014-08-13T21:05:23.797Z
endDate Latest date and time for which to retrieve transactions. Must be ISO-8601 formatted. Example: 2014-08-13T21:05:23.797Z

Errors

Error String Description
Invalid since date. Date specified to retrieve transactions is invalid
Invalid end date. Date specified to retrieve transactions is invalid
Invalid limit. Invalid number of transactions to return
Invalid skip. Invalid number of transactions to skip

List an app’s transactions

/**
 * Retrieve the 10 recentmost transactions which
 * have been facilitated by this application.
 */

Dwolla.transactionsByApp(function(err, data) {
  console.log(data);
});
<?php
$Transactions = new Dwolla\Transactions();
$Transactions->settings->client_id = $apiKey;
$Transactions->settings->client_secret = $apiSecret;

// set access token to null and get() will use key and secret
$Transactions->settings->oauth_token = null;

$result = $Transactions->get();

var_export($result);
?>
puts Dwolla::Transactions.get(nil, {}, false)
print(transactions.get())

Response:

array (
  0 =>
  array (
    'Id' => 346099,
    'Amount' => 5,
    'Date' => '2014-10-22T19:51:01Z',
    'Type' => 'deposit',
    'UserType' => 'Dwolla',
    'DestinationId' => '812-742-8722',
    'DestinationName' => 'Cafe Kubal',
    'Destination' =>
    array (
      'Id' => '812-742-8722',
      'Name' => 'Cafe Kubal',
      'Type' => 'Dwolla',
      'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
    ),
    'SourceId' => '33be0db8a99c1a03e01e7c6dd54dff26',
    'SourceName' => 'Blah',
    'Source' =>
    array (
      'Id' => '33be0db8a99c1a03e01e7c6dd54dff26',
      'Name' => 'Blah',
      'Type' => 'Dwolla',
      'Image' => '',
    ),
    'ClearingDate' => '2014-10-28T00:00:00Z',
    'Status' => 'pending',
    'Notes' => NULL,
    'Fees' => NULL,
    'OriginalTransactionId' => NULL,
    'Metadata' => NULL,
  ),
  1 =>
  array (
  ...
  ),
)
[
  {
    "Id"                    => 331506,
    "Amount"                => 15.25,
    "Date"                  => "2014-09-17T18:18:46Z",
    "Type"                  => "withdrawal",
    "UserType"              => "Dwolla",
    "DestinationId"         => "33be0db8a99c1a03e01e7c6dd54dff26",
    "DestinationName"       => "Blah",
    "Destination"           => {
      "Id"    => "33be0db8a99c1a03e01e7c6dd54dff26",
      "Name"  => "Blah",
      "Type"  => "Dwolla",
      "Image" => ""
    },
    "SourceId"              => "812-742-8722",
    "SourceName"            => "Cafe Kubal",
    "Source"                => {
      "Id"    => "812-742-8722",
      "Name"  => "Cafe Kubal",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "ClearingDate"          => "2014-09-19T00:00:00Z",
    "Status"                => "pending",
    "Notes"                 => nil,
    "Fees"                  => nil,
    "OriginalTransactionId" => nil,
    "Metadata"              => nil
  },
  { ... },
  { ... }
]
[
   {
      "Id":328979,
      "Amount":10.01,
      "Date":"2014-09-09T04:49:41Z",
      "Type":"money_sent",
      "UserType":"Dwolla",
      "DestinationId":"812-232-2342",
      "DestinationName":"Joe Schmoe",
      "Destination":{
         "Id":"812-232-2342",
         "Name":"Joe Schmoe",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-232-2342"
      },
      "SourceId":"812-742-8722",
      "SourceName":"Cafe Kubal",
      "Source":{
         "Id":"812-742-8722",
         "Name":"Cafe Kubal",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-742-8722"
      },
      "ClearingDate":"",
      "Status":"processed",
      "Notes":"",
      "Fees":null,
      "OriginalTransactionId":null,
      "Metadata":null
  },
  { 
    ... 
  },
  { 
    ... 
  }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Id": 5569196,
            "Amount": 0.01,
            "Date": "2014-08-13T05:17:15Z",
            "Type": "money_sent",
            "UserType": "Email",
            "DestinationId": "ejfwefjwfk02022@gmail.com",
            "DestinationName": "ejfwefjwfk02022@gmail.com",
            "Destination": {
                "Id": "ejfwefjwfk02022@gmail.com",
                "Name": "ejfwefjwfk02022@gmail.com",
                "Type": "Email",
                "Image": ""
            },
            "SourceId": "812-687-7049",
            "SourceName": "Gordon Zheng",
            "Source": {
                "Id": "812-687-7049",
                "Name": "Gordon Zheng",
                "Type": "Dwolla",
                "Image": "https://dwolla-avatars.s3.amazonaws.com/812-687-7049/ac044552"
            },
            "ClearingDate": "",
            "Status": "cancelled",
            "Notes": "",
            "Fees": null,
            "OriginalTransactionId": null,
            "Metadata": null
        },
        ...
    ]
}

List the transactions which your application has created / facilitated.

HTTP Request

GET https://www.dwolla.com/oauth/rest/transactions?client_id={}&client_secret={}

Example:

To get the latest 200 transactions of type money_sent, fee, and deposit:

GET https://www.dwolla.com/oauth/rest/transactions?types=money_sent,fee,deposit&limit=200

Request Parameters

Parameter Description
client_id Application key
client_secret Application secret
types Types of transactions to return. By default, all types returned. Possible values: money_sent, money_received, deposit, withdrawal, fee. Delimited by ,
limit Number of transactions to return. Max 200. Defaults to 10.
skip Number of transactions to skip.
sinceDate Earliest date and time for which to retrieve transactions. Must be ISO-8601 formatted. Example: 2014-08-13T21:05:23.797Z
endDate Latest date and time for which to retrieve transactions. Must be ISO-8601 formatted. Example: 2014-08-13T21:05:23.797Z

Get a specific transaction

/**
 * Retrieve transaction ID '12345'
 */

Dwolla.transactionById('12345', function(err, data) {
  console.log(data);
});
#   Retrieve a transaction by ID
puts Dwolla::Transactions.get(331506)
# Get info for transaction ID 123456
print(transactions.info('123456'))
<?php
$Transactions = new Dwolla\Transactions();

// you may provide key and secret...
$Transactions->settings->client_id = $apiKey;
$Transactions->settings->client_secret = $apiSecret;

// OR an access token... 
$Transactions->settings->oauth_token = "foo";

$result = $Transactions->info('346099');

var_export($result);
?>

Response:

array (
  'Id' => 346099,
  'Amount' => 5,
  'Date' => '2014-10-22T19:51:01Z',
  'Type' => 'deposit',
  'UserType' => 'Dwolla',
  'DestinationId' => '812-742-8722',
  'DestinationName' => 'Cafe Kubal',
  'Destination' =>
  array (
    'Id' => '812-742-8722',
    'Name' => 'Cafe Kubal',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
  ),
  'SourceId' => '33be0db8a99c1a03e01e7c6dd54dff26',
  'SourceName' => 'Blah',
  'Source' =>
  array (
    'Id' => '33be0db8a99c1a03e01e7c6dd54dff26',
    'Name' => 'Blah',
    'Type' => 'Dwolla',
    'Image' => '',
  ),
  'ClearingDate' => '2014-10-28T00:00:00Z',
  'Status' => 'pending',
  'Notes' => NULL,
  'Fees' => NULL,
  'OriginalTransactionId' => NULL,
  'Metadata' => NULL,
)
Return:
    {
        "Id": 123456,
        "Amount": 5.50,
        "Date": "2014-12-13T05:07:15Z",
        "Type": "money_sent",
        "UserType": "Email",
        "DestinationId": "812-197-4121",
        "DestinationName": "Some Name",
        "Destination": {
            "Id": "812-197-4121",
            "Name": "Some Name",
            "Type": "dwolla",
            "Image": ""
        },
        "SourceId": "812-202-3784",
        "SourceName": "David Stancu",
        "Source": {
            "Id": "812-202-3784",
            "Name": "David Stancu",
            "Type": "Dwolla",
            "Image": "https://dwolla-avatars.s3.amazonaws.com/812-202-3784/ac045522"
        },
        "ClearingDate": "",
        "Status": "cancelled",
        "Notes": "",
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null
    }
{
    "Id"                    => 331506,
    "Amount"                => 15.25,
    "Date"                  => "2014-09-17T18:18:46Z",
    "Type"                  => "withdrawal",
    "UserType"              => "Dwolla",
    "DestinationId"         => "33be0db8a99c1a03e01e7c6dd54dff26",
    "DestinationName"       => "Blah",
    "Destination"           => {
      "Id"    => "33be0db8a99c1a03e01e7c6dd54dff26",
      "Name"  => "Blah",
      "Type"  => "Dwolla",
      "Image" => ""
    },
    "SourceId"              => "812-742-8722",
    "SourceName"            => "Cafe Kubal",
    "Source"                => {
      "Id"    => "812-742-8722",
      "Name"  => "Cafe Kubal",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "ClearingDate"          => "2014-09-19T00:00:00Z",
    "Status"                => "pending",
    "Notes"                 => nil,
    "Fees"                  => nil,
    "OriginalTransactionId" => nil,
    "Metadata"              => nil
  }
{
      "Id":328979,
      "Amount":10.01,
      "Date":"2014-09-09T04:49:41Z",
      "Type":"money_sent",
      "UserType":"Dwolla",
      "DestinationId":"812-232-2342",
      "DestinationName":"Joe Schmoe",
      "Destination":{
         "Id":"812-232-2342",
         "Name":"Joe Schmoe",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-232-2342"
      },
      "SourceId":"812-742-8722",
      "SourceName":"Cafe Kubal",
      "Source":{
         "Id":"812-742-8722",
         "Name":"Cafe Kubal",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-742-8722"
      },
      "ClearingDate":"",
      "Status":"processed",
      "Notes":"",
      "Fees":null,
      "OriginalTransactionId":null,
      "Metadata":null
  }
{
  "Success": true,
  "Message": "Success",
  "Response": {
    "Id": 331506,
    "Amount": 15.25,
    "Date": "2014-09-17T18:18:46Z",
    "Type": "withdrawal",
    "UserType": "Dwolla",
    "DestinationId": "33be0db8a99c1a03e01e7c6dd54dff26",
    "DestinationName": "Blah",
    "Destination": {
      "Id": "33be0db8a99c1a03e01e7c6dd54dff26",
      "Name": "Blah",
      "Type": "Dwolla",
      "Image": ""
    },
    "SourceId": "812-742-8722",
    "SourceName": "Cafe Kubal",
    "Source": {
      "Id": "812-742-8722",
      "Name": "Cafe Kubal",
      "Type": "Dwolla",
      "Image": "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "ClearingDate": "2014-09-19T00:00:00Z",
    "Status": "pending",
    "Notes": null,
    "Fees": null,
    "OriginalTransactionId": null,
    "Metadata": null
  }
}

Look up a particular transaction by its ID (Either Sender’s or Recipient’s. Read about transaction IDs here.) Either an OAuth access token can be supplied, or if your API application facilitated this transaction, you can supply an application key and secret instead.

HTTP Request

To fetch a transaction which belongs to the authorized user:

GET https://www.dwolla.com/oauth/rest/transactions/{id}

or to fetch a transaction which belongs to an application:

GET https://www.dwolla.com/oauth/rest/transactions/{id}?client_id={}&client_secret={}

Errors

Error String Description
Invalid transaction ID. The specified transaction ID is empty, missing, or invalid.
Transaction not found for account. Could not find a transaction with the specified ID for the given OAuth token.

Search transactions

GET https://www.dwolla.com/oauth/rest/transactions/search?limit=20

Response:

{
  "Success": true,
  "Message": "Success",
  "Response": {
    "TotalHits": 13502,
    "Results": [
      {
        "Id": 346099,
        "Amount": 5,
        "Date": "2014-10-22T19:51:01Z",
        "Type": "deposit",
        "UserType": "Dwolla",
        "DestinationId": "812-742-8722",
        "DestinationName": "Cafe Kubal",
        "Destination": {
          "Id": "812-742-8722",
          "Name": "Cafe Kubal",
          "Type": "Dwolla",
          "Image": "http://www.dwolla.com/avatars/812-742-8722"
        },
        "SourceId": "33be0db8a99c1a03e01e7c6dd54dff26",
        "SourceName": "Blah",
        "Source": {
          "Id": "33be0db8a99c1a03e01e7c6dd54dff26",
          "Name": "Blah",
          "Type": "Dwolla",
          "Image": ""
        },
        "ClearingDate": "2014-10-28T00:00:00Z",
        "Status": "pending",
        "Notes": null,
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null
      },

      { ... }
    ]
  }
}

Search a user’s transactions, filtering results based on an amount range, date range, transaction type, transaction status, individual’s name, business name, Dwolla ID, email address, or phone number.

HTTP Request

To fetch a transaction which belongs to the authorized user:

GET https://www.dwolla.com/oauth/rest/transactions/search?limit={}

Optional Querystring Parameters

Parameter Description
searchTerm A string to be matched with recipient/sender names (individual or business/organizaton), Dwolla ID, email address, or phone number.
startAmount Only include transactions with an amount equal to or greater than startAmount. Can optionally be used with endAmount to specify an amount range.
endAmount Only include transactions with an amount equal to or less than endAmount. Can optionally be used with startAmount to specify an amount range.
startDate 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 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.
type Filter results on Transaction type. Possible values: money_sent, money_received, deposit, withdraw
status Filter results on Transaction status. Possible values: pending, processed, failed, reclaimed, cancelled
limit Number of search results to return. Defaults to 50.
offset Number of search results to skip. Used for pagination.

Response

Parameter Description
TotalHits Total number of search results. Does not necessarily equal the number of results contained in the response Results.
Results JSON array of Transaction resources.

Scheduled Payments

        _____
     _.'_____`._
   .'.-'  12 `-.`.
  /,' 11      1 `.\
 // 10      /   2 \\
;;         /       ::
|| 9  ----O      3 ||
::                 ;;
 \\ 8           4 //
  \`. 7       5 ,'/
   '.`-.__6__.-'.'
    ((-._____.-))
    _))       ((_
   '--'SSt    '--'

{
  "Id": "3bfaf7fb-b5e9-4a6e-ab09-1ef30d30bbef",
  "ScheduledDate": "2014-09-13",
  "ExpectedClearingDate": "2014-09-18",
  "TransactionId": null,
  "Amount": 10,
  "FundingSource": "3eacc3e3f6da404aa5735911219f277",
  "Destination": {
      "Id": "812-111-1111",
      "Name": "Jane Doe",
      "Type": "Dwolla",
      "Image": "http://uat.dwolla.com/avatars/812-111-1111"
  },
  "Notes": "This is a scheduled payment",
  "Status": "scheduled",
  "CreatedDate": "2014-09-12T20:37:37Z",
  "Metadata": {
    "foo": "bar"
  }
}

Payments can be scheduled to be created at a future date, up to 3 years into the future. When a Scheduled Payment is created, no transaction is created (and thus, no funds are transferred) until the ScheduledDate.

Scheduled Payments can be one-time or recurring. Options for recurring payments are flexible. You can create a recurring payment that pays weekly, monthly, daily, or every 2 weeks, every week on Tuesdays and Fridays, every 12th and 18th and 26th each month, and so on.

If there is an error creating the transaction, the Scheduled Payment will have a Status of failed. Only bank-sourced payments are supported at this time.

Scheduled Payment Resource

Property Description
Id A unique ID for the scheduled payment
ScheduledDate Date when transaction will be created. Must be within 3 years from when the scheduled payment was created. Format: YYYY-MM-DD
ExpectedClearingDate Estimated date when the funds will be available to the recipient. Typically 1-3 business days after the ScheduledDate.
TransactionId Transaction ID of resulting Transaction. null until the transaction is successfully created.
Amount Amount of the transaction to be created.
FundingSource ID of the bank funding source which will fund the transaction
AssumeCosts Boolean. Deprecated.
Destination JSON object describing the recipient. Id is the recipient’s Dwolla ID or email address, Name is the recipient’s full name, Type is either Dwolla or Email and Image is a URL to the recipient’s avatar, if the recipient is an existing Dwolla user.
Notes Optional notes field. Max 250 chars.
Status Possible values: ‘scheduled’, 'processed’, 'failed’
Metadata JSON object with max 10 key-value pairs. Keys and values are strings of max length 255. Omitted if null, if not provided, or visible to application. Read more

Create Scheduled Payment

{
  "amount":10,
  "destinationId":"812-114-7461",
  "destinationType":"Dwolla",
  "fundsSource":"33be0db8a99c1a03e01e7c6dd54dff26",
  "notes":"Weekly recurring membership",
  "pin":"7890",
  "scheduleDate":"2015-05-04",
  "metadata":{
    "foo": "bar",
    "bar": "baz"
  },
  "recurrence":{
    "frequency":"weekly",
    "onDays":"2"
  }
}
/**
 * Send $300 to a Dwolla ID,
 * on 2018-01-01, from funding source with ID
 * "ashfdjh8f9df89"
 */
print_r($Transactions->schedule('812-197-4121', 300, '2018-01-01', 'ashfdjh8f9df89'));
/**
 * Schedule a payment for 300 on 2015-09-09 to 812-111-1234
 */

Dwolla.schedule(cfg.pin, '812-111-1234', 300, '2015-09-09', function(err, data) {
  if (err) {console.log(err);}
  console.log(data);
});
#   Send money ($1.00) to a Dwolla ID
#   on 2015-09-09 from funding source "abcdef"
pp Dwolla::Transactions.schedule({
                                :pin => @pin,
                                :amount => 1.00,
                                :destinationId => '812-111-1111',
                                :fundsSource => 'abcdef',
                                :scheduleDate => '2015-09-09'}) 
# Schedule a payment for 2018-01-01 with
# amount $300

print(transactions.schedule('812-111-1111', 300, '2018-01-01', '5da016f7769bcc1de9998a30d194d5a7'))

Response:

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "876a72fb-e817-4bec-a781-a97b1c41091e",
        "ScheduledDate": "2015-05-04",
        "ExpectedClearingDate": "2015-05-07",
        "Amount": 10,
        "FundingSource": "33be0db8a99c1a03e01e7c6dd54dff26",
        "Destination": {
            "Id": "812-114-7461",
            "Name": "WidgetCorp",
            "Type": "Dwolla",
            "Image": "https://uat.dwolla.com/avatars/812-114-7461/dec1fee7"
        },
        "Notes": "Weekly recurring membership",
        "Status": "scheduled",
        "CreatedDate": "2015-05-01T19:51:30Z",
        "Metadata": {
            "foo": "bar",
            "bar": "baz"
        },
        "Recurrence": {
            "Frequency": "Weekly",
            "RepeatEvery": 1,
            "OnDays": "2",
            "NextRunDate": "2015-05-04",
            "Status": "Enabled"
        }
    }
}

Create a new Scheduled Payment on behalf of the authorized user. Initial Status will be scheduled. Must fund payment with a bank-funding source. Allows scheduling of a one-time payment, or recurring payments with use of the recurrence object.

HTTP Request

POST https://www.dwolla.com/oauth/rest/transactions/scheduled

Parameter Optional? Description
amount Amount of transaction. Must be within the sender’s account transaction limit.
destinationId Recipient’s Dwolla ID or email address.
destinationType yes Recipient type: Dwolla or Email. Must set this to Email if you provided an email as the destinationId.
pin Sender’s account PIN
fundsSource ID of the Funding Source to fund this payment.
scheduleDate Date to initiate payment. If the transaction is funded by an ACH bank funding source, funds will be available to the recipient typically 1-3 business days after this date.
recurrence yes A recurrence JSON object. See below
assumeCosts yes Boolean. Deprecated.
notes yes Optional note to attach to transaction. Max 250 chars.
metadata yes Optional JSON object of a maximum of 10 key-value pairs (each key and value must be less than 255 characters). Read more

Recurrence Object

Parameter Optional? Description
frequency Either weekly or monthly.
endDate yes Date at which to stop the recurrence.
endAfter yes Stop the recurrence after this many payments
repeatEvery yes Defaults to 1. For example a frequency of weekly and repeatEvery set to 2 would mean “pay every 2 weeks”.
onDays Day of the week or day of the month to initiate payments. Valid values for weekly are 1-7, where 1 is Sunday and 7 is Saturday. For monthly, valid values are 1-31 and -1. -1 is relative, indicating the last day of the month. If you use 29, 30, or 31 and the month doesn’t have that day, it will initiate on the last day of the month. You can also pass combinations of days. weekly with onDays = 1,2,3,4,5,6,7 would initiate a payment every day of the week. For monthly, you are not able to combine 28,29,30,31 and/or -1 as this would cause an overlap.

Errors

Error String Description
Invalid account PIN The supplied PIN is invalid or incorrect.
There was an error scheduling the transaction at this time. There was an error scheduling this transaction
Invalid funding source. The specified funding source doesn’t exist or is invalid.
Funding source must be a bank. The specified funding source must be a bank
Notes length is too long. Maximum of 250 character is allowed. The 'notes’ length is too long.
This user is unable to receive transactions from provided funding source. The destination user is unable to receive funds from specified funding source

List Scheduled Payments

/**
 * Get all scheduled payments
 */
print_r($Transactions->scheduled());
/**
 * Get all scheduled payments.
 */
Dwolla.scheduled(function(err, data) {
  if (err) {console.log(err);}
  console.log(data);
});
#  Get all scheduled payments
pp Dwolla::Transactions.scheduled() 
# Get all scheduled payments
print(transactions.scheduled())
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Total": 3,
        "Count": 3,
        "Results": [{
            "Id": "62dc6dcb-cc88-476f-a5c9-ce20e4d9d5af",
            "ScheduledDate": "2015-05-04",
            "ExpectedClearingDate": "2015-05-07",
            "Amount": 5,
            "FundingSource": "33be0db8a99c1a03e01e7c6dd54dff26",
            "Destination": {
                "Id": "812-114-7461",
                "Name": "WidgetCorp",
                "Type": "Dwolla",
                "Image": "https://uat.dwolla.com/avatars/812-114-7461/dec1fee7"
            },
            "Notes": "Daily recurring membership",
            "Status": "scheduled",
            "CreatedDate": "2015-05-01T19:35:04Z",
            "Recurrence": {
                "Frequency": "Weekly",
                "RepeatEvery": 1,
                "OnDays": "1,2,3,4,5,6,7",
                "NextRunDate": "2015-05-04",
                "Status": "Enabled"
            }
        }, {
            "Id": "c9cb400b-bb58-4d63-b000-662e93d22119",
            "ScheduledDate": "2015-05-04",
            "ExpectedClearingDate": "2015-05-07",
            "Amount": 10,
            "FundingSource": "33be0db8a99c1a03e01e7c6dd54dff26",
            "Destination": {
                "Id": "812-114-7461",
                "Name": "WidgetCorp",
                "Type": "Dwolla",
                "Image": "https://uat.dwolla.com/avatars/812-114-7461/dec1fee7"
            },
            "Notes": "Weekly recurring membership",
            "Status": "scheduled",
            "CreatedDate": "2015-05-01T19:30:17Z",
            "Recurrence": {
                "Frequency": "Weekly",
                "RepeatEvery": 1,
                "OnDays": "2",
                "NextRunDate": "2015-05-04",
                "Status": "Enabled"
            }
        }, {
            "Id": "35921635-aeb4-4c83-b730-6b61b1749127",
            "ScheduledDate": "2015-06-01",
            "ExpectedClearingDate": "2015-06-04",
            "Amount": 900,
            "FundingSource": "33be0db8a99c1a03e01e7c6dd54dff26",
            "Destination": {
                "Id": "812-114-7461",
                "Name": "WidgetCorp",
                "Type": "Dwolla",
                "Image": "https://uat.dwolla.com/avatars/812-114-7461/dec1fee7"
            },
            "Notes": "Rent payment",
            "Status": "scheduled",
            "CreatedDate": "2015-05-01T19:57:50Z",
            "Metadata": {
                "foo": "bar",
                "bar": "baz"
            }
        }]
    }
}

List the authorized user’s scheduled payments which have been created by your application.

HTTP Request

GET https://www.dwolla.com/oauth/rest/transactions/scheduled?limit=10

Optional Parameters

Parameter Description
status Filter scheduled payments by their status. Possible values: scheduled, processed, failed.
limit Pagination: number of results to return.
skip Pagination: number of results to skip.
fundingSource Show only scheduled payments funded by a given funding source ID.

Response

Parameter Description
Total Total number of query results
Count Number of query results included in response. Can be less than Total, if paginating with limit set in query.
Results JSON array of Scheduled Payments

Retrieve Scheduled Payment

/**
 * Get scheduled payment with ID
 * 'd72b9f82-307e-4a35-9559-7889ea929db7'
 */
print_r($Transactions->scheduledById('d72b9f82-307e-4a35-9559-7889ea929db7'));
/**
 * Get scheduled payment with ID 'd72b9f82-307e-4a35-9559-7889ea929db7'
 */
Dwolla.scheduledById('d72b9f82-307e-4a35-9559-7889ea929db7', function(err, data) {
  if (err) {console.log(err);}
  console.log(data);
});
#   Get scheduled payment with ID
#   'd72b9f82-307e-4a35-9559-7889ea929db7'
pp Dwolla::Transactions.scheduled_by_id('d72b9f82-307e-4a35-9559-7889ea929db7') 
# Get scheduled payment with 
# ID 'd72b9f82-307e-4a35-9559-7889ea929db7'
print transactions.scheduledbyid('d72b9f82-307e-4a35-9559-7889ea929db7')
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "d72b9f82-307e-4a35-9559-7889ea929db7",
        "ScheduledDate": "2014-09-11",
        "ExpectedClearingDate": "2014-09-16",
        "TransactionId": 330295,
        "Amount": 100,
        "FundingSource": "3eacc3e3f6da404aa5735911219f277",
        "Destination": {
            "Id": "812-111-1111",
            "Name": "Jane Doe",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-111-1111"
        },
        "Notes": "This is a scheduled",
        "Status": "processed",
        "CreatedDate": "2014-09-10T21:05:39Z"
    }
}

Retrieve a scheduled payment by its ID.

HTTP Request

GET https://www.dwolla.com/oauth/rest/transactions/scheduled/{id}

Edit Scheduled Payment

Edit the amount:

{
  "pin": 9999,
  "amount": 16
}
/**
 * Edit scheduled payment with ID
 * '08f9b638-0f8e-4e00-abe5-41c8fd24fbe8' to reflect amount 16
 */
print_r($Transactions->editScheduled('08f9b638-0f8e-4e00-abe5-41c8fd24fbe8', ['amount' => 16]));
/**
 * Edit scheduled payment with ID '08f9b638-0f8e-4e00-abe5-41c8fd24fbe8' 
 * to specify a new amount of 16
 */
Dwolla.editScheduled('08f9b638-0f8e-4e00-abe5-41c8fd24fbe8', cfg.pin, {amount: 16}, {function(err, data) {
  if (err) {console.log(err);}
  console.log(data);
});
#   Edit scheduled payment with ID 
#   '08f9b638-0f8e-4e00-abe5-41c8fd24fbe8' to have new amount 16
pp Dwolla::Transactions.edit_scheduled_by_id('08f9b638-0f8e-4e00-abe5-41c8fd24fbe8', {:amount => 16})
# Edit scheduled payment with ID
# '08f9b638-0f8e-4e00-abe5-41c8fd24fbe8' to reflect amount 16
print transactions.editscheduledbyid('08f9b638-0f8e-4e00-abe5-41c8fd24fbe8', {'amount': 16})

Response:

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "08f9b638-0f8e-4e00-abe5-41c8fd24fbe8",
        "ScheduledDate": "2014-09-11",
        "ExpectedClearingDate": "2014-09-16",
        "TransactionId": null,
        "Amount": 16,
        "FundingSource": "3eacc3e3f6da404aa5735911219f277",
        "Destination": {
            "Id": "812-111-1111",
            "Name": "Jane Doe",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-111-1111"
        },
        "Notes": "This is a scheduled test update",
        "Status": "scheduled",
        "CreatedDate": "2014-09-10T18:28:20Z"
    }
}

Edit an existing scheduled payment. Partial editing is allowed: just supply the field(s) to change, along with the sender’s PIN.

Note: the recurrence field cannot be modified. If you need to change the recurrence of a scheduled payment, delete it and create a new one.

HTTP Request

PUT https://www.dwolla.com/oauth/rest/transactions/scheduled/{id}

Parameter Optional? Description
pin required Sender’s account PIN
amount yes Amount of payment. Must be within the sender’s account transaction limit.
destinationId yes Recipient’s Dwolla ID or email address.
destinationType yes Recipient type: Dwolla or Email. Must set this to Email if you provided an email as the destinationId.
fundsSource yes ID of the Funding Source to fund this payment.
scheduleDate yes Date to initiate payment. If the payment is funded by an ACH bank funding source, funds will be available to the recipient typically 1-3 business days after this date.
assumeCosts yes Boolean. Deprecated.
notes yes Optional note to attach to transaction. Max 250 chars.

Errors

Error String Description
Transaction has already been processed. Unable to edit a transaction that has alredy been processed
There was an error updating the scheduled payment. Error occured when updating the scheduled payment

Delete Scheduled Payment

DELETE https://www.dwolla.com/oauth/rest/transactions/scheduled/d856d2ec-4098-4b3b-b20f-b2561ec85871?pin={PIN}
/**
 * Delete scheduled payment with ID
 * 'd856d2ec-4098-4b3b-b20f-b2561ec85871'
 */
print_r($Transactions->deleteScheduledById('d856d2ec-4098-4b3b-b20f-b2561ec85871'));
/**
 * Delete scheduled payment with ID 'd856d2ec-4098-4b3b-b20f-b2561ec85871'
 */
Dwolla.deleteScheduledById('d856d2ec-4098-4b3b-b20f-b2561ec85871', function(err, data) {
  if (err) {console.log(err);}
  console.log(data);
});
#   Delete the scheduled payment with ID 
#   'd856d2ec-4098-4b3b-b20f-b2561ec85871' 
pp Dwolla::Transactions.delete_scheduled_by_id('d856d2ec-4098-4b3b-b20f-b2561ec85871', {:pin => @pin})
# Delete scheduled payment with ID
# 'd856d2ec-4098-4b3b-b20f-b2561ec85871'
print transactions.deletescheduledbyid('d856d2ec-4098-4b3b-b20f-b2561ec85871')

If successful, response contains the ID of the deleted scheduled payment:

{
    "Success": true,
    "Message": "Success",
    "Response": "d856d2ec-4098-4b3b-b20f-b2561ec85871"
}

Delete a pending scheduled payment created by your application. Status must be scheduled. Cannot delete a processed or failed scheduled payment.

HTTP Request

DELETE https://www.dwolla.com/oauth/rest/transactions/scheduled/{id}?pin={PIN}

Querystring params

Parameter Description
pin User’s PIN

Errors

Error String Description
Scheduled transaction must not have been processed to delete. The scheduled payment must be deleted before the ScheduleDate
There was an error deleting the scheduled payment. Generic error. If you’re not sure why this happened, contact us.

Delete all Scheduled Payments

DELETE https://www.dwolla.com/oauth/rest/transactions/scheduled?pin={PIN}
/**
 * Delete all scheduled payments
 */
print_r($Transactions->deleteAllScheduled());
/**
 * Delete all scheduled payments.
 */
Dwolla.deleteAllScheduled(function(err, data) {
  if (err) {console.log(err);}
  console.log(data);
});
#   Delete all scheduled payments 
pp Dwolla::Transactions.delete_all_scheduled({:pin => @pin})
# Delete all scheduled payments
print transactions.deleteallscheduled()

If successful, response contains JSON array of IDs of scheduled payments deleted:

{
  "Success": true,
  "Message": "Success",
  "Response": [
    "09e66fa3-1542-40b0-8143-67f72c75ae77",
    "1646c924-c6e0-46f1-b33d-5b999b408cab",
    "48c93710-5cb0-424b-b0b0-3a692a0ba840"
  ]
}

Delete all of an authorized user’s pending scheduled payments created by your application. Will not delete any processed or failed scheduled payments.

HTTP Request

DELETE https://www.dwolla.com/oauth/rest/transactions/scheduled?pin={PIN}

Querystring params

Parameter Description
pin User’s PIN

Transaction Stats

/**
 * Retrieve transaction statistics for the 
 * authorized user.
 */

Dwolla.transactionsStats(function(err, data){
  console.log(data);
});
puts Dwolla::Transactions.stats()
<?php
$Transactions = new Dwolla\Transactions();
$Transactions->settings->oauth_token = "foo";

$result = $Transactions->stats();

var_export($result);
?>
print(transactions.stats())

Response:

{
  "TransactionsCount" => 10,
  "TransactionsTotal" => 134.22
}
{
    "TransactionsCount": 5,
    "TransactionsTotal": 116.92
}
{
  "TransactionsCount": 5,
  "TransactionsTotal": 116.92
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "TransactionsCount": 5,
        "TransactionsTotal": 116.92
    }
}
array (
  'TransactionsCount' => 5,
  'TransactionsTotal' => 116.21,
)

Transaction statistics can be retrieved for the authenticated user. Currently, the report contains a count of transactions and sum of transactions over a given period of time.

HTTP Request

GET https://www.dwolla.com/oauth/rest/transactions/stats

Request Parameters

Parameter Optional? Description
startDate yes Starting date and time for which to select transactions for report. Defaults to 0300 UTC, today.
endDate yes Ending date and time for which to select transactions for report. Defaults to current date and time.

Errors

Error String Description
Invalid start date format. Should follow format of yyyy-mm-dd
Invalid end date format. Should follow format of yyyy-mm-dd

Users

USERS!

 o   \ o /  _ o         __|    \ / 
/|\    |     /\   ___\o   \o    |  
/ \   / \   | \  /)  |    ( \  /o\ 

- "Tonja Hickey"

Dwolla users can be looked up via the API.

Account Types

Type Description
Personal Account belonging to an individual. Default transaction limit of $5000.
Commercial Merchant/business account. Default transaction limit of $10000.
NonProfit Account belonging to a non-profit organization. Default transaction limit of $10000.

Get Basic Account Info

/**
 *   Fetch basic account information
 *   for a given Dwolla ID
 **/

<?php

$Account = new Dwolla\Account();
$Account->settings->client_id = $apiKey;
$Account->settings->client_secret = $apiSecret;

$result = $Account->basic('812-121-7199');
var_export($result);
?>
#   Fetch basic account information
#   for a given email address
puts Dwolla::Users.get('gordon@dwolla.com')
# Fetch basic information for a user via their Dwolla ID
print(accounts.basic('812-202-3784'))
/**
 *   Fetch basic account information
 *   for a given Dwolla ID (or email)
 **/

Dwolla.basicAccountInfo('812-546-3855', function(err, data) {
    console.log(data);
});

If successful, you’ll receive this response:

array (
  'Id' => '812-121-7199',
  'Name' => 'David Stancu',
  'Latitude' => 0,
  'Longitude' => 0,
)
{
  "Id"        => "812-742-3301",
  "Name"      => "Gordon Zheng",
  "Latitude"  => 0,
  "Longitude" => 0
}
{u'Latitude': 0, u'Id': u'812-202-3784', u'Longitude': 0, u'Name': u'David Stancu'}
{
    "Id": "812-111-1111",
    "Latitude": 0,
    "Longitude": 0,
    "Name": "Joe Schmoe"
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "812-111-1111",
        "Latitude": 41.584546,
        "Longitude": -93.634167,
        "Name": "Test User"
    }
}

Retrieve basic information about any Dwolla user, given their Dwolla ID or email address.

HTTP Request

GET https://www.dwolla.com/oauth/rest/users/{account_identifier}?client_id={}&client_secret={}

account_identifier must be a Dwolla ID or email address.

Example

To lookup the user with email gordon@dwolla.com:

GET https://www.dwolla.com/oauth/rest/users/gordon@dwolla.com?client_id={}&client_secret={}

Response

Parameter Description
Id User’s Dwolla ID
Latitude If this is a business account, latitude of the account’s location. Otherwise, always 0 for individual accounts.
Longitude If this is a business account, longitude of the account’s location. Otherwise, always 0 for individual accounts.
Name Full account name (or business name for a business account)

Errors

Error String Description
Invalid account identifier. Could not find an account with the specified ID.

Get Full Account Info

/**
 *   Fetch account information for the
 *   account associated with the provided
 *   OAuth access token
 **/
<?php
$Account = new Dwolla\Account();
$Account->settings->oauth_token = "foo";

$result = $Account->full();

var_export($result);
?>
#   Fetch account information for the
#   authorized user
puts Dwolla::Users.get
# Print FULL account information for the user associated with the currently set OAuth token.
print(accounts.full())
/**
 *   Fetch account information for the
 *   authorized user
 **/

Dwolla.fullAccountInfo(function(err, data) {
    console.log(data);
});

If successful, you’ll receive this response:

{
  "City"      => "Test",
  "State"     => "NY",
  "Type"      => "Commercial",
  "Id"        => "812-742-8722",
  "Name"      => "Cafe Kubal",
  "Latitude"  => 41.58975983,
  "Longitude" => -93.61564636
}
{u'City': u'New York', u'Name': u'David Stancu', u'Longitude': 0, u'State': u'NY', u'Latitude': 0, u'Type': u'Personal', u'Id': u'812-202-3784'}
{
    "City": "Des Moines",
    "Id": "812-111-1111",
    "Latitude": 41.584546,
    "Longitude": -93.634167,
    "Name": "Test User",
    "State": "IA",
    "Type": "Personal"
}
array (
  'City' => 'Test',
  'State' => 'NY',
  'Type' => 'Commercial',
  'Id' => '812-742-8722',
  'Name' => 'Cafe Kubal',
  'Latitude' => -1,
  'Longitude' => -1,
)
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "City": "Des Moines",
        "Id": "812-111-1111",
        "Latitude": 41.584546,
        "Longitude": -93.634167,
        "Name": "Test User",
        "State": "IA",
        "Type": "Personal"
    }
}

Retrieve information about the authorized user.

HTTP Request

GET https://www.dwolla.com/oauth/rest/users/

Response

Parameter Description
Id User’s Dwolla ID
Latitude If this is a business account, latitude of the account’s location. Otherwise, always 0 for individual accounts.
Longitude If this is a business account, longitude of the account’s location. Otherwise, always 0 for individual accounts.
Name Full account name (or business name for a business account)
City User’s home city
State User’s home state
Type Personal or Commercial

Get Avatar

GET https://www.dwolla.com/avatars/812-713-9234

Retrieve the avatar image for a Dwolla user, given their Dwolla ID. This requires no authentication and will return a 220px x 220px PNG file.

HTTP Request

GET https://www.dwolla.com/avatars/{dwolla_id}

Find Nearby Businesses

<?php
$Contacts = new Dwolla\Contacts();
$Contacts->settings->client_id = $apiKey;
$Contacts->settings->client_secret = $apiSecret;

$lat = "41.585";
$long = "-93.624";

$result = $Contacts->nearby($lat, $long);

var_export($result);
?>
#   Get a list of nearby Dwolla spots
#   for a given set of coordinates (lat, long)
pp Dwolla::Contacts.nearby(41.58975983, -93.61564636)
# Fetch Dwolla spots near 40.7127, 74.0059
print(contacts.nearby(40.7127, 74.0059))
/**
 * Fetch all spots near lat 41.585 and 
 * long -93.624
 **/

Dwolla.nearby('41.585', '-93.624', function(err, data){
   console.log(data);
});

If successful, you’ll receive this response:

array (
  0 =>
  array (
    'Name' => 'Alan\'s Brew',
    'Id' => '812-198-4099',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-198-4099',
    'Latitude' => 41.582946999999997,
    'Longitude' => -93.622444000000002,
    'Address' => '333 SW 5th st',
    'City' => 'Des Moines\n',
    'State' => 'IA',
    'PostalCode' => '50309',
    'Group' => '812-198-4099',
    'Delta' => 0.0036089999999973088,
  ),
  1 =>
  array (
    'Name' => 'Rocket Gear',
    'Id' => '812-742-6826',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-6826',
    'Latitude' => 41.589759829999998,
    'Longitude' => -93.61564636,
    'Address' => '123 Test Ave\n',
    'City' => 'Des Moines',
    'State' => 'IA',
    'PostalCode' => '50169',
    'Group' => '812-742-6826',
    'Delta' => 0.013113469999993299,
  )
)
    [
       {
           "Name": "ThelmasTreats",
           "Id": "812-608-8758",
           "Type": "Dwolla",
           "Image": "https://www.dwolla.com/avatars/812-608-8758",
           "Latitude": 41.590043,
           "Longitude": -93.62095,
           "Address": "615 3rd Street\n",
           "City": "Des Moines",
           "State": "IA",
           "PostalCode": "50309",
           "Group": "812-608-8758",
           "Delta": 0.0009069999999908873
       },
       {
           "Name": "IKONIX Studio",
           "Id": "812-505-4939",
           "Type": "Dwolla",
           "Image": "https://www.dwolla.com/avatars/812-505-4939",
           "Latitude": 41.5887958,
           "Longitude": -93.6215057,
           "Address": "506 3rd St\nSuite 206",
           "City": "Des Moines",
           "State": "IA",
           "PostalCode": "50309",
           "Group": "812-505-4939",
           "Delta": 0.0027098999999992657
   }
]
[
  {
    "Name"       => "Rocket Gear",
    "Id"         => "812-742-6826",
    "Type"       => "Dwolla",
    "Image"      => "http://uat.dwolla.com/avatars/812-742-6826",
    "Latitude"   => 41.58975983,
    "Longitude"  => -93.61564636,
    "Address"    => "123 Test Ave\n",
    "City"       => "Des Moines",
    "State"      => "IA",
    "PostalCode" => "50169",
    "Group"      => "812-742-6826",
    "Delta"      => 0.0045938100000100235
  },
  {
    "Name"       => "Alan's Brew",
    "Id"         => "812-198-4099",
    "Type"       => "Dwolla",
    "Image"      => "http://uat.dwolla.com/avatars/812-198-4099",
    "Latitude"   => 41.582947,
    "Longitude"  => -93.622444,
    "Address"    => "120 SW 5th st\n",
    "City"       => "Des Moines",
    "State"      => "IA",
    "PostalCode" => "50309",
    "Group"      => "812-198-4099",
    "Delta"      => 0.009497000000003197
  },
  { ... }
]
[
  {
    "Name": "ThelmasTreats",
    "Id": "812-608-8758",
    "Type": "Dwolla",
    "Image": "https://www.dwolla.com/avatars/812-608-8758",
    "Latitude": 41.590043,
    "Longitude": -93.62095,
    "Address": "615 3rd Street\n",
    "City": "Des Moines",
    "State": "IA",
    "PostalCode": "50309",
    "Group": "812-608-8758",
    "Delta": 0.0009069999999908873
  },
  {
    "Name": "IKONIX Studio",
    "Id": "812-505-4939",
    "Type": "Dwolla",
    "Image": "https://www.dwolla.com/avatars/812-505-4939",
    "Latitude": 41.5887958,
    "Longitude": -93.6215057,
    "Address": "506 3rd St\nSuite 206",
    "City": "Des Moines",
    "State": "IA",
    "PostalCode": "50309",
    "Group": "812-505-4939",
    "Delta": 0.0027098999999992657
  }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Name": "ThelmasTreats",
            "Id": "812-608-8758",
            "Type": "Dwolla",
            "Image": "https://www.dwolla.com/avatars/812-608-8758",
            "Latitude": 41.590043,
            "Longitude": -93.62095,
            "Address": "615 3rd Street\n",
            "City": "Des Moines",
            "State": "IA",
            "PostalCode": "50309",
            "Group": "812-608-8758",
            "Delta": 0.0009069999999908873
        },
        {
            "Name": "IKONIX Studio",
            "Id": "812-505-4939",
            "Type": "Dwolla",
            "Image": "https://www.dwolla.com/avatars/812-505-4939",
            "Latitude": 41.5887958,
            "Longitude": -93.6215057,
            "Address": "506 3rd St\nSuite 206",
            "City": "Des Moines",
            "State": "IA",
            "PostalCode": "50309",
            "Group": "812-505-4939",
            "Delta": 0.0027098999999992657
        }
    ]
}

Retrieve a list of Dwolla business accounts (Spots) near a given location.

HTTP Request

GET https://www.dwolla.com/oauth/rest/contacts/nearby?client_id={}&client_secret={}&latitude={}&longitude={}

Parameter Optional? Description
client_id Your Application Key
client_secret Your Application Secret
latitude Latitude coordinates (between -90.0 and 90.0)
longitude Longitude coordinates (between -180.0 and 180.0)
range yes Range to retrieve spots for in miles (default 10, minimum 1)
limit yes Number of spots to retrieve (default 10, minimum 1, maximum 100)

Response

Parameter Description
Name Business name
Id Dwolla ID
Type Will always be Dwolla
Image URL to business’s account avatar
Latitude Business location
Longitude Business location
Address Business address. Street address lines are separated by an escaped newline character: \n
City Business address city
State Business address state
PostalCode Business address zip code
Group Set to Dwolla ID of business account
Delta Proximity to the lat / long specified in query

Errors

Error String Description
Latitude must be between -90.0 and 90.0. Invalid latitude.
Longitude must be between -180.0 and 180.0. Invalid longitude.

Find Users Nearby

<?php
$Account = new Dwolla\Account();
$Account->settings->client_id = $apiKey;
$Account->settings->client_secret = $apiSecret;

$lat = "40.7820";
$long = "-73.8317";

$result = $Account->nearby($lat, $long);

var_export($result);
?>
#   Get a list of nearby Dwolla users
#   for a given set of coordinates (lat, long)
pp Dwolla::Users.nearby(:latitude => 40.7820, :longitude => -73.8317)
# Get users near 40.7127, 74.0059
print(accounts.nearby(40.7127, 74.0059))
/**
 * Fetch all spots near lat 40.7820 and 
 * long -73.8317
 **/

Dwolla.nearbyUsers('40.7820', '-73.8317', function(err, data){
   console.log(data);
});

If successful, you’ll receive this response:

array (
  0 =>
  array (
    'Id' => '812-687-7049',
    'Image' => 'https://www.dwolla.com/avatars/812-687-7049',
    'Name' => 'Gordon Zheng',
    'Latitude' => 40.708448,
    'Longitude' => -74.014429,
    'Delta' => 114.72287700000001
  )
)
[{
    "Id": "812-687-7049",
    "Image": "https://www.dwolla.com/avatars/812-687-7049",
    "Name": "Gordon Zheng",
    "Latitude": 40.708448,
    "Longitude": -74.014429,
    "Delta": 114.72287700000001
}]
[
  {
    "Id"         => "812-687-7049",
    "Image"      => "https://www.dwolla.com/avatars/812-687-7049",
    "Name"       => "Gordon Zheng",
    "Latitude"   => 40.708448,
    "Longitude"  => -74.014429,
    "Delta"      => 114.72287700000001
  },
  { ... }
]
[
  {
    "Id": "812-687-7049",
    "Image": "https://www.dwolla.com/avatars/812-687-7049",
    "Name": "Gordon Zheng",
    "Latitude": 40.708448,
    "Longitude": -74.014429,
    "Delta": 114.72287700000001
  }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Id": "812-687-7049",
            "Image": "https://www.dwolla.com/avatars/812-687-7049",
            "Name": "Gordon Zheng",
            "Latitude": 40.708448,
            "Longitude": -74.014429,
            "Delta": 114.72287700000001
        }
    ]
}

Retrieve a list of Dwolla users near a given location. Users must opt into allowing their location to be seen by enabling this setting in the Dwolla mobile app. Example on the (web app).

HTTP Request

GET http://www.dwolla.com/oauth/rest/users/nearby?client_id={}&client_secret={}&latitude={}&longitude={}

Parameter Optional? Description
client_id Your Application Key
client_secret Your Application Secret
latitude Latitude coordinates (between -90.0 and 90.0)
longitude Longitude coordinates (between -180.0 and 180.0)

Response

Parameter Description
Id Dwolla ID
Image URL to user’s account avatar
Name User’s name
Latitude User’s location
Longitude User’s location
Delta Proximity to the lat / long specified in query

Errors

Error String Description
Latitude must be between -90.0 and 90.0. Invalid latitude.
Longitude must be between -180.0 and 180.0. Invalid longitude.

Contacts

[
    {
        "Name": "Joe Schmoe",
        "Id": "812-999-0090",
        "Type": "Dwolla",
        "Image": "https://www.dwolla.com/avatars/812-999-0090",
        "City": "St Louis",
        "State": "MO"
    },
    {
        "Name": "Sam Schmoe Super Foods",
        "Id": "812-999-0091",
        "Type": "Dwolla",
        "Image": "https://www.dwolla.com/avatars/812-999-0091",
        "City": "Des Moines",
        "State": "IA"
    }
]

Any Dwolla user which a user sends money to or receives money from becomes a Contact of that user.

Contact Resource

Property Description
Name User’s full name (business name, if business account)
Id Dwolla ID of user
Type Will always be Dwolla
Image URL of the user’s avatar image
City User’s resident city
State User’s resident state

Get a user’s contacts

<?php
$Contacts = new Dwolla\Contacts();
$Contacts->settings->oauth_token = "foo";

$result = $Contacts->get();

var_export($result);
?>
# EXAMPLE 1: 
#   Fetch last 10 contacts from the 
#   account associated with the provided
#   OAuth token
pp Dwolla::Contacts.get


# EXAMPLE 2: 
#   Search through the contacts of the
#   account associated with the provided
#   OAuth token
pp Dwolla::Contacts.get({:search => 'Ben'})
# Get the first 10 contacts from the user
# associated with the current OAuth token.

print(contacts.get())
/**
 * EXAMPLE 1: 
 *   Fetch last 10 contacts from the 
 *   account associated with the provided
 *   OAuth token
 **/

Dwolla.contacts(function(err, data){
   console.log(data);
});

/**
 * EXAMPLE 2: 
 *   Search through the contacts of the
 *   account associated with the provided
 *   OAuth token
 **/

Dwolla.contacts({search: 'Ben'}, function(err, data){
   console.log(data);
});

If successful, you’ll receive this response:

[
  {
    "Name"  => "Gordon Zheng",
    "Id"    => "812-742-3301",
    "Type"  => "Dwolla",
    "Image" => "http://uat.dwolla.com/avatars/812-742-3301",
    "City"  => "Elmhurst",
    "State" => "NY"
  },
  { ... },
  { ... }
]
[{u'City': u'Des Moines', u'Name': u'Dwolla, Inc.', u'Image': u'https://www.dwolla.com/avatars/812-616-9409', u'State': u'IA', u'Type': u'Dwolla', u'Id': u'812-616-9409'}, 
{u'City': u'Elmhurst', u'Name': u'Gordon Zheng', u'Image': u'https://www.dwolla.com/avatars/812-687-7049', u'State': u'NY', u'Type': u'Dwolla', u'Id': u'812-687-7049'}]
array (
  0 =>
  array (
    'Name' => 'GORDCORP',
    'Id' => '812-740-4294',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-740-4294',
    'City' => 'Test',
    'State' => 'NY',
  ),
  1 =>
  array (
    'Name' => 'Gordon Zheng',
    'Id' => '812-742-3301',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-3301',
    'City' => 'Elmhurst',
    'State' => 'NY',
  ),
  2 =>
  array (
    'Name' => 'Joe Schmoe',
    'Id' => '812-741-3440',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-741-3440',
    'City' => 'Test',
    'State' => 'NY',
  ),
)
[
    {
        "Name": "Joe Schmoe",
        "Id": "812-999-0090",
        "Type": "Dwolla",
        "Image": "https://www.dwolla.com/avatars/812-999-0090",
        "City": "St Louis",
        "State": "MO"
    },
    {
        "Name": "Sam Schmoe Super Foods",
        "Id": "812-999-0091",
        "Type": "Dwolla",
        "Image": "https://www.dwolla.com/avatars/812-999-0091",
        "City": "Des Moines",
        "State": "IA"
    }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Name": "Joe Schmoe",
            "Id": "812-999-0090",
            "Type": "Dwolla",
            "Image": "https://www.dwolla.com/avatars/812-999-0090",
            "City": "St Louis",
            "State": "MO"
        },
        {
            "Name": "Sam Schmoe Super Foods",
            "Id": "812-999-0091",
            "Type": "Dwolla",
            "Image": "https://www.dwolla.com/avatars/812-999-0091",
            "City": "Des Moines",
            "State": "IA"
        },
        {
            "Name": "Moe Schmoe",
            "Id": "812-999-0092",
            "Type": "Dwolla",
            "Image": "https://www.dwolla.com/avatars/812-999-0092",
            "City": "Simpsonville",
            "State": "SC"
        }
    ]
}

Use the following endpoint to fetch the authorized user’s contacts.

HTTP Request

GET https://www.dwolla.com/oauth/rest/contacts/

Optional Paramters

Parameter Description
search Search term used to search contacts.
types Account types to return.
limit Number of contacts to return (default is 10).

Balance

<?php
$Account = new Dwolla\Account();
$Account->settings->oauth_token = "foo";

$result = $Account->balance();

var_export($result);
?>
#   Get the balance of the authenticated user
puts Dwolla::Balance.get
# Get the balance of the account for
# the user associated with the current OAuth token

print(accounts.balance())
/***
 * Get balance of the user associated with the OAuth token.
 */

Dwolla.balance(function(err, data){
   if (err) { console.log(err); }
   console.log(data);
});

Response:

55.76
55.76
55.76
55.76
{
    "Success": true,
    "Message": "Success",
    "Response": 55.76
}

Fetch a user’s account balance.

HTTP Request

GET https://www.dwolla.com/oauth/rest/balance/

MassPay

$~ cowsay MOOOspay
  _________
< MOOOspay >
  ---------
         \   ^__^ 
          \  (oo)\_______
             (__)\       )\/\
                 ||----w |
                 ||     ||

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

Your MassPay Job will then be queued and processed. As the service processes a Job, each Item is processed one ofter the other, at an average rate of about 0.5 sec. / item. Therefore, you can expect a 1000-item MassPay Job to be completed in about 8 minutes.

MassPay offers a significant advantage over repeatedly calling the Send endpoint for each individual transaction, which is the fact that a bank-funded MassPay Job only incurs a single withdrawal from the bank account to fund the entire batch of payments. The alternative approach incurs a withdrawal 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.

Create Job

{
  "fundsSource": "76fe6c3ff2417eb02a9019c25c9a259d",
  "pin": "9999",
  "userJobId": "some ID",
  "assumeCosts": true,
  "items": [
    {
        "amount": 140.52,
        "destination": "812-713-9234"
    },
    {
        "amount": 100.00,
        "destination": "reflector@dwolla.com",
        "destinationType": "Email",
        "notes": "here's some money!",
        "metadata": {
            "foo": "bar"
        } 
    }
  ]
} 
# Create a MassPay job with two items to
# the Balance of the user associated with the current
# OAuth token.

info = masspay.create('Balance',
               {
                   {
                       'amount': 1.00,
                       'destination': '812-197-4121'
                   },
                   {
                       'amount': 2.00,
                       'destination': '812-174-9528'
                   }
               })
items = [
  {
    :amount => 9.99,
    :destination => 'gordon@dwolla.com',
    :destinationType => 'Email'
  },
  {
    :amount => 30,
    :destination => '812-742-3301',
    :notes => 'money!!!',
    :metadata => {
      'something_optional' => 'foobar'
    }
  }
]

puts Dwolla::MassPay.create({
  :fundsSource => "Balance",
  :pin => 9999,
  :items => items
})
items = [
  {
    amount: 0.01,
    destination: 'a@example.com',
    destinationType: 'Email',
    notes: 'for your good work',
    metadata: {
      'arbitrary_info': 'the house tasted good'
    }
  },
  {
    amount: 0.01,
    destination: '812-740-4294',
    destinationType: 'Dwolla',
    notes: 'cause Im jenerus',
    metadata: {
      'anything_you_want': 'blahhhhh'
    }
  },
  {
    amount: 0.01,
    destination: 'a@example.com',
    destinationType: 'email'
  }
];

dwolla.createMassPayJob('Balance', '2908', items, {
  userJobId: 'Some arbitrary id you can specify',
  assumeCosts: true
}, console.log);
<?php

/*
 * Send $3.40 to an email address and $12.40 to a Dwolla ID.
 */

$MassPay = new Dwolla\MassPay();
$MassPay->settings->oauth_token = "foo";
$MassPay->settings->pin = 9999;

$items = [
  [
    'destination' => 'gordon@dwolla.com',
    'destinationType' => 'Email',
    'amount' => 3.40,
    'notes' => 'enjoy this money!'
  ],
  [
    'destination' => '812-742-3301',
    'destinationType' => 'Dwolla',
    'amount' => 12.40
  ]
];

$fundsSource = '5da016f7769bcb1de9938a30d194d5a7';

$result = $MassPay->create($fundsSource, $items, [
  'assumeCosts' => true
]);

var_export($result);
?>

Response:

array (
  'Id' => '8b116429-95c8-428f-be0f-a3ce017cba53',
  'UserJobId' => NULL,
  'AssumeCosts' => true,
  'FundingSource' => '5da016f7769bcb1de9938a30d194d5a7',
  'Total' => 15.80,
  'Fees' => 0,
  'CreatedDate' => '2014-10-24T23:06:08Z',
  'Status' => 'queued',
  'ItemSummary' =>
  array (
    'Count' => 2,
    'Completed' => 0,
    'Successful' => 0,
  ),
)
{
        "Id": "47fe2f7c-8d6d-4f98-bcd9-a3100178062f",
        "AssumeCosts": true,
        "FundingSource": "Balance",
        "Total": 3.00,
        "Fees": 0,
        "CreatedDate": "2014-04-18T05:49:03Z",
        "Status": "queued",
        "ItemSummary": {
            "Count": 2,
            "Completed": 0,
            "Successful": 0
}
{
  "Id"            => "d18a2589-409c-4d0d-8404-a3ca005d3bf2",
  "UserJobId"     => nil,
  "AssumeCosts"   => false,
  "FundingSource" => "Balance",
  "Total"         => 39.99,
  "Fees"          => 0,
  "CreatedDate"   => "2014-10-20T05:39:27Z",
  "Status"        => "queued",
  "ItemSummary"   => {
    "Count"      => 2,
    "Completed"  => 0,
    "Successful" => 0
  }
}
{ 
  Id: '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e',
  UserJobId: 'Some arbitrary id you can specify',
  AssumeCosts: true,
  FundingSource: 'Balance',
  Total: 0.03,
  Fees: 0,
  CreatedDate: '2014-08-05T00:01:06Z',
  Status: 'queued',
  ItemSummary: { 
    Count: 3, 
    Completed: 0, 
    Successful: 0 
  } 
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "47fe2f7c-8d6d-4f98-bcd9-a3100178062f",
        "UserJobId": "testjob",
        "AssumeCosts": true,
        "FundingSource": "Balance",
        "Total": 240.52,
        "Fees": 0,
        "CreatedDate": "2014-04-18T05:49:03Z",
        "Status": "queued",
        "ItemSummary": {
            "Count": 2,
            "Completed": 0,
            "Successful": 0
        }
    }
}

Create a new MassPay job.

HTTP Request

POST https://www.dwolla.com/oauth/rest/masspay/

Request Parameters

Param Optional? Description
fundsSource no ID of funding source from which to fund the payments
pin no User account PIN
items no An array of Item objects. See below.
userJobId yes An optional custom identifer for this job
assumeCosts yes Deprecated

Items

Each payment to be created in a MassPay job is represented as a JSON object with the following properties:

Param Optional? Description
amount no Payment amount
destination no Payment destination. Can be a Dwolla ID or email address.
destinationType yes If the destination is an email address, set this to Email. Otherwise, defaults to Dwolla.
notes yes A note to attach to the payment. Max 250 characters.
metadata yes An optional metadata object.

Errors

Error String Description
The selected funding source doesn’t have enough funds to cover this job’s payout. Insufficient funds to cover total job payout. Select alternative funding source.

List Jobs

<?php
$MassPay = new Dwolla\MassPay();
$MassPay->settings->oauth_token = "foo";

$result = $MassPay->listJobs();

var_export($result);
?>
dwolla.getMassPayJobs(function(err, response) {
  console.log(response);
});
# Get all current MassPay jobs for the
# user associated with the current OAuth token.

print(masspay.listjobs())
puts Dwolla::MassPay.get

Response:

array (
  0 => array (
    'Id' => '8b116429-95c8-428f-be0f-a3ce017cba53',
    'UserJobId' => NULL,
    'AssumeCosts' => true,
    'FundingSource' => '5da016f7769bcb1de9938a30d194d5a7',
    'Total' => 15.80,
    'Fees' => 0,
    'CreatedDate' => '2014-10-24T23:06:08Z',
    'Status' => 'queued',
    'ItemSummary' =>
    array (
      'Count' => 2,
      'Completed' => 0,
      'Successful' => 0,
    ),
  ),

  1 => array ( ... ),
  2 => array ( ... ),
  ...
)
[
        {
            "Id": "643f2db9-5b45-4755-a881-a3100178b6d7",
            "UserJobId": "I've got a job for ya",
            "AssumeCosts": true,
            "FundingSource": "Balance",
            "Total": 0.02,
            "Fees": 0,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Status": "complete",
            "ItemSummary": {
                "Count": 2,
                "Completed": 2,
                "Successful": 2
            }
        },
        {
            "Id": "634de23d-ab50-4a53-bcd2-a310017794a8",
            "UserJobId": "I've got another job for ya",
            "AssumeCosts": true,
            "FundingSource": "Balance",
            "Total": 2,
            "Fees": 0,
            "CreatedDate": "2014-04-18T05:47:26Z",
            "Status": "complete",
            "ItemSummary": {
                "Count": 2,
                "Completed": 2,
                "Successful": 2
            }
        }
]
[
  {
    "Id"            => "256f7554-9bcb-4399-97d8-a34c00bb20b1",
    "UserJobId"     => "efnwjkefnkwjnknkjnk",
    "AssumeCosts"   => true,
    "FundingSource" => "Balance",
    "Total"         => 0.02,
    "Fees"          => 0.0,
    "CreatedDate"   => "2014-06-16T18:21:18Z",
    "Status"        => "complete",
    "ItemSummary"   => {
      "Count"      => 2,
      "Completed"  => 2,
      "Successful" => 1
    }
  },
  { ... }
]
[
   {
      Id: '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e',
      UserJobId: 'Some arbitrary id you can specify',
      AssumeCosts: true,
      FundingSource: 'Balance',
      Total: 0.03,
      Fees: 0,
      CreatedDate: '2014-08-05T00:01:06Z',
      Status: 'complete',
      ItemSummary: {
         Count: 3,
         Completed: 3,
         Successful: 3
      }
   },
   {
      Id: '68e22e63-c3cb-45e6-bf04-a37201717e5d',
      UserJobId: null,
      AssumeCosts: true,
      FundingSource: '76fe6c3ff2417eb02a9019c25c9a259d',
      Total: 10080000,
      Fees: 504,
      CreatedDate: '2014-07-24T22:25:18Z',
      Status: 'complete',
      ItemSummary: {
         Count: 2016,
         Completed: 2016,
         Successful: 1832
      }
   }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Id": "643f2db9-5b45-4755-a881-a3100178b6d7",
            "UserJobId": "I've got a job for ya",
            "AssumeCosts": true,
            "FundingSource": "Balance",
            "Total": 0.02,
            "Fees": 0,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Status": "complete",
            "ItemSummary": {
                "Count": 2,
                "Completed": 2,
                "Successful": 2
            }
        },
        {
            "Id": "634de23d-ab50-4a53-bcd2-a310017794a8",
            "UserJobId": "I've got another job for ya",
            "AssumeCosts": true,
            "FundingSource": "Balance",
            "Total": 2,
            "Fees": 0,
            "CreatedDate": "2014-04-18T05:47:26Z",
            "Status": "complete",
            "ItemSummary": {
                "Count": 2,
                "Completed": 2,
                "Successful": 2
            }
        }
    ]
}

List a user’s existing MassPay jobs.

HTTP Request

GET https://www.dwolla.com/oauth/rest/masspay/

Optional Param Description
limit Retrieve up to limit number of results
skip Pagination marker. Start retrieving results after skip number of elements in the set of results.

You can optionally provide the skip and limit querystring parameters to limit the number of results returned, and to offset the results by skip number of items. For example, to retrieve the first 20 results after the first 5 in the set of results:

GET https://www.dwolla.com/oauth/rest/masspay/?limit=20&skip=5

Errors

Error String Description
Invalid limit. The value for limit is invalid.
Invalid skip. The value for skip is invalid.

Retrieve Job

<?php
$MassPay = new Dwolla\MassPay();
$MassPay->settings->oauth_token = "foo";

$result = $MassPay->getJob('8b116429-95c8-428f-be0f-a3ce017cba53');

var_export($result);
?>

# Get information about a MassPay
# job with ID 'abcd123456'

print(masspay.getjob("abcd123456"))
puts Dwolla::MassPay.getJob('68e22e63-c3cb-45e6-bf04-a37201717e5d')
var jobId = '68e22e63-c3cb-45e6-bf04-a37201717e5d';

dwolla.getMassPayJob(jobId, function(err,result) {
  console.log(result);
});

Response:

array (
  'Id' => '8b116429-95c8-428f-be0f-a3ce017cba53',
  'UserJobId' => NULL,
  'AssumeCosts' => true,
  'FundingSource' => '5da016f7769bcb1de9938a30d194d5a7',
  'Total' => 15.80,
  'Fees' => 0,
  'CreatedDate' => '2014-10-24T23:06:08Z',
  'Status' => 'complete',
  'ItemSummary' =>
  array (
    'Count' => 2,
    'Completed' => 2,
    'Successful' => 2,
  ),
)
{
        "Id": "abcd123456",
        "AssumeCosts": true,
        "FundingSource": "Balance",
        "Total": 3.00,
        "Fees": 0,
        "CreatedDate": "2014-04-18T05:49:03Z",
        "Status": "complete",
        "ItemSummary": {
            "Count": 2,
            "Completed": 2,
            "Successful": 2
}
{
  "Id"            => "256f7554-9bcb-4399-97d8-a34c00bb20b1",
  "UserJobId"     => "efnwjkefnkwjnknkjnk",
  "AssumeCosts"   => true,
  "FundingSource" => "Balance",
  "Total"         => 0.02,
  "Fees"          => 0.0,
  "CreatedDate"   => "2014-06-16T18:21:18Z",
  "Status"        => "complete",
  "ItemSummary"   => {
    "Count"      => 2,
    "Completed"  => 2,
    "Successful" => 1
  }
}
{
  Id: '68e22e63-c3cb-45e6-bf04-a37201717e5d',
  UserJobId: null,
  AssumeCosts: true,
  FundingSource: '76fe6c3ff2417eb02a9019c25c9a259d',
  Total: 10080000,
  Fees: 504,
  CreatedDate: '2014-07-24T22:25:18Z',
  Status: 'complete',
  ItemSummary: {
     Count: 2016,
     Completed: 2016,
     Successful: 1832
  }
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "643f2db9-5b45-4755-a881-a3100178b6d7",
        "UserJobId": "somejob",
        "AssumeCosts": true,
        "FundingSource": "Balance",
        "Total": 240.52,
        "Fees": 0,
        "CreatedDate": "2014-04-18T05:51:34Z",
        "Status": "complete",
        "ItemSummary": {
            "Count": 2,
            "Completed": 2,
            "Successful": 2
        }
    }
}

Look up a particular MassPay job by its ID.

HTTP Request

GET https://www.dwolla.com/oauth/rest/masspay/{id}

Errors

Error String Description
Invalid job id. The value for job id is invalid.

List a Job’s Items

<?php
$MassPay = new Dwolla\MassPay();
$MassPay->settings->oauth_token = "foo";

$result = $MassPay->getJobItems('8b116429-95c8-428f-be0f-a3ce017cba53');

var_export($result);
?>
var jobId = '643f2db9-5b45-4755-a881-a3100178b6d7';

dwolla.getMassPayJobItems(jobId, function(err,result) {
  console.log(result);
});
# Get items from MassPay job ID with 'abcd1234'
items = masspay.getjobitems("abcd1234")
print(items)
puts Dwolla::MassPay.getItems('256f7554-9bcb-4399-97d8-a34c00bb20b1')

Response:

array (
  0 =>
  array (
    'JobId' => '8b116429-95c8-428f-be0f-a3ce017cba53',
    'ItemId' => 482764,
    'Destination' => 'gordon@dwolla.com',
    'DestinationType' => 'email',
    'Amount' => 3.4,
    'Status' => 'success',
    'TransactionId' => 347927,
    'Error' => NULL,
    'CreatedDate' => '2014-10-24T23:06:08Z',
    'Metadata' => NULL,
  ),
  1 =>
  array (
    'JobId' => '8b116429-95c8-428f-be0f-a3ce017cba53',
    'ItemId' => 482765,
    'Destination' => '812-742-3301',
    'DestinationType' => 'dwolla',
    'Amount' => 12.4,
    'Status' => 'success',
    'TransactionId' => 347929,
    'Error' => NULL,
    'CreatedDate' => '2014-10-24T23:06:08Z',
    'Metadata' => NULL,
  ),
)
[
  {
    "JobId"           => "256f7554-9bcb-4399-97d8-a34c00bb20b1",
    "ItemId"          => 17053,
    "Destination"     => "reflector@dwolla.com",
    "DestinationType" => "email",
    "Amount"          => 0.01,
    "Status"          => "success",
    "TransactionId"   => 61966,
    "Error"           => nil,
    "CreatedDate"     => "2014-06-16T18:21:18Z",
    "Metadata"        => {
      "lol" => "foo",
      "bar" => "qux"
    }
  },
  {
    "JobId"           => "256f7554-9bcb-4399-97d8-a34c00bb20b1",
    "ItemId"          => 17054,
    "Destination"     => "812-713-9234",
    "DestinationType" => "dwolla",
    "Amount"          => 0.01,
    "Status"          => "failed",
    "TransactionId"   => nil,
    "Error"           => "The user to send to could not be found.",
    "CreatedDate"     => "2014-06-16T18:21:18Z",
    "Metadata"        => nil
  }
]
[
        {
            "JobId": "abcd12345",
            "ItemId": 13,
            "Destination": "812-197-4121",
            "DestinationType": "dwolla",
            "Amount": 1.00,
            "Status": "success",
            "TransactionId": 4938766,
            "Error": null,
            "CreatedDate": "2014-04-18T05:51:34Z"
        },
        {
            "JobId": "abcd12345",
            "ItemId": 14,
            "Destination": "812-174-9528",
            "DestinationType": "dwolla",
            "Amount": 2.00,
            "Status": "success",
            "TransactionId": 4938768,
            "Error": null,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Metadata": null 
        }
]
{
  "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
  "ItemId": 13,
  "Destination": "reflector@dwolla.com",
  "DestinationType": "email",
  "Amount": 0.01,
  "Status": "success",
  "TransactionId": 4938766,
  "Error": null,
  "CreatedDate": "2014-04-18T05:51:34Z",
  "Metadata": {
      "some meta data":  "hello world!",
      "profound realization": "cats"
  }
},
{
  "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
  "ItemId": 14,
  "Destination": "812-713-9234",
  "DestinationType": "dwolla",
  "Amount": 0.01,
  "Status": "success",
  "TransactionId": 4938768,
  "Error": null,
  "CreatedDate": "2014-04-18T05:51:34Z",
  "Metadata": null 
}
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
            "ItemId": 13,
            "Destination": "reflector@dwolla.com",
            "DestinationType": "email",
            "Amount": 0.01,
            "Status": "success",
            "TransactionId": 4938766,
            "Error": null,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Metadata": {
                "some meta data":  "hello world!",
                "profound realization": "cats"
            }
        },
        {
            "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
            "ItemId": 14,
            "Destination": "812-713-9234",
            "DestinationType": "dwolla",
            "Amount": 0.01,
            "Status": "success",
            "TransactionId": 4938768,
            "Error": null,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Metadata": null 
        }
    ]
}

Retrieve the items for a particular MassPay job.

HTTP Request

GET https://www.dwolla.com/oauth/rest/masspay/{id}/items

Optional Param Description
limit Retrieve up to limit number of results
skip Pagination marker. Start retrieving results after skip number of elements in the set of results.
status Filter results on Item status. Possible values: notrun, success, failed

You can optionally provide the skip and limit querystring parameters to limit the number of results returned, and to offset the results by skip number of items. For example, to retrieve the first 20 results after the first 5 in the set of results:

GET https://www.dwolla.com/oauth/rest/masspay/{id}/items?limit=20&skip=5

Item Statuses

In the response, each Item will contain an item Status that corresponds to the success or fail of that particular transaction. A MassPay Job Item can contain a status of either notrun, success, or failed.

Errors

Error String Description
Invalid limit. The value for limit is invalid.
Invalid skip. The value for skip is invalid.
Invalid status. The value for status is invalid.

Retrieve a Job’s Item

var jobId = '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e';
var itemId = '424792';

dwolla.getMassPayJobItem(jobId, itemId, function(err, result) {
  console.log(result);
});
# Retrieve item 43432 from job with ID aaad1324

print(masspay.getitem("aaad1324", "43432")
# Retrieve item 17054 from Job 256f7554-9bcb-4399-97d8-a34c00bb20b1: 

puts Dwolla::MassPay.getItem('256f7554-9bcb-4399-97d8-a34c00bb20b1', '17054')
<?php
$MassPay = new Dwolla\MassPay();
$MassPay->settings->oauth_token = "foo";

$result = $MassPay->getItem('8b116429-95c8-428f-be0f-a3ce017cba53', '482765');

var_export($result);
?>

Response:

array (
  'JobId' => '8b116429-95c8-428f-be0f-a3ce017cba53',
  'ItemId' => 482765,
  'Destination' => '812-742-3301',
  'DestinationType' => 'dwolla',
  'Amount' => 12.4,
  'Status' => 'success',
  'TransactionId' => 347929,
  'Error' => NULL,
  'CreatedDate' => '2014-10-24T23:06:08Z',
  'Metadata' => NULL,
)
{
    "JobId": "aaad1324",
    "ItemId": 43432,
    "Destination": "812-197-4121",
    "DestinationType": "dwolla",
    "Amount": 1.00,
    "Status": "success",
    "TransactionId": 4938766,
    "Error": null,
    "CreatedDate": "2014-04-18T05:51:34Z"
}
{ 
  JobId: '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e',
  ItemId: 424792,
  Destination: 'a@example.com',
  DestinationType: 'email',
  Amount: 0.01,
  Status: 'success',
  TransactionId: 290128,
  Error: null,
  CreatedDate: '2014-08-05T00:06:26Z',
  Metadata: null 
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
        "ItemId": 14,
        "Destination": "812-713-9234",
        "DestinationType": "dwolla",
        "Amount": 0.01,
        "Status": "success",
        "TransactionId": 4938768,
        "Error": null,
        "CreatedDate": "2014-04-18T05:51:34Z",
        "Metadata": {
            "some meta data":  "hello world!",
            "profound realization": "cats"
        }
    }
}

Retrieve a particular MassPay Job Item, by the Job ID and Item ID.

HTTP Request

GET https://www.dwolla.com/oauth/rest/masspay/{job_id}/items/{item_id}

Errors

Error String Description
Invalid job id. The value for job id is invalid.
Invalid job item id. The value for item id is invalid.

Refund

{
  "amount": 11.25,
  "fundsSource": "Balance",
  "pin": 9999,
  "transactionId": 2427171
}
/**
 * Process a refund for transaction '123456',
 * funding the refund from funding source ID '7654321'
 * for amount $10.00
 */

Dwolla.refund(pin, '12345', '7654321', 10.00, function(err, data) {
  console.log(data);
});
puts Dwolla::Transactions.refund({
  :transactionId => "341617",
  :fundsSource => "Balance",
  :pin => "9999",
  :amount => 20
})
<?php

/*
 * Refund transaction ID 347940 for the amount of $20.00,
 * and fund the refund with the merchant's account balance.
 */

$Transactions = new Dwolla\Transactions();
$Transactions->settings->oauth_token = "foo";
$Transactions->settings->pin = 9999;

$transactionId = '347940';
$fundingSource = 'Balance';
$result = $Transactions->refund($transactionId, $fundingSource, 20.00);

var_export($result);
?>
# Refund $2 from "Balance" from transaction
# '123456'

print(transactions.refund('3452346', 'Balance', 2.00))

Response:

array (
  'TransactionId' => 347944,
  'RefundDate' => '10/24/2014 23:23:20',
  'Amount' => 20,
)
{
    "TransactionId": 4532,
    "RefundDate": "2014-12-10T12:01:09Z",
    "Amount": 2.00
}
{
  "TransactionId" => 341621,
  "RefundDate"    => "10/20/2014 05:51:43",
  "Amount"        => 20
}
{
  "TransactionId": 123458,
  "RefundDate": "2014-01-22T17:47:04Z",
  "Amount": 10
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "TransactionId": 8522,
        "RefundDate": "2014-01-22T17:47:04Z",
        "Amount": 20
    }
}

Commercial, Non-Profit, and Government type accounts can refund payments that have been received. There is no limit on the window of time in which a payment can be refunded. Individual accounts currently cannot refund payments.

A refund creates a new transaction. The refund amount can be up to the total payment amount, plus any facilitator fees assumed by the sender.

The Refund API requires the Recipient’s Transaction ID to be provided.

HTTP Request

POST https://www.dwolla.com/oauth/rest/transactions/refund

Request Parameters

Param Optional? Description
fundsSource no ID of funding source from which to fund the payments
pin no User account PIN
transactionId no Recipient’s Transaction ID of the payment to be refunded.
notes yes Note to attach to the refund. Visible to refunder and recipient of refund. Max 250 chars.
metadata yes An optional metadata object.

Response Parameters

Param Description
TransactionId Transaction ID of the newly created refund payment
RefundDate Timestamp when refund was created
Amount Amount refunded

Errors

Error String Description
Invalid access token. Access token not valid.
Transaction ineligible for refund. Cannot refund the transaction, for one of the following reasons: user is not recipient of a transaction, user is not a Commercial or Non-Profit type account
Invalid refund amount. Refund amount is either less than 0.01 or not equal to or less than the original transaction amount.

Money Requests

    __  ___                      
   /  |/  /___  ____  ___  __  __
  / /|_/ / __ \/ __ \/ _ \/ / / /
 / /  / / /_/ / / / /  __/ /_/ / 
/_/  /_/\____/_/ /_/\___/\__, /  
                        /____/   
    ____                             __      
   / __ \___  ____ ___  _____  _____/ /______
  / /_/ / _ \/ __ `/ / / / _ \/ ___/ __/ ___/
 / _, _/  __/ /_/ / /_/ /  __(__  ) /_(__  ) 
/_/ |_|\___/\__, /\__,_/\___/____/\__/____/  
              /_/      
{
    "Id": 1636,
    "Source": {
        "Id": "812-742-8722",
        "Name": "Cafe Kubal",
        "Type": "Dwolla",
        "Image": "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "Destination": {
        "Id": "812-742-3301",
        "Name": "Gordon Zheng",
        "Type": "Dwolla",
        "Image": "http://uat.dwolla.com/avatars/812-742-3301"
    },
    "Amount": 0.01,
    "Notes": "",
    "DateRequested": "2014-10-01T19:50:54Z",
    "Status": "Paid",
    "Transaction": {
        "RequestId": 1636,
        "Id": 335741,
        "Source": {
            "Id": "812-742-3301",
            "Name": "Gordon Zheng",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-742-3301"
        },
        "Destination": {
            "Id": "812-742-8722",
            "Name": "Cafe Kubal",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-742-8722"
        },
        "Amount": 0.01,
        "SentDate": "2014-10-01T19:51:52Z",
        "ClearingDate": "2014-10-01T19:51:52Z",
        "Status": "processed"
    },
    "CancelledBy": null,
    "DateCancelled": "",
    "SenderAssumeAdditionalFees": false,
    "AdditionalFees": [],
    "Metadata": null
}

Money Requests are sent from a Dwolla user to another Dwolla user, phone number or email address. A Money Request is essentially an invoice, requesting payment from the recipient of the request.

Money Requests can be fulfilled for the amount of the request or greater whenever the payer decides to do so. When fulfilled, a RequestFulfilled webhook notification is sent. Money Requests can also be cancelled by either the sender of the request or the recipient of the request. When cancelled, a RequestCancelled webhook notification is sent.

Money requests do not expire.

Money Request Statuses

Status Description
Pending Intitial state upon creation. Not yet fulfilled.
Paid Payer has fulfilled the request and a payment has been sent for the request amount or greater.
Cancelled Request was cancelled by either payer or requester.

Money Request Resource

Parameter Description
Id Unique Request ID
Source JSON object describing the requester: Dwolla ID, full name, user type (will always be Dwolla, since only Dwolla user accounts can request money), and profile avatar URL
Destination JSON object describing the payer: DestinationId (a Dwolla ID, email, or phone number), full name (if Dwolla account, otherwise, the email or phone number), user type, and profile avatar URL (null if not a user yet)
Amount Amount of funds requested
Notes Optional notes attached to Money Request
DateRequested Date and time when Money Request was created
Status Status of Money Request. See statuses.
Transaction If fulfilled, a JSON object representing the resulting Transaction. Otherwise, null.
CancelledBy If cancelled, a JSON object representing the user who cancelled the request. Otherwise, null.
DateCancelled If cancelled, the date and time when the request was cancelled. Otherwise, empty string: "".
SenderAssumeFee Boolean. Deprecated
SenderAssumeAdditionalFees Boolean. true if sender will assume all facilitator fees.
AdditionalFees Any additional facilitator fees attached to the request.
Metadata An optional metadata object.

Create Money Request

<?php

// Request $20 from email gordon@dwolla.com

$Requests = new Dwolla\Requests();
$Requests->settings->oauth_token = "foo";

$result = $Requests->create('gordon@dwolla.com', 20.00, [
  'sourceType' => 'Email',
  'notes' => 'You owe me money!'
]);

var_export($result);
?>
# Request 1.00 from a Dwolla ID
puts Dwolla::Requests.create({:sourceId=> '812-742-8722', :amount=> '1.00'})
# Request $5 from 812-740-3809

print(request.create('812-740-3809', 5.00))
/***
 * Request $5 from Source ID '812-111-1111'
 */

Dwolla.request('812-111-1111', '5.00', function(err, data) {
   console.log(data);
});

If successful, you’ll receive this response:

1670        // request ID
1470 # Request ID
1652      # request ID
1288        // Request ID
{
    "Success": true,
    "Message": "Success",
    "Response": 996
}

Send a Money Request from the authorized user to a destination Dwolla user, email address or phone number.

HTTP Request

POST https://www.dwolla.com/oauth/rest/requests/

Parameter Optional? Description
sourceId no ID of user to request funds from. Must be either a Dwolla ID, phone number, or email address.
amount no Amount of funds to request
sourceType yes Type of source user (either Dwolla, Email or Phone). Defaults to Dwolla.
facilitatorAmount yes Amount of the facilitator feeto override. Only applicable if the facilitator fee feature is enabled for your API application. If set to 0, facilitator fee is disabled for transaction. Cannot exceed 50% of the amount.
notes yes Note to attach to request (250 character limit).
senderAssumeCosts yes Deprecated
senderAssumeAdditionalFees yes Set to true if the fulfilling user is to assume all facilitator fees. Defaults to false; does not include the Dwolla transaction fee.
additionalFees yes Array of additional facilitator fee objects. [{"destinationId": "", "amount": 0.01}, ...]
metadata yes Optional JSON object of a maximum of 10 key-value pairs (each key and value must be less than 255 characters). Read more

Errors

Error String Description
Notes length is too long. Maximum of 250 character is allowed. The ‘notes’ parameter is too long. See requests parameters for further details.
The user to send to could not be found. Could not find the speicified source user + source type combination.
You can only send money to one of your Twitter followers. You can only request money from one of your Twitter followers.
Invalid facilitator user.
Facilitator fee too large. Facilitator fee cannot exceed 50% of the amount.
Facilitator fee too small.
Money request failed. {..} An unexpecetd error occured while trying to request funds. See additional response message.

List Money Requests

/**
 * EXAMPLE 1: 
 *   Get list of pending requests
 **/
$requests = $Dwolla->requests();
if(!$requests) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($requests); }
# Get all pending requests
puts Dwolla::requests.get
# Get all pending requests from the user
# associated with the current OAuth token.
print(request.get())
/***
 * List pending money requests for the authorized user
 */

Dwolla.requests(function(err, data){
   console.log(data);
});
<?php
$Requests = new Dwolla\Requests();
$Requests->settings->oauth_token = "foo";

$result = $Requests->get();

var_export($result);
?>

If successful, you’ll receive this response:

array (
  0 =>
  array (
    'Id' => 1452,
    'Source' =>
    array (
      'Id' => '812-742-8722',
      'Name' => 'Cafe Kubal',
      'Type' => 'Dwolla',
      'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
    ),
    'Destination' =>
    array (
      'Id' => '812-443-2936',
      'Name' => ' ',
      'Type' => 'Dwolla',
      'Image' => 'http://uat.dwolla.com/avatars/812-443-2936',
    ),
    'Amount' => 1,
    'Notes' => '',
    'DateRequested' => '2014-08-27T03:47:39Z',
    'Status' => 'Pending',
    'Transaction' => NULL,
    'CancelledBy' => NULL,
    'DateCancelled' => '',
    'SenderAssumeAdditionalFees' => false,
    'AdditionalFees' =>
    array (
    ),
    'Metadata' => NULL,
  ),
  1 => array ( ... ),
  2 => array ( ... ),
  ...
)
[
        {
            "Id": 640,
            "Source": {
                "Id": "812-693-9484",
                "Name": "Spencer Hunter",
                "Type": "Dwolla",
                "Image": null
            },
            "Destination": {
                "Id": "812-706-1396",
                "Name": "Jane Doe",
                "Type": "Dwolla",
                "Image": null
            },
            "Amount": 5.00,
            "Notes": "",
            "DateRequested": "2014-07-23T21:49:06Z",
            "Status": "Pending" ,
            "Transaction": null,
            "CancelledBy": null,
            "DateCancelled": "",
            "SenderAssumeAdditionalFees": false,
            "AdditionalFees": [],
            "Metadata": null 
        },
        ...
]
[
  {
    "Id"                         => 1452,
    "Source"                     => {
      "Id"    => "812-742-8722",
      "Name"  => "Cafe Kubal",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "Destination"                => {
      "Id"    => "812-443-2936",
      "Name"  => " ",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-443-2936"
    },
    "Amount"                     => 1.0,
    "Notes"                      => "",
    "DateRequested"              => "2014-08-27T03:47:39Z",
    "Status"                     => "Pending",
    "Transaction"                => nil,
    "CancelledBy"                => nil,
    "DateCancelled"              => "",
    "SenderAssumeAdditionalFees" => false,
    "AdditionalFees"             => [],
    "Metadata"                   => nil
  },
  { ... }
]
[
  {
    "Id": 640,
    "Source": {
      "Id": "812-693-9484",
      "Name": "Spencer Hunter",
      "Type": "Dwolla",
      "Image": null
    },
    "Destination": {
      "Id": "812-706-1396",
      "Name": "Jane Doe",
      "Type": "Dwolla",
      "Image": null
    },
    "Amount": 0.1,
    "Notes": "",
    "DateRequested": "2014-07-23T21:49:06Z",
    "Status": "Pending" ,
    "Transaction": null,
    "CancelledBy": null,
    "DateCancelled": "",
    "SenderAssumeAdditionalFees": false,
    "AdditionalFees": [],
    "Metadata": null 
  },
  {
    ...
  },
  {
    ...
  }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Id": 640,
            "Source": {
                "Id": "812-693-9484",
                "Name": "Spencer Hunter",
                "Type": "Dwolla",
                "Image": null
            },
            "Destination": {
                "Id": "812-706-1396",
                "Name": "Jane Doe",
                "Type": "Dwolla",
                "Image": null
            },
            "Amount": 0.1,
            "Notes": "",
            "DateRequested": "2014-07-23T21:49:06Z",
            "Status": "Pending" ,
            "Transaction": null,
            "CancelledBy": null,
            "DateCancelled": "",
            "SenderAssumeAdditionalFees": false,
            "AdditionalFees": [],
            "Metadata": null 
        },

        ...

    ]
}

List the authorized user’s pending requests.

HTTP Request

GET https://www.dwolla.com/oauth/rest/requests/

Request Parameters

Parameter Optional? Description
startDate yes Earliest date and time for which to retrieve pending requests (defaults to 0300 UTC for current day)
endDate yes Latest date and time for which to retrieve pending requests (defaults to UTC current date/time)
limit yes Number of pending requests to retrieve (defaults to 20, must be in range of 1-200)

Retrieve Money Request

<?php
$Requests = new Dwolla\Requests();
$Requests->settings->oauth_token = "foo";

$requestId = '1452';
$result = $Requests->info($requestId);

var_export($result);
?>
# Example 1: Get request details for request '12345'
puts Dwolla::requests.get('12345')
# Get info regarding a pending money request.
print(request.info(1470))
/***
 * Fetch a money request by id '12345678'
 */

Dwolla.requestById('12345678', function(err, data) {
   console.log(data);
});

If successful, you’ll receive this response:

array (
  'Id' => 1452,
  'Source' =>
  array (
    'Id' => '812-742-8722',
    'Name' => 'Cafe Kubal',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
  ),
  'Destination' =>
  array (
    'Id' => '812-443-2936',
    'Name' => ' ',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-443-2936',
  ),
  'Amount' => 1,
  'Notes' => '',
  'DateRequested' => '2014-08-27T03:47:39Z',
  'Status' => 'Pending',
  'Transaction' => NULL,
  'CancelledBy' => NULL,
  'DateCancelled' => '',
  'SenderAssumeAdditionalFees' => false,
  'AdditionalFees' =>
  array (
  ),
  'Metadata' => NULL,
)
{
    "Id"                         => 12345,
    "Source"                     => {
      "Id"    => "812-742-8722",
      "Name"  => "Cafe Kubal",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
    },
    "Destination"                => {
      "Id"    => "812-443-2936",
      "Name"  => " ",
      "Type"  => "Dwolla",
      "Image" => "http://uat.dwolla.com/avatars/812-443-2936"
    },
    "Amount"                     => 1.0,
    "Notes"                      => "",
    "DateRequested"              => "2014-08-27T03:47:39Z",
    "Status"                     => "Pending",
    "Transaction"                => nil,
    "CancelledBy"                => nil,
    "DateCancelled"              => "",
    "SenderAssumeAdditionalFees" => false,
    "AdditionalFees"             => [],
    "Metadata"                   => nil
  }
        {
            "Id": 1470,
            "Source": {
                "Id": "812-693-9484",
                "Name": "Spencer Hunter",
                "Type": "Dwolla",
                "Image": null
            },
            "Destination": {
                "Id": "812-706-1396",
                "Name": "Jane Doe",
                "Type": "Dwolla",
                "Image": null
            },
            "Amount": 5.00,
            "Notes": "",
            "DateRequested": "2014-07-23T21:49:06Z",
            "Status": "Pending" ,
            "Transaction": null,
            "CancelledBy": null,
            "DateCancelled": "",
            "SenderAssumeAdditionalFees": false,
            "AdditionalFees": [],
            "Metadata": null 
        }
{
  "Id": 660,
  "Source": {
    "Id": "812-693-9484",
    "Name": "Spencer Hunter",
    "Type": "Dwolla",
    "Image": null
  },
  "Destination": {
    "Id": "812-706-1396",
    "Name": "Jane Doe",
    "Type": "Dwolla",
    "Image": null
  },
  "Amount": 10,
  "Notes": "",
  "DateRequested": "2014-07-25T17:38:26Z",
  "Status": "Pending" ,
  "Transaction": null,
  "CancelledBy": null,
  "DateCancelled": "",
  "SenderAssumeAdditionalFees": false,
  "AdditionalFees": [],
  "Metadata": {
    "InvoiceDate": "12-06-2014",
    "Priority": "High",
    "TShirtSize": "Small",
    "blah": "blah"
  }
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": 660,
        "Source": {
            "Id": "812-693-9484",
            "Name": "Spencer Hunter",
            "Type": "Dwolla",
            "Image": null
        },
        "Destination": {
            "Id": "812-706-1396",
            "Name": "Jane Doe",
            "Type": "Dwolla",
            "Image": null
        },
        "Amount": 10,
        "Notes": "",
        "DateRequested": "2014-07-25T17:38:26Z",
        "Status": "Pending" ,
        "Transaction": null,
        "CancelledBy": null,
        "DateCancelled": "",
        "SenderAssumeAdditionalFees": false,
        "AdditionalFees": [],
        "Metadata": {
            "InvoiceDate": "12-06-2014",
            "Priority": "High",
            "TShirtSize": "Small",
            "blah": "blah"
        }
    }
}

Retrieve a single Money Request by its ID.

HTTP Request

GET https://www.dwolla.com/oauth/rest/requests/{id}

Errors

Error String Description
No verified funding sources. Could not find any funding sources for the given OAuth token.

Fulfill Money Request

/**
 *   Fulfill request ID 1671 for $29.99
 **/
<?php
$Requests = new Dwolla\Requests();
$Requests->settings->oauth_token = "foo";
$Requests->settings->pin = 9999;

$requestId = '1671';
$result = $Requests->fulfill($requestId, '29.99');

var_export($result);
?>
# Example 1: Fulfill a request, ID 1653, of amount 20.00
puts Dwolla::Requests.fulfill('1653', {
  :pin => 9999,
  :amount => 20.00,
})
# Fulfill a pending money request.

print(request.fulfill(1475, 10.00))
/***
 * Fulfill money request ID '12345678'.  Pay '10.00'
 */

Dwolla.fulfillRequest(pin, '12345678', '10.00', function(err, data) {
   console.log(data);
});

If successful, you’ll receive this response:

array (
  'RequestId' => 1671,
  'Id' => 347947,
  'Source' =>
  array (
    'Id' => '812-742-8722',
    'Name' => 'Cafe Kubal',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-8722',
  ),
  'Destination' =>
  array (
    'Id' => '812-742-3301',
    'Name' => 'Gordon Zheng',
    'Type' => 'Dwolla',
    'Image' => 'http://uat.dwolla.com/avatars/812-742-3301',
  ),
  'Amount' => 29.989999999999998,
  'SentDate' => '2014-10-24T23:37:18Z',
  'ClearingDate' => '2014-10-24T23:37:18Z',
  'Status' => 'processed',
)
{
        "Id": 147659,
        "RequestId": 1475,
        "Amount": 10.00,
        "SentDate": "2014-01-22T13:11:10Z",
        "ClearingDate": "2014-01-22T13:11:10Z",
        "Status": "processed" ,
        "Source": {
            "Id": "812-693-9484",
            "Name": "Michael Schonfeld",
            "Type": "Dwolla",
            "Image": null
        },
        "Destination": {
            "Id": "812-600-6705",
            "Name": "Michael Schonfeld",
            "Type": "Dwolla",
            "Image": null
        }
}
{
  "RequestId"    => 1653,
  "Id"           => 341624,
  "Source"       => {
    "Id"    => "812-742-8722",
    "Name"  => "Cafe Kubal",
    "Type"  => "Dwolla",
    "Image" => "http://uat.dwolla.com/avatars/812-742-8722"
  },
  "Destination"  => {
    "Id"    => "812-742-3301",
    "Name"  => "Gordon Zheng",
    "Type"  => "Dwolla",
    "Image" => "http://uat.dwolla.com/avatars/812-742-3301"
  },
  "Amount"       => 20.0,
  "SentDate"     => "2014-10-20T06:00:02Z",
  "ClearingDate" => "2014-10-20T06:00:02Z",
  "Status"       => "processed"
}
{ 
  RequestId: 12345678,
  Id: 328969,
  Source: { 
    Id: '812-740-4294',
    Name: 'GORDCORP',
    Type: 'Dwolla',
    Image: 'http://uat.dwolla.com/avatars/812-740-4294' 
  },
  Destination: { 
    Id: '812-742-8722',
    Name: 'Cafe Kubal',
    Type: 'Dwolla',
    Image: 'http://uat.dwolla.com/avatars/812-742-8722'
  },
  Amount: 10,
  SentDate: '2014-09-09T04:30:46Z',
  ClearingDate: '2014-09-09T04:30:46Z',
  Status: 'processed' 
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": 147659,
        "RequestId": 999,
        "Amount": 1,
        "SentDate": "2014-01-22T13:11:10Z",
        "ClearingDate": "2014-01-22T13:11:10Z",
        "Status": "processed" ,
        "Source": {
            "Id": "812-693-9484",
            "Name": "Michael Schonfeld",
            "Type": "Dwolla",
            "Image": null
        },
        "Destination": {
            "Id": "812-600-6705",
            "Name": "Michael Schonfeld",
            "Type": "Dwolla",
            "Image": null
        }
    }
}

Fulfill an authorized user’s pending money request. Request must have a status of Pending.

HTTP Request

POST https://www.dwolla.com/oauth/rest/requests/{request_id}/fulfill

Parameter Optional? Description
pin no The authorized user’s PIN.
amount no Amount to pay for request (must be greater than or equal to the request amount).
notes yes Note to attach to transaction (250 character limit).
fundsSource yes ID of funding source to use for transaction (defaults to Balance).
assumeCosts yes Deprecated
metadata yes An optional metadata object.

Errors

Error String Description
Invalid request ID. The specific request ID is either empty or invalid.
Request not found for account. Could not find a request with the specified ID for the given OAuth token.
Account can not pay their own request. Account can not pay their own request.
Request has already been paid Request has already been paid
Amount may not be less than request amount of {0} The fulfilled amount cannot be less than the requested amount.
Notes length is too long. Maximum of 250 character is allowed. The 'notes’ parameter is too long. See requests parameters for further details.
Invalid funding source provided: {..} The specified funding source is missing, empty, or invalid.
Insufficient funds. The are not enough funds in the specified funding source to fulfill this transaction.

Cancel a Money Request

Cancel a money request which the authorized user created or received. Request must have a status of Pending.

/**
 *   Cancel request with ID 1672
 **/
<?php
$Requests = new Dwolla\Requests();
$Requests->settings->oauth_token = "foo";

$requestId = '1672';
$result = $Requests->cancel($requestId);

var_export($result);
?>
# Cancel request with ID '12345'
puts Dwolla::Requests.delete('1652')
# Cancel a pending money request.

print(request.cancel(1470))
/***
 * Cancel money request with ID '12345678'
 */

Dwolla.cancelRequest('12345678', function(err, data){
   console.log(data);
});

If successful, you’ll recieve this response:

''      // empty string
true    // boolean.
""      // empty string
{
    "Success": true,
    "Message": "Success",
    "Response": ""
}

HTTP Request

POST https://www.dwolla.com/oauth/rest/requests/{request_id}/cancel

Error String Description
Invalid request ID. The specific request ID is either empty or invalid.
Request not found for account. Could not find a request with the specified ID for the given OAuth token.
Request is not in Pending status. You may only cancel requests that are in the 'pending’ state.

Account Settings

With the ManageAccount OAuth scope, you can set and retrieve a user’s account preferences.

Currently, the only account feature you can enable or disable for a user via the API is Auto Withdrawal. When Auto Withdrawal is enabled for a user, any payments received by the user will be automatically withdrawn to a bank funding source of their choice.

Get Auto Withdrawal Status

/**
 * Example 1:
 * Get autowithdrawal status for the 
 * account associted with the OAuth token
 */

<?php
$Account = new Dwolla\Account();
$Account->settings->oauth_token = "foo";

$result = $Account->getAutoWithdrawalStatus();

var_export($result);
?>
#   Get autowithdrawal status of the user
#   associated with the current OAuth token

puts Dwolla::Accounts.get_auto_withdrawal_status
# Get the auto-withdrawal status of the user
# associated with the current OAuth token.

print(accounts.autowithdrawalstatus())
/***
 * Find out whether or not auto-withdrawal is enabled for the 
 * authorized user
 */

Dwolla.getAutoWithdrawalStatus(function(err, data) {
    console.log(data);
});

If enabled, you’ll get:

{
  "Enabled"   => true,
  "FundingId" => "5da016f7769bcb1de9938a30d194d5a7"
}
{u'Enabled': True, u'FundingId': u'5da016f7769bcb1de9938a30d194d5a7'}
{
    "Enabled": true,
    "FundingId": "5da016f7769bcb1de9938a30d194d5a7"
}
{
  "Success": true,
  "Message": "Success",
  "Response": {
    "Enabled": true,
    "FundingId": "5da016f7769bcb1de9938a30d194d5a7"
  }
}
array (
  'Enabled' => true,
  'FundingId' => '5da016f7769bcb1de9938a30d194d5a7',
)

If disabled, you’ll get this response:

array (
  'Enabled' => false,
  'FundingId' => '',
)
{
  "Enabled"   => false,
  "FundingId" => ""
}
{u'Enabled': False, u'FundingId': u''}
{
  "Enabled": false,
  "FundingId": ""
}
{
  "Success": true,
  "Message": "Success",
  "Response": {
    "Enabled": false,
    "FundingId": ""
  }
}

Determine whether the Auto Withdrawal is enabled for the authorized user.

HTTP Request

GET https://www.dwolla.com/oauth/rest/accounts/features/auto_withdrawl

Enable/Disable Auto Withdrawal

# Toggle the auto-withdrawal status of an account
# under the Dwolla user associated with the current OAuth token.

print(accounts.toggleautowithdrawalstatus(True, '12345678'))
/**
 * Example 1:
 * Enable autowithdraw for funding source '12345' under the
 * account associted with the OAuth token
 */

<?php
$Account = new Dwolla\Account();
$Account->settings->oauth_token = "foo";

$fundingSource = '5da016f7769bcb1de9938a30d194d5a7';
$result = $Account->toggleAutoWithdrawalStatus(true, $fundingSource);

var_export($result);
?>
# EXAMPLE 1:
#   Enable autowithdraw for funding source '12345' under the
#   associated with the current OAuth token

puts Dwolla::Accounts.toggle_auto_withdrawl(true, '12345')
# Toggle the auto-withdrawal status of an account
# under the Dwolla user associated with the current OAuth token.

print(accounts.toggleautowithdrawalstatus(True, '12345678'))
/***
 * Enable auto-withdraw for the user associated with the OAuth token,
 * for the funding source ID '1234567'.
 */

Dwolla.toggleAutoWithdraw('true', '1234567', function(err, data) {
    console.log(data);
});

If enabled, you’ll get this response:

'Enabled'
"Enabled"
"Enabled"
"Enabled"
{
    "Success": true,
    "Message": "Success",
    "Response": "Enabled"
}

Enable or disable Auto Withdrawal for the authorized user.

HTTP Request

POST https://www.dwolla.com/oauth/rest/accounts/features/auto_withdrawl

Parameter Description
enabled Boolean value of autowithdrawal feature.
fundingId Funding source ID of account to autowithdraw funds to.

Changelog

Track our changes on Github!

Date Changes
10/15/2014 Initial docs + code samples written
12/03/2014 Temporarily removed Scheduled Transactions documentation, which is currently not available while we work on making some improvements to it.
03/17/2015 Add new parameters processingTypes and verified to the List Funding Sources endpoint.
4/1/2015 Added Python example code
4/28/2015 Add Scheduled Payments documentation. Introduce Scheduled scope. Add Catalog endpoint. Update sample code for scheduled and catalog.
8/7/2015 Add dwolla_landing parameter to the initial OAuth authorization request.