NAV
json php ruby python node.js

Introduction

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

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

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

Helper Libraries

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

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

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

Making Requests

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

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

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

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

GET requests have parameters provided in the querysting.

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

Responses

Happy response

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

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:

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.

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

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

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

{
  "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": 35,
    "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']

Successful Response:

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

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:

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 ($1.00) to Dwolla ID 812-734-7288
 **/
$transactionId = $Dwolla->send($pin, '812-734-7288', 1.00);
if(!$transactionId) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { echo "Send transaction ID: {$transactionId} \n"; } // Print Transaction ID
#   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, 'gordon@dwolla.com', 1.00, params, function(err, data) {
   if (err) { console.log(err); }
   console.log(data);
});

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

If successful, you’ll receive this response:

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

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

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

Retrieve a Checkout

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,
                "Total": 15
            }
        ],
        "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 
}
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);
});
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
    }
}
{ 
  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
}
"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.

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

Response:

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

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

Response:

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

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

Response:

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

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

Response:

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

Add new Funding Source

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

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

Verify a Funding Source

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:

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

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:

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

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"                 => nil,
    "Fees"                  => nil,
    "OriginalTransactionId" => nil,
    "Metadata"              => nil
  },
  { ... },
  { ... }
]
[
   {
      "Id":328979,
      "Amount":10.01,
      "Date":"2014-09-09T04:49:41Z",
      "Type":"money_sent",
      "UserType":"Dwolla",
      "DestinationId":"812-232-2342",
      "DestinationName":"Joe Schmoe",
      "Destination":{
         "Id":"812-232-2342",
         "Name":"Joe Schmoe",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-232-2342"
      },
      "SourceId":"812-742-8722",
      "SourceName":"Cafe Kubal",
      "Source":{
         "Id":"812-742-8722",
         "Name":"Cafe Kubal",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-742-8722"
      },
      "ClearingDate":"",
      "Status":"processed",
      "Notes":"",
      "Fees":null,
      "OriginalTransactionId":null,
      "Metadata":null
  },
  { 
    ... 
  },
  { 
    ... 
  }
]
{
  "Success": true,
  "Message": "Success",
  "Response": [
    {
      "Id": 5569196,
      "Amount": 0.01,
      "Date": "2014-08-13T05:17:15Z",
      "Type": "money_sent",
      "UserType": "Email",
      "DestinationId": "ejfwefjwfk02022@gmail.com",
      "DestinationName": "ejfwefjwfk02022@gmail.com",
      "Destination": {
        "Id": "ejfwefjwfk02022@gmail.com",
        "Name": "ejfwefjwfk02022@gmail.com",
        "Type": "Email",
        "Image": ""
      },
      "SourceId": "812-687-7049",
      "SourceName": "Gordon Zheng",
      "Source": {
        "Id": "812-687-7049",
        "Name": "Gordon Zheng",
        "Type": "Dwolla",
        "Image": "https://dwolla-avatars.s3.amazonaws.com/812-687-7049/ac044552"
      },
      "ClearingDate": "",
      "Status": "cancelled",
      "Notes": "",
      "Fees": null,
      "OriginalTransactionId": null,
      "Metadata": null
    },
    ...
  ]
}

Retrieve the transaction history of the authenticated user.

HTTP Request

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

Example:

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

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

Request Parameters

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

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);
});
puts Dwolla::Transactions.get(nil, {}, false)

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"                 => nil,
    "Fees"                  => nil,
    "OriginalTransactionId" => nil,
    "Metadata"              => nil
  },
  { ... },
  { ... }
]
[
   {
      "Id":328979,
      "Amount":10.01,
      "Date":"2014-09-09T04:49:41Z",
      "Type":"money_sent",
      "UserType":"Dwolla",
      "DestinationId":"812-232-2342",
      "DestinationName":"Joe Schmoe",
      "Destination":{
         "Id":"812-232-2342",
         "Name":"Joe Schmoe",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-232-2342"
      },
      "SourceId":"812-742-8722",
      "SourceName":"Cafe Kubal",
      "Source":{
         "Id":"812-742-8722",
         "Name":"Cafe Kubal",
         "Type":"Dwolla",
         "Image":"http://uat.dwolla.com/avatars/812-742-8722"
      },
      "ClearingDate":"",
      "Status":"processed",
      "Notes":"",
      "Fees":null,
      "OriginalTransactionId":null,
      "Metadata":null
  },
  { 
    ... 
  },
  { 
    ... 
  }
]
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "Id": 5569196,
            "Amount": 0.01,
            "Date": "2014-08-13T05:17:15Z",
            "Type": "money_sent",
            "UserType": "Email",
            "DestinationId": "ejfwefjwfk02022@gmail.com",
            "DestinationName": "ejfwefjwfk02022@gmail.com",
            "Destination": {
                "Id": "ejfwefjwfk02022@gmail.com",
                "Name": "ejfwefjwfk02022@gmail.com",
                "Type": "Email",
                "Image": ""
            },
            "SourceId": "812-687-7049",
            "SourceName": "Gordon Zheng",
            "Source": {
                "Id": "812-687-7049",
                "Name": "Gordon Zheng",
                "Type": "Dwolla",
                "Image": "https://dwolla-avatars.s3.amazonaws.com/812-687-7049/ac044552"
            },
            "ClearingDate": "",
            "Status": "cancelled",
            "Notes": "",
            "Fees": null,
            "OriginalTransactionId": null,
            "Metadata": null
        },
        ...
    ]
}

List the transactions which your application has created / facilitated.

HTTP Request

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

Example:

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

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

Request Parameters

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

Get a specific transaction

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

Dwolla.transactionById('12345', function(err, data) {
  console.log(data);
});
#   Retrieve a transaction by ID
puts Dwolla::Transactions.get(331506)

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

Scheduled Transactions

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

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

Payments can be scheduled to be created at a future date, up to 3 years into the future. Only bank-sourced payments are supported at this time. When a Scheduled Transaction is created, no transaction is created (and thus, no funds are transferred) until the ScheduledDate. If there is an error creating the transaction, the Scheduled Transaction will have a Status of failed.

Scheduled Transaction Resource

Property Description
Id A unique ID for the scheduled transaction
ScheduledDate Date when transaction will be created. Must be within 3 years from when the scheduled transaction was created. Format: YYYY-MM-DD
ExpectedClearingDate Estimated date when the funds will be available to the recipient. Typically 1-3 business days after the ScheduledDate.
TransactionId Transaction ID of resulting Transaction. null until the transaction is successfully created.
Amount Amount of the transaction to be created.
FundingSource ID of the bank funding source which will fund the transaction
AssumeCosts Boolean. Set to true if the sender of the funds will assume the $0.25 transaction fee (only applies if transaction is greater than $10.00).
Destination JSON object describing the recipient. Id is the recipient’s Dwolla ID or email address, Name is the recipient’s full name, Type is either Dwolla or Email and Image is a URL to the recipient’s avatar, if the recipient is an existing Dwolla user.
Notes Optional notes field. Max 250 chars.
Status Possible values: ‘scheduled’, ‘processed’, ‘failed’

Create Scheduled Transaction

{
  "pin": "9999",
  "destinationId": "gordon@dwolla.com",
  "destinationType": "Email",
  "amount": 300.00,
  "scheduleDate": "2015-09-13",
  "assumeCosts": true,
  "fundsSource": "5da016f7769bcc1de9998a30d194d5a7",
  "notes": "here's this month's rent!",
  "metadata": {
    "foo": "bar"
  }
}

Response:

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "3bfaf7fb-b5e9-4a6e-ab09-1ef30d30bbef",
        "ScheduledDate": "2015-09-13",
        "ExpectedClearingDate": "2015-09-18",
        "TransactionId": null,
        "Amount": 300.00,
        "FundingSource": "5da016f7769bcc1de9998a30d194d5a7",
        "AssumeCosts": false,
        "Destination": {
            "Id": "812-111-1111",
            "Name": "Jane Doe",
            "Type": "Dwolla",
            "Image": "http://www.dwolla.com/avatars/812-111-1111"
        },
        "Notes": "here's this month's rent!",
        "Status": "scheduled",
        "CreatedDate": "2014-09-12T20:37:37Z"
    }
}

Create a new Scheduled Transaction on behalf of the authorized user. Initial Status will be scheduled. Must fund payment with a bank-funding source.

HTTP Request

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

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

List Scheduled Transactions

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Total": 2,
        "Count": 2,
        "Results": [
            {
                "Id": "59be7670-343b-46a1-bbb0-7070c2ba1806",
                "ScheduledDate": "2014-09-10",
                "ExpectedClearingDate": "2014-09-15",
                "TransactionId": 329870,
                "Amount": 12,
                "FundingSource": "3eacc3e3f6da404aa5735911219f277",
                "AssumeCosts": true,
                "Destination": {
                    "Id": "812-111-1111",
                    "Name": "Jane Doe",
                    "Type": "Dwolla",
                    "Image": "http://uat.dwolla.com/avatars/812-111-1111"
                },
                "Notes": "scheduled 1",
                "Status": "processed",
                "CreatedDate": "2014-09-09T22:00:03Z"
            },
            {
                "Id": "1d7c80c6-8dcd-4219-8ddc-440909eccc0d",
                "ScheduledDate": "2014-09-10",
                "ExpectedClearingDate": "2014-09-15",
                "TransactionId": 329867,
                "Amount": 1,
                "FundingSource": "3eacc3e3f6da404aa5735911219f277",
                "AssumeCosts": false,
                "Destination": {
                    "Id": "812-111-1111",
                    "Name": "Jane Doe",
                    "Type": "Dwolla",
                    "Image": "http://uat.dwolla.com/avatars/812-111-1111"
                },
                "Notes": "This is a scheduled",
                "Status": "processed",
                "CreatedDate": "2014-09-09T21:58:14Z"
            }
        ]
    }
}

List the authorized user’s scheduled transactions.

HTTP Request

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

Optional Parameters

Parameter Description
status Filter scheduled transactions by their status. Possible values: scheduled, processed, failed.
limit Pagination: number of results to return.
skip Pagination: number of results to skip.

Response

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

Retrieve Scheduled Transaction

{
    "Success": true,
    "Message": "Success",
    "Response": {
        "Id": "d72b9f82-307e-4a35-9559-7889ea929db7",
        "ScheduledDate": "2014-09-11",
        "ExpectedClearingDate": "2014-09-16",
        "TransactionId": 330295,
        "Amount": 100,
        "FundingSource": "3eacc3e3f6da404aa5735911219f277",
        "AssumeCosts": false,
        "Destination": {
            "Id": "812-111-1111",
            "Name": "Jane Doe",
            "Type": "Dwolla",
            "Image": "http://uat.dwolla.com/avatars/812-111-1111"
        },
        "Notes": "This is a scheduled",
        "Status": "processed",
        "CreatedDate": "2014-09-10T21:05:39Z"
    }
}

Retrieve a scheduled transaction by its ID.

HTTP Request

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

Edit Scheduled Transaction

Edit the amount:

{
  "pin": 9999,
  "amount": 16
}

Response:

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

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

HTTP Request

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

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

Delete Scheduled Transaction

DELETE https://www.dwolla.com/oauth/rest/transactions/scheduled/d856d2ec-4098-4b3b-b20f-b2561ec85871

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

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

Delete a pending scheduled transaction created by the authorized user. Status must be scheduled. Cannot delete a processed or failed scheduled transaction.

HTTP Request

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

Delete all Scheduled Transactions

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

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

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

Delete all of an authorized user’s pending scheduled transactions. Will not delete any processed or failed scheduled transactions.

HTTP Request

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

Transaction Stats

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

Dwolla.transactionsStats(function(err, data){
  console.log(data);
});
puts Dwolla::Transactions.stats()

Response:

{
  "TransactionsCount" => 10,
  "TransactionsTotal" => 134.22
}
{
  "TransactionsCount": 5,
  "TransactionsTotal": 116.92
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "TransactionsCount": 5,
        "TransactionsTotal": 116.92
    }
}

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.

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

/**
 * EXAMPLE 1: 
 *   Fetch basic account information
 *   for a given Dwolla ID
 **/
$user = $Dwolla->getUser('812-546-3855');
if(!$user) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($user); } // Print user information
#   Fetch basic account information
#   for a given email address
puts Dwolla::Users.get('gordon@dwolla.com')
'''
    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:

{
  "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 gordon@dwolla.com:

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

Response

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

Get Full Account Info

/**
 * EXAMPLE 1: 
 *   Fetch account information for the
 *   account associated with the provided
 *   OAuth token
 **/
$me = $Dwolla->me();
if(!$me) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($me); } // Print user information
#   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"
}
{
    "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
/**
 * EXAMPLE 1: 
 * Fetch contacts of businesses near lat 45, lon 45
 **/
$contacts = $Dwolla->nearby(45,45);
if(!$contacts) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($contacts); } // Print contacts
?>
#   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:

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

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
/**
 * EXAMPLE 1: 
 *   Fetch last 10 contacts from the 
 *   account associated with the provided
 *   OAuth token
 **/
$contacts = $Dwolla->contacts('Ben');
if(!$contacts) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($contacts); } // Print contacts

/**
 * EXAMPLE 2: 
 *   Search through the contacts of the
 *   account associated with the provided
 *   OAuth token for 'David', return 20 
 *   "Dwolla" type results. 
 **/

$contacts = $Dwolla->contacts('David', array('dwolla'), 20);
if(!$contacts) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($contacts); } // Print contacts
?>
# 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"
  },
  { ... },
  { ... }
]
[
    {
        "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

/**
 * EXAMPLE 1: 
 *   Fetch account balance for the 
 *   account associated with the provided
 *   OAuth token
 **/
$balance = $Dwolla->balance();
if($balance == NULL) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { echo $balance; } // Print user's balance
#   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
{
    "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 10,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": "reflector@dwolla.com",
        "destinationType": "Email",
        "notes": "here's some money!",
        "metadata": {
            "foo": "bar"
        } 
    }
  ]
} 
items = [
  {
    :amount => 9.99,
    :destination => 'gordon@dwolla.com',
    :destinationType => 'Email'
  },
  {
    :amount => 30,
    :destination => '812-742-3301',
    :notes => 'money!!!',
    :metadata => {
      'something_optional' => 'foobar'
    }
  }
]

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

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

Response:

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

List Jobs

dwolla.getMassPayJobs(function(err, response) {
  console.log(response);
});
puts Dwolla::MassPay.get

Response:

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

Retrieve Job

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:

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

List a Job’s Items

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:

[
  {
    "JobId"           => "256f7554-9bcb-4399-97d8-a34c00bb20b1",
    "ItemId"          => 17053,
    "Destination"     => "reflector@dwolla.com",
    "DestinationType" => "email",
    "Amount"          => 0.01,
    "Status"          => "success",
    "TransactionId"   => 61966,
    "Error"           => nil,
    "CreatedDate"     => "2014-06-16T18:21:18Z",
    "Metadata"        => {
      "lol" => "foo",
      "bar" => "qux"
    }
  },
  {
    "JobId"           => "256f7554-9bcb-4399-97d8-a34c00bb20b1",
    "ItemId"          => 17054,
    "Destination"     => "812-713-9234",
    "DestinationType" => "dwolla",
    "Amount"          => 0.01,
    "Status"          => "failed",
    "TransactionId"   => nil,
    "Error"           => "The user to send to could not be found.",
    "CreatedDate"     => "2014-06-16T18:21:18Z",
    "Metadata"        => nil
  }
]
{
  "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
  "ItemId": 13,
  "Destination": "reflector@dwolla.com",
  "DestinationType": "email",
  "Amount": 0.01,
  "Status": "success",
  "TransactionId": 4938766,
  "Error": null,
  "CreatedDate": "2014-04-18T05:51:34Z",
  "Metadata": {
      "some meta data":  "hello world!",
      "profound realization": "cats"
  }
},
{
  "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
  "ItemId": 14,
  "Destination": "812-713-9234",
  "DestinationType": "dwolla",
  "Amount": 0.01,
  "Status": "success",
  "TransactionId": 4938768,
  "Error": null,
  "CreatedDate": "2014-04-18T05:51:34Z",
  "Metadata": null 
}
{
    "Success": true,
    "Message": "Success",
    "Response": [
        {
            "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
            "ItemId": 13,
            "Destination": "reflector@dwolla.com",
            "DestinationType": "email",
            "Amount": 0.01,
            "Status": "success",
            "TransactionId": 4938766,
            "Error": null,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Metadata": {
                "some meta data":  "hello world!",
                "profound realization": "cats"
            }
        },
        {
            "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
            "ItemId": 14,
            "Destination": "812-713-9234",
            "DestinationType": "dwolla",
            "Amount": 0.01,
            "Status": "success",
            "TransactionId": 4938768,
            "Error": null,
            "CreatedDate": "2014-04-18T05:51:34Z",
            "Metadata": null 
        }
    ]
}

Retrieve the items for a particular MassPay job.

HTTP Request

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

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

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

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

Response:

{ 
  JobId: '9ed0f61a-5cc9-4f36-a7c1-a37e0001c55e',
  ItemId: 424792,
  Destination: 'a@example.com',
  DestinationType: 'email',
  Amount: 0.01,
  Status: 'success',
  TransactionId: 290128,
  Error: null,
  CreatedDate: '2014-08-05T00:06:26Z',
  Metadata: null 
}
{
    "Success": true,
    "Message": "Success",
    "Response": {
        "JobId": "643f2db9-5b45-4755-a881-a3100178b6d7",
        "ItemId": 14,
        "Destination": "812-713-9234",
        "DestinationType": "dwolla",
        "Amount": 0.01,
        "Status": "success",
        "TransactionId": 4938768,
        "Error": null,
        "CreatedDate": "2014-04-18T05:51:34Z",
        "Metadata": {
            "some meta data":  "hello world!",
            "profound realization": "cats"
        }
    }
}

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

HTTP Request

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

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

Response:

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

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

/**
 * EXAMPLE 1: 
 *   Request money ($1.00) to a Dwolla ID 
 **/
$requestId = $Dwolla->request('812-713-9234', 1.00);
if(!$requestId) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { echo("Request ID: {$requestId} \n"); }
# 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', 'reflector@dwolla.com', _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:

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

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

If successful, you’ll receive this response:

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

/**
 * EXAMPLE 1: 
 *   Get request by ID
 **/
$request = $Dwolla->requestById($requestId);
if(!$request) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($request); }
# 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:

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

Fulfill Money Request

/**
 * EXAMPLE 1: 
 *   Fulfill request with ID
 **/
$fulfilledRequest = $Dwolla->fulfillRequest($requestId, $pin);
if(!$fulfilledRequest) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($fulfilledRequest); }
# 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:

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

Cancel a Money Request

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

/**
 * EXAMPLE 1: 
 *   Cancel request with ID
 **/
$canceledRequest = $Dwolla->cancelRequest($requestId);
if(!$canceledRequest) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { echo("Canceled? {$canceledRequest} \n"); }
# 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:

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

HTTP Request

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

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

$status = $Dwolla->getAutoWithdrawalStatus();
if(!$status) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($status); } // Print status
#   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"
  }
}

If disabled, you’ll get this response:

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

$status = $Dwolla->toggleAutoWithdrawalStatus('true', '12345');
if(!$status) { echo "Error: {$Dwolla->getError()} \n"; } // Check for errors
else { print_r($status); } // Print status
# 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"
{
    "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