Introduction
_ _ _
| |__ ___| | | ___
| '_ \ / _ \ | |/ _ \
| | | | __/ | | (_) |
|_| |_|\___|_|_|\___/ _
__ _____ _ __| | __| |
\ \ /\ / / _ \| '__| |/ _` |
\ V V / (_) | | | | (_| |
\_/\_/ \___/|_| |_|\__,_|
Welcome to the Dwolla API V1 documentation. Dwolla’s 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.
We’re in the process of migrating to a new API version – Version 2. Initially, the primary focus of the new version centers around a premium feature: White Label, and will not provide the same functionality as Version 1 does. API V1 will continue to be supported for the foreseeable future. Over time, we will add the same functionality currently available in V1 to V2. Feel free to sign up for our Developer Newsletter to remain informed of our ongoing changes.
If you’re not sure where to start, ask a question in our developer forum or get in touch with our Developer Relations team.
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.
Officially maintained
- PHP: dwolla-php
- Ruby: dwolla-ruby
- Python: dwolla-python
- Node.JS: dwolla-node
- Java: dwolla-java
Unsupported or community maintained
- Clojure: dwolla-clojure
- Scala: dwolla-scala
- Windows 8 SDK
- iOS: dwolla-ios
- OS X Cocoa: dwolla-cocoa
- Perl: WebService-Dwolla
- C# / .NET: dwolla.net
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:
Success, a boolean indicating whether or not the call was successful, or resulted in an errorMessage, an error message if the API call was unsuccessful, or"Success"otherwiseResponse, the actual data returned by the API call.
Most API responses will contain:
_links, object that contains links (to URIs). Keys within _links are the name of the link and describe the relationship between the current resource and the link.
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:
- the application that created the transaction
- the recipient and sender of the transaction (through the Dwolla.com dashboard)
- 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:
- If an metadata collection contains two duplicate keys, a HTTP 500 XML response will be thrown instead of a proper error response.
- 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 <serviceDebug> 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. The value of this parameter must match one of the values that appear in your application details page. (We compare: protocol, subdomain, domain, tld, and file path. Querystring parameters are ignored) | |
| scope | 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 names of funding sources the user has connected to Dwolla, access available balance information for Dwolla Balance and Dwolla Credit (if applicable), add new funding sources, verify funding sources, initiate transfers to and from funding sources |
| ManageAccount | Manage the user’s account settings |
| Scheduled | Allow scheduling one-time and recurring payments |
| Access the user’s Dwolla account email address |
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:
- TransactionStatus
- TransactionReturned
- RequestFulfilled
- RequestCancelled
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
CheckoutIdto 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 |
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,
"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,
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'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,
'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, 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",
"Balance" => nil,
"Verified" => true,
"ProcessingType" => "FiSync"
}
{
"Id": "12345678",
"Name": "Donations Payout Account - Checking",
"Type": "Checking",
"Balance": null,
"Verified": true,
"ProcessingType": "FiSync"
}
{
"Success": true,
"Message": "Success",
"Response": {
"Balance": null,
"Id": "a1578b447d79ad16eea8601d46d006cb",
"Name": "Veridian Credit Union - Savings",
"Type": "Savings",
"Verified": true,
"ProcessingType": "FiSync"
},
"_links": null
}
{
Id: '5da016f7769bcb1de9938a30d194d5a7',
Name: 'Blah - Checking',
Balance: null,
Type: 'Checking',
Verified: true,
ProcessingType: 'FiSync'
}
Look up a particular funding source by its funding source ID. This endpoint includes an additional Balance parameter. If the funding source is of type Credit or is a Dwolla account balance, the funding source’s available funds will be returned. Otherwise, for ACH and FiSync funding sources, Balance will be null.
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:
- Transaction
512010: credits Alice’s account with $5 - 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:
- if the payment is bank sourced, to fund the payment
- if there is a facilitator fee
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 Email Address
/**
* No example for this language yet.
**/
# No example for this language yet.
# No example for this language yet.
/**
* No example for this language yet.
**/
If successful, you’ll receive this response:
{
"Success": true,
"Message": "Success",
"Response": {
"Email": "test+user@email.com"
},
"_links": null
}
Retrieve the email address for the authorized user.
HTTP Request
GET https://www.dwolla.com/oauth/rest/users/email
Response
| Parameter | Description |
|---|---|
| Dwolla user account email address. |
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 identifier for this job. Note: Must be a unique string identifier that hasn’t already been supplied in an existing request. |
| 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. |
| A job with UserJobId of ’{}’ already exists. | A MassPay job has already been created with the supplied userJobId. Supply a new unique value. |
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. |