Introduction

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

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

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

Helper Libraries

We'll show you sample code on this pane!

Quote of the day:

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

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

• PHP: dwolla-php
• Ruby: dwolla-ruby
• Python: dwolla-python
• Node.JS: dwolla-node
• Java: dwolla-java
• Clojure: dwolla-clojure
• Scala: dwolla-scala
• Windows 8 SDK
  • Phone
  • XAML
  • JS
• 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: '[email protected]',
    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
}

Unsuccessful response

{
    "Success": false,
    "Message": "Invalid access token.",
    "Response": 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 error
• Message, an error message if the API call was unsuccessful, or "Success" otherwise
• Response, the actual data returned by the API call.

Facilitator Fees

By enabling the Facilitator Fee application feature, your application can take a cut of any transactions that it facilitates. 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 total transaction amount, and exist as a separate Transaction resource with a unique Transaction ID.

Metadata

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

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

Visibility / Access

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

Unlike the notes field, which is visible to:

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

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

Warnings

Currently, there are 2 bugs we are aware of:

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

Errors

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

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

Standard HTTP 200 JSON response:
{
    "Success": false,
    "Message": "Access token is empty.",
    "Response": null
}

HTTP 500 XML response:

<Fault>
    xmlns="http://schemas.microsoft.com/ws/2005/05/envelope/none">
    <Code>
        <Value>Receiver</Value>
        <Subcode>
            <Value 
                xmlns:a="http://schemas.microsoft.com/net/2005/12/windowscommunicationfoundation/dispatcher">a:InternalServiceFault
            </Value>
        </Subcode>
    </Code>
    <Reason>
        <Text xml:lang="en-US">The server was unable to process the request due to an internal error.  For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the &lt;serviceDebug&gt; configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs.</Text>
    </Reason>
</Fault>

HTTP Status	Response Type	Meaning
200	JSON	Normal errors
500	XML	Results from an invalid request or uncaught server exception

General Errors

The following errors are common across all API endpoints.

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

Authentication

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

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

Dwolla.setToken("token goes here");

require 'dwolla'

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

# set an OAuth access token
Dwolla::token = "JRRTolkien"

<?php
require 'dwolla.php';

// Instantiate a new Dwolla REST Client
$Dwolla = new DwollaRestClient("key goes here", "secret goes here");

// Set an OAuth access token:
$Dwolla->setToken("token goes here");
?>

from dwolla import DwollaClientApp, DwollaUser

# Instantiate a new Dwolla client
Dwolla = DwollaClientApp("key goes here", "secret goes here")

# set an OAuth access token
DwollaUser = DwollaUser("token goes here")

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");

?>

// 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	Description
client_id	Application key
response_type	This must always be set to code
redirect_uri	URL where the user will be redirected to afterwards
scope	Permissions you are requesting. See below for list of available scopes. Scopes are delimited by a pipe (“|”)

OAuth Scopes

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

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

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);
?>

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

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.

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.

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": "",
        "Fees": [],
        "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": "",
    "SenderAssumeFee": false,
    "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",
    "SenderAssumeFee": false,
    "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 [email protected]
 **/

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

$result = $Transactions->send('[email protected]', 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 money ($1.00) to a Dwolla ID 812-626-8794
'''
transaction = DwollaUser.send_funds(0.01, '812-626-8794', _keys.pin)
print(transaction)

/**
 *   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, '[email protected]', 1.00, params, function(err, data) {
   if (err) { console.log(err); }
   console.log(data);
});

{
  "amount": 0.01,
  "destinationId": "[email protected]",
  "destinationType": "Email",
  "pin": 4321
}

If successful, you’ll receive this response:

343947    // resulting Transacton 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.

You can optionally have the sender cover the transaction fee, if applicable, by setting assumeCosts to true. By default, the recipient of the payment covers the $0.25 fee.

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.
assumeCosts	yes	Set to true for the fulfilling user to assume the Dwolla fee, false for the destination user to assume the 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
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);
});

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

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

array (
  'CheckoutId' => 'f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
  'URL' => 'https://uat.dwolla.com/payment/checkout/f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
)

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

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

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

Then send your user there!

HTTP Request

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

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

PurchaseOrder Object

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

Errors

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

Retrieve a Checkout

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

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

var_export($result);
?>

var checkoutId = 'a9d7c86a-0d0d-4466-b228-e15584a1315a';
dwolla.getCheckout(checkoutId, function(err, response) {
  console.log(response);
});

This method is not yet supported in dwolla-ruby.

Response:

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "CheckoutId": "684862bc-8d94-4e53-9c41-26398b4b7fac",
        "Discount": null,
        "Shipping": null,
        "Tax": null,
        "Total": 15,
        "Status": "Completed",
        "FundingSource": "Balance",
        "TransactionId": 69960,
        "ProfileId": null,
        "DestinationTransactionId": 69959,
        "OrderItems": [
            {
                "Description": "A somewhat tasty non-vegetarian sandwich",
                "Name": "Prime Rib Sandwich",
                "Price": 15,
                "Quantity": 1
            }
        ],
        "Metadata": null
    }
}

{ 
  CheckoutId: 'd0429a55-c338-4139-b273-48d2f8c45693',
  Discount: null,
  Shipping: null,
  Tax: null,
  Total: 5,
  Status: 'Completed',
  FundingSource: 'Balance',
  TransactionId: 290142,
  ProfileId: null,
  DestinationTransactionId: 290141,
  OrderItems: [],
  Metadata: null 
}

array (
  'CheckoutId' => 'f3f454bd-89a9-422f-8fef-5eb9f82ccc8f',
  'Discount' => NULL,
  'Shipping' => NULL,
  'Tax' => NULL,
  'Total' => 33.99,
  'Status' => 'Created',
  'FundingSource' => NULL,
  'TransactionId' => NULL,
  'ProfileId' => NULL,
  'DestinationTransactionId' => NULL,
  'OrderItems' =>
  array (
  ),
  'Metadata' => NULL,
)

This method is not yet supported in dwolla-ruby.

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

HTTP Request

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

Response Parameters

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

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

Complete a PayLater Checkout

{
  "client_id": "JCGQXLrlfuOqdUYdTcLz3rBiCZQDRvdWIUPkw++GMuGhkem9Bo",
  "client_secret": "g7QLwvO37aN2HoKx1amekWi8a2g7AIuPbD5C/JSLqXIcDOxfTr"
}

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 deposited 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 Fi-Sync 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. Currently, only bank accounts with Veridian Credit Union support FiSync.	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 deposited or withdrawn from them.
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);
});

#   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',
  ),
)

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

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);
})

# Retrieve a funding source by its ID

pp Dwolla::FundingSources.get("5da016f7769bcb1de9938a30d194d5a7")

<?php 

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

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

var_export($result);
?>

Response:

array (
  'Balance' => NULL,
  'Id' => '5da016f7769bcb1de9938a30d194d5a7',
  'Name' => 'Blah - Checking',
  'Type' => 'Checking',
  'Verified' => true,
  'ProcessingType' => 'ACH',
)

{
  "Id"             => "5da016f7769bcb1de9938a30d194d5a7",
  "Name"           => "Blah - Checking",
  "Type"           => "Checking",
  "Verified"       => true,
  "ProcessingType" => "ACH"
}

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "c58bb9f7f1d51d5547e1987a2833f4fb",
        "Name": "Donations Payout Account - Checking",
        "Type": "Checking",
        "Verified": true,
        "ProcessingType": "FiSync"
    }
}

{ 
    Id: '5da016f7769bcb1de9938a30d194d5a7',
    Name: 'Blah - Checking',
    Type: 'Checking',
    Verified: true,
    ProcessingType: 'ACH' 
} 

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

HTTP Request

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

Errors

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

Withdraw to a funding source

var fundingSource = "c58bb9f7f1d51d5547e1987a2833f4fb";
dwolla.withdrawToFundingSource(pin, 5.00, fundingSource, function(err, res) {
  console.log(res);
})

{
    amount: 300.52,
    pin: 9999
}

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:

array (
  'Id' => 346098,
  'Amount' => 5,
  'Date' => '2014-10-22T19:49:45Z',
  'Type' => 'withdrawal',
  'UserType' => 'Dwolla',
  'DestinationId' => 'XXX9999',
  'DestinationName' => 'Blah',
  'Destination' =>
  array (
    'Id' => 'XXX9999',
    '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"         => "XXX9999",
  "DestinationName"       => "Blah",
  "Destination"           => {
    "Id"    => "XXX9999",
    "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": "XXX9999",
        "DestinationName": "Blah",
        "Destination": { 
            "Id": "XXX9999", 
            "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: 'XXX9999',
    DestinationName: 'Blah',
    Destination: { 
        Id: 'XXX9999', 
        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.

Deposit from a funding source

{
  amount: 5,
  pin: 9999
}

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' => 'XXX9999',
  'SourceName' => 'Blah',
  'Source' =>
  array (
    'Id' => 'XXX9999',
    'Name' => 'Blah',
    'Type' => 'Dwolla',
    'Image' => '',
  ),
  'ClearingDate' => '2014-10-28T00: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"              => "XXX9999",
  "SourceName"            => "Blah",
  "Source"                => {
    "Id"    => "XXX9999",
    "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: 'XXX9999',
  SourceName: 'Blah',
  Source: { 
    Id: 'XXX9999', 
    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": "XXX9999",
        "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": "XXX9999", 
            "Name": "Blah", 
            "Type": "Dwolla", 
            "Image": ""
        },
        "ClearingDate": "2014-09-08T00:00:00Z",
        "Status": "pending",
        "Notes": null,
        "Fees": null,
        "OriginalTransactionId": null,
        "Metadata": null 
      }
}

Deposit funds from a user’s bank funding source to the user’s 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 deposit amount is $1.00. Please adjust the deposit amount.
The account is limited to {…} per transaction	The maximum amount per deposit for this account is {…}. Please adjust the deposit amount.

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 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: '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);
?>

```ruby
puts Dwolla::FundingSources.verify("7bf971a12543f560119318e67aa76035", {
  :deposit1 => 0.01, 
  :deposit2 => 0.04, 
})

{
    "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"             => "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 payment, withdrawal, deposit, or fee, is recorded as an individual Transaction. For instance, depositing money from a funding source into your Dwolla account balance creates a Transaction of type deposit.

How Transactions Work

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

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

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

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

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

Additional Transactions

For a particular payment, additional transactions are created:

• if the payment is bank sourced, to fund the payment
• if the payment is over $10 it will incur a $0.25 Dwolla Fee
• 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
fee	Transaction fee of $0.25 or Facilitator Fee

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": "[email protected]",
  "DestinationName": "[email protected],
  "Destination": {
      "Id": "[email protected]",
      "Name": "[email protected]",
      "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 or transaction 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);
?>

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' => 'XXX9999',
    'SourceName' => 'Blah',
    'Source' =>
    array (
      'Id' => 'XXX9999',
      '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"         => "XXX9999",
    "DestinationName"       => "Blah",
    "Destination"           => {
      "Id"    => "XXX9999",
      "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": "[email protected]",
      "DestinationName": "[email protected]",
      "Destination": {
        "Id": "[email protected]",
        "Name": "[email protected]",
        "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)

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' => 'XXX9999',
    'SourceName' => 'Blah',
    'Source' =>
    array (
      'Id' => 'XXX9999',
      '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"         => "XXX9999",
    "DestinationName"       => "Blah",
    "Destination"           => {
      "Id"    => "XXX9999",
      "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": "[email protected]",
            "DestinationName": "[email protected]",
            "Destination": {
                "Id": "[email protected]",
                "Name": "[email protected]",
                "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)

<?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' => 'XXX9999',
  'SourceName' => 'Blah',
  'Source' =>
  array (
    'Id' => 'XXX9999',
    'Name' => 'Blah',
    'Type' => 'Dwolla',
    'Image' => '',
  ),
  'ClearingDate' => '2014-10-28T00:00:00Z',
  'Status' => 'pending',
  'Notes' => NULL,
  'Fees' => NULL,
  'OriginalTransactionId' => NULL,
  'Metadata' => NULL,
)

{
    "Id"                    => 331506,
    "Amount"                => 15.25,
    "Date"                  => "2014-09-17T18:18:46Z",
    "Type"                  => "withdrawal",
    "UserType"              => "Dwolla",
    "DestinationId"         => "XXX9999",
    "DestinationName"       => "Blah",
    "Destination"           => {
      "Id"    => "XXX9999",
      "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": "XXX9999",
    "DestinationName": "Blah",
    "Destination": {
      "Id": "XXX9999",
      "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": "XXX9999",
        "SourceName": "Blah",
        "Source": {
          "Id": "XXX9999",
          "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.

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);
?>

Response:

{
  "TransactionsCount" => 10,
  "TransactionsTotal" => 134.22
}

{
  "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('[email protected]')

'''
    EXAMPLE 1: 
      Fetch basic account information
      for a given Dwolla ID
'''
me = Dwolla.get_account_info('812-626-8794')
print(me)

/**
 *   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
}

{
    "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 [email protected]:

GET https://www.dwolla.com/oauth/rest/users/[email protected]?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

'''
    EXAMPLE 1: 
      Fetch account information for the
      account associated with the provided
      OAuth token
'''
me = DwollaUser.get_account_info()
print(me)

/**
 *   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
}

{
    "City": "Des Moines",
    "Id": "812-111-1111",
    "Latitude": 41.584546,
    "Longitude": -93.634167,
    "Name": "Test User",
    "State": "IA",
    "Type": "Personal"
}

array (
  'City' => 'Test',
  'State' => 'NY',
  'Type' => 'Commercial',
  'Id' => '812-742-8722',
  'Name' => 'Cafe Kubal',
  'Latitude' => -1,
  'Longitude' => -1,
)

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "City": "Des Moines",
        "Id": "812-111-1111",
        "Latitude": 41.584546,
        "Longitude": -93.634167,
        "Name": "Test User",
        "State": "IA",
        "Type": "Personal"
    }
}

Retrieve information about the authorized user.

HTTP Request

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

Response

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

Get Avatar

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

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

HTTP Request

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

Find Nearby Businesses

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

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

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

var_export($result);
?>

#   Get a list of nearby Dwolla spots
#   for a given set of coordinates (lat, long)
pp Dwolla::Contacts.nearby(41.58975983, -93.61564636)

'''
    EXAMPLE 1: 
      Fetch spots near  41.59 and 
      -93.62 (default parameters in dwolla-python)
'''
contacts = DwollaUser.get_nearby_spots()
print(contacts)

/**
 * 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"       => "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)

'''
    EXAMPLE 1: 
      Fetch users near  40.78 and 
      -73.83 (default parameters in dwolla-python)
'''
users = DwollaUser.get_nearby_users('40.7820', '-73.8317')
print(users)

/**
 * 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
  }
]

{
    "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'})

'''
    EXAMPLE 1: 
      Fetch last 10 contacts from the 
      account associated with the provided
      OAuth token
'''
contacts = DwollaUser.get_contacts()
print(contacts)


'''
    EXAMPLE 2: 
      Search through the contacts of the
      account associated with the provided
      OAuth token
'''
contacts = DwollaUser.get_contacts('Ben')
print(contacts)

/**
 * 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"
  },
  { ... },
  { ... }
]

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

balance = DwollaUser.get_balance()
print(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

{
    "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 ACH deposit to fund the entire batch of payments.

The alternative approach incurs an ACH deposit 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, which inspired us to build the Single Deposit feature.

Create Job

{
  "fundsSource": "76fe6c3ff2417eb02a9019c25c9a259d",
  "pin": "9999",
  "userJobId": "some ID",
  "assumeCosts": true,
  "items": [
    {
        "amount": 140.52,
        "destination": "812-713-9234"
    },
    {
        "amount": 100.00,
        "destination": "[email protected]",
        "destinationType": "Email",
        "notes": "here's some money!",
        "metadata": {
            "foo": "bar"
        } 
    }
  ]
} 

items = [
  {
    :amount => 9.99,
    :destination => '[email protected]',
    :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: '[email protected]',
    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: '[email protected]',
    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.
 * Assume transaction fees.
 */

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

$items = [
  [
    'destination' => '[email protected]',
    '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.25,
  'CreatedDate' => '2014-10-24T23:06:08Z',
  'Status' => 'queued',
  'ItemSummary' =>
  array (
    'Count' => 2,
    'Completed' => 0,
    'Successful' => 0,
  ),
)

{
  "Id"            => "d18a2589-409c-4d0d-8404-a3ca005d3bf2",
  "UserJobId"     => nil,
  "AssumeCosts"   => false,
  "FundingSource" => "Balance",
  "Total"         => 39.99,
  "Fees"          => 0,
  "CreatedDate"   => "2014-10-20T05:39:27Z",
  "Status"        => "queued",
  "ItemSummary"   => {
    "Count"      => 2,
    "Completed"  => 0,
    "Successful" => 0
  }
}

{ 
  Id: '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e',
  UserJobId: 'Some arbitrary id you can specify',
  AssumeCosts: true,
  FundingSource: 'Balance',
  Total: 0.03,
  Fees: 0,
  CreatedDate: '2014-08-05T00:01:06Z',
  Status: 'queued',
  ItemSummary: { 
    Count: 3, 
    Completed: 0, 
    Successful: 0 
  } 
}

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "47fe2f7c-8d6d-4f98-bcd9-a3100178062f",
        "UserJobId": "testjob",
        "AssumeCosts": true,
        "FundingSource": "Balance",
        "Total": 240.52,
        "Fees": 0,
        "CreatedDate": "2014-04-18T05:49:03Z",
        "Status": "queued",
        "ItemSummary": {
            "Count": 2,
            "Completed": 0,
            "Successful": 0
        }
    }
}

Create a new MassPay job.

HTTP Request

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

Request Parameters

Param	Optional?	Description
fundsSource	no	ID of funding source from which to fund the payments
pin	no	User account PIN
items	no	An array of Item objects. See below.
userJobId	yes	An optional custom identifer for this job
assumeCosts	yes	If true, the sender will assume the $0.25 Dwolla fee for each payment, if applicable. Defaults to false.

Items

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

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

Errors

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

List Jobs

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

$result = $MassPay->listJobs();

var_export($result);
?>

dwolla.getMassPayJobs(function(err, response) {
  console.log(response);
});

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.25,
    'CreatedDate' => '2014-10-24T23:06:08Z',
    'Status' => 'queued',
    'ItemSummary' =>
    array (
      'Count' => 2,
      'Completed' => 0,
      'Successful' => 0,
    ),
  ),

  1 => array ( ... ),
  2 => array ( ... ),
  ...
)

[
  {
    "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);
?>

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.25,
  'CreatedDate' => '2014-10-24T23:06:08Z',
  'Status' => 'complete',
  'ItemSummary' =>
  array (
    '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);
});

puts Dwolla::MassPay.getItems('256f7554-9bcb-4399-97d8-a34c00bb20b1')

Response:

array (
  0 =>
  array (
    'JobId' => '8b116429-95c8-428f-be0f-a3ce017cba53',
    'ItemId' => 482764,
    'Destination' => '[email protected]',
    '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"     => "[email protected]",
    "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": "643f2db9-5b45-4755-a881-a3100178b6d7",
  "ItemId": 13,
  "Destination": "[email protected]",
  "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": "[email protected]",
            "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 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: '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e',
  ItemId: 424792,
  Destination: '[email protected]',
  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);
?>

Response:

array (
  'TransactionId' => 347944,
  'RefundDate' => '10/24/2014 23:23:20',
  'Amount' => 20,
)

{
  "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. This transaction will not incur a $0.25 transaction fee. The refund amount can be up to the total payment amount, plus any transaction fee assumed by the sender and 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": "",
    "SenderAssumeFee": false,
    "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. true if sender will assume the $0.25 transaction fee if applicable.
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 [email protected]

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

$result = $Requests->create('[email protected]', 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'})

'''
    EXAMPLE 1:
      Initiate a money request
'''
request = DwollaUser.request_funds('1.00', '[email protected]', _keys.pin, source_type='Email')
print(request)

/***
 * 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

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	Set to true if the fulfilling user is to assume the Dwolla fee. Defaults to false; does not include facilitator fees.
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

'''
    EXAMPLE 1:
      Get a list of pending requests
      for the user with the given oauth token
'''
pending_requests = DwollaUser.get_pending_requests()
print(pending_requests)

/***
 * 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' => '',
    'SenderAssumeFee' => false,
    'SenderAssumeAdditionalFees' => false,
    'AdditionalFees' =>
    array (
    ),
    'Metadata' => NULL,
  ),
  1 => array ( ... ),
  2 => array ( ... ),
  ...
)

[
  {
    "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"              => "",
    "SenderAssumeFee"            => false,
    "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": "",
    "SenderAssumeFee": false,
    "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": "",
            "SenderAssumeFee": false,
            "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')

'''
    EXAMPLE 1:
      Get detailed information for the request
      with the given 'request_id'
'''
request_id = '2209516'
request = DwollaUser.get_request(request_id)
print(request)

/***
 * 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' => '',
  'SenderAssumeFee' => false,
  '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"              => "",
    "SenderAssumeFee"            => false,
    "SenderAssumeAdditionalFees" => false,
    "AdditionalFees"             => [],
    "Metadata"                   => nil
  }

{
  "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": "",
  "SenderAssumeFee": false,
  "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": "",
        "SenderAssumeFee": false,
        "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,
})

'''
    EXAMPLE 1:
      Fulfill (:pay) a pending payment request
'''
request_id = '2214710'
fulfilled_request = DwollaUser.fulfill_request(request_id, _keys.pin)
print(fulfilled)

/***
 * 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',
)

{
  "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	Set to true for the fulfilling user to assume the Dwolla fee, false for the destination user to assume the fee.
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')

'''
    EXAMPLE 1:
      Cancel a pending money request
'''
request_id = request
canceled_request = DwollaUser.cancel_request(request_id)
print(canceled_request)

/***
 * 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

'''
    EXAMPLE 1: 
        Fetch autowithdraw status for the account
        associated with the current OAuth token.
'''
status = DwollaUser.get_autowithdraw_status
print(status)

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

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

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

/**
 * 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')

'''
    EXAMPLE 1: 
        nable autowithdraw for funding source '12345' under the
        associated with the current OAuth token.
'''
status = DwollaUser.set_autowithdraw_status(true, '12345')
print(status)

/***
 * 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"

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

Enable or disable Auto Withdrawal for the authorized user.

HTTP Request

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

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

Changelog

Track our changes on Github!

Date	Changes
10/15/2014	Initial docs + code samples written
12/03/2014	Temporarily removed Scheduled Transactions documentation, which is currently not available while we work on making some improvements to it.