node package manager


DwollaV2 Node

Build Status

Dwolla V2 Node client. For the V1 Node client see Dwolla/dwolla-node.

API Documentation


npm install dwolla-v2


Basic usage

var dwolla = require('dwolla-v2');
var client = new dwolla.Client({
  key: process.env.DWOLLA_APP_KEY,
  secret: process.env.DWOLLA_APP_SECRET,

Using the sandbox environment (optional)

var dwolla = require('dwolla-v2');
var client = new dwolla.Client({
  key: process.env.DWOLLA_APP_KEY,
  secret: process.env.DWOLLA_APP_SECRET,
  environment: 'sandbox',

Note: environment defaults to production.

Configuring an onGrant callback (optional)

An onGrant callback is useful for storing new tokens when they are granted. The onGrant callback is called with the Token that was just granted by the server and must return a Promise.

var dwolla = require('dwolla-v2');
var client = new dwolla.Client({
  key: process.env.DWOLLA_APP_KEY,
  secret: process.env.DWOLLA_APP_SECRET,
  onGrant: function(token) {
    return new Promise(...); // here you can return a Promise that saves a token to your database 


Tokens can be used to make requests to the Dwolla V2 API. There are two types of tokens:

Application tokens

Application tokens are used to access the API on behalf of a consumer application. API resources that belong to an application include: webhook-subscriptions, events, and webhooks. Application tokens can be created using the client_credentials OAuth grant type:

Note: If an application has the ManageCustomers scope enabled, it can also be used to access the API for White Label Customer related endpoints. Keep in mind, the application must belong to same Dwolla account that will be used when creating and managing White Label Customers in the API.

  .then(function(appToken) {
    return appToken.get('webhook-subscriptions');
  .then(function(res) {

Application tokens do not include a refresh_token. When an application token expires, generate a new one using client.auth.client().

Account tokens

Account tokens are used to access the API on behalf of a Dwolla account. API resources that belong to an account include customers, funding-sources, documents, mass-payments, mass-payment-items, transfers, and on-demand-authorizations.

There are two ways to get an account token. One is by generating a token at (Sandbox) or (Production).

You can instantiate a generated token by doing the following:

var accountToken = new client.Token({ access_token: "...", refresh_token: "..." });

The other way to get an account token is using the authorization_code OAuth grant type. This flow works by redirecting a user to in order to get authorization and sending them back to your website with an authorization code which can be exchanged for a token. For example:

var auth = new client.Auth({
  redirect_uri: '',
  scope: 'ManageCustomers',
  state: getRandomHex(), // optional - 
  verified_account: true, // optional 
  dwolla_landing: 'register', // optional 
// redirect to `auth.url` 
auth.callback(req.query) // pass the code and optional state to the callback 
  .then(function(token) {
    return token.get('customers');
  .then(function(res) {

Refreshing tokens

Tokens with refresh_tokens can be refreshed using client.auth.refresh(token), which takes a Token as its first argument and returns a promise containing a new token.

var oldToken = new client.Token({ refresh_token: 'sHzEauv7FVpga2BSHVecKqFmCUfuhbBa4JRuClFuYa5vUSUdhL' });
  .then(function(token) {
    return token.get('customers');
  .then(function(res) {

Initializing pre-existing tokens:

Tokens can be initialized with the following attributes:

new client.Token({
  access_token: "...",
  refresh_token: "...",
  expires_in: 123,
  scope: "...",
  account_id: "..."


Tokens can make requests using the #get, #post, and #delete methods. These methods return promises containing a response object detailed in the next section.

// GET 
token.get('resource', { foo: 'bar' });
// POST {"foo":"bar"}'resource', { foo: 'bar' });
// POST multipart/form-data foo=... 
var body = new FormData();
body.append('file', fs.createReadStream('mclovin.jpg'), {
  filename: 'mclovin.jpg',
  contentType: 'image/jpeg',
  knownLength: fs.statSync('mclovin.jpg').size
body.append('documentType', 'license')'resource', body);
// PUT {"foo":"bar"} 
token.put('resource', { foo: 'bar' });

Setting headers

To set additional headers on a request you can pass an object as the 3rd argument.

For example:'customers',
           { firstName: 'John', lastName: 'Doe', email: '' },
           { 'Idempotency-Key': 'a52fcf63-0730-41c3-96e8-7147b5d1fb01' });


token.get('customers').then(function(res) {
  // res.status   => 200 
  // res.headers  => Headers { ... } 
  // res.body     => Object or String depending on response type 
}, function(error) {
  // when the server return a status >= 400 


Bug reports and pull requests are welcome on GitHub at


The gem is available as open source under the terms of the MIT License.


  • 1.3.2 Strip domain from URLs provided to token.* methods.
  • 1.3.1 Update sandbox URLs from uat => sandbox.
  • 1.3.0 Refer to Client id as key.
  • 1.2.3 Use Bluebird Promise in Auth to prevent Promise undefined error.
  • 1.2.2 Upgrade node-fetch dependency to fix form-data compatibility ([#15][/Dwolla/dwolla-v2-node/issues/15])
  • 1.2.1 Add support for verified_account and dwolla_landing auth flags
  • 1.2.0 Reject promises with Errors instead of plain objects (#8)
  • 1.1.2 Fix issue uploading files (#4)
  • 1.1.1 Handle promises differently to allow all rejections to be handled (#5)