Official Python Wrapper for Dwolla's API v2
Latest commit dd4c229 Feb 3, 2017 @sausman sausman committed on GitHub Refer to Client id as key. (#13)


Build Status

Dwolla V2 Python client. For the V1 Python client see Dwolla/dwolla-python.

API Documentation


pip install dwollav2


Basic usage

Create a client using your application's consumer key and secret found on the applications page (UAT, Production).

client = dwollav2.Client(id = os.environ['DWOLLA_APP_KEY'], secret = os.environ['DWOLLA_APP_SECRET'])

Using the sandbox environment (optional)

client = dwollav2.Client(
  key = os.environ['DWOLLA_APP_KEY'],
  secret = os.environ['DWOLLA_APP_SECRET'],
  environment = 'sandbox'

environment defaults to 'production'.

Configure an on_grant callback (optional)

An on_grant callback is useful for storing new tokens when they are granted. The on_grant callback is called with the Token that was just granted by the server.

client = dwollav2.Client(
  key = os.environ['DWOLLA_APP_KEY'],
  secret = os.environ['DWOLLA_APP_SECRET'],
  on_grant = lambda t: save(t)

It is highly recommended that you encrypt any token data you store.


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.

application_token = client.Auth.client()

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:

account_token = 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:

For more information see the Request User Authorization section of the Dwolla V2 docs.

state = binascii.b2a_hex(os.urandom(15))
auth = client.Auth(redirect_uri = '',
                   scope = 'ManageCustomers|Funding',
                   state = state, # optional
                   verified_account = True, # optional
                   dwolla_landing = 'register') # optional

# redirect the user to for authorization

# exchange the code for a token using the variables provided to the redirect_uri in the query string
token = auth.callback(req.GET)

Refreshing tokens

Tokens with a refresh_token can be refreshed using client.Auth.refresh, which takes a Token as its first argument and returns a new token.

new_token = client.Auth.refresh(expired_token)

Initializing pre-existing tokens:

Tokens can be initialized with the following attributes:

client.Token(access_token = '...',
             refresh_token = '...',
             expires_in = 123,
             scope = '...',
             account_id = '...')


Tokens can make requests using the #get, #post, and #delete methods.

token.get('resource', foo = 'bar')

# POST {"foo":"bar"}'resource', foo = 'bar')

# POST multipart/form-data foo=...'resource', foo = ('mclovin.jpg', open('mclovin.jpg', 'rb'), 'image/jpeg'))

# PUT {"foo":"bar"}
token.put('resource', foo = 'bar')


Setting headers

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

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


Requests return a Response.

res = token.get('/')

# => 200

# => {'server'=>'cloudflare-nginx', 'date'=>'Mon, 28 Mar 2016 15:30:23 GMT', 'content-type'=>'application/vnd.dwolla.v1.hal+json; charset=UTF-8', 'content-length'=>'150', 'connection'=>'close', 'set-cookie'=>'__cfduid=d9dcd0f586c166d36cbd45b992bdaa11b1459179023; expires=Tue, 28-Mar-17 15:30:23 GMT; path=/;; HttpOnly', 'x-request-id'=>'69a4e612-5dae-4c52-a6a0-2f921e34a88a', 'cf-ray'=>'28ac1f81875941e3-MSP'}

# => ''


If the server returns an error, a dwollav2.Error (or one of its subclasses) will be raised. dwollav2.Errors are similar to Responses.

except dwollav2.NotFoundError:
  # => 404

  # => {"server"=>"cloudflare-nginx", "date"=>"Mon, 28 Mar 2016 15:35:32 GMT", "content-type"=>"application/vnd.dwolla.v1.hal+json; profile=\"\"; charset=UTF-8", "content-length"=>"69", "connection"=>"close", "set-cookie"=>"__cfduid=da1478bfdf3e56275cd8a6a741866ccce1459179332; expires=Tue, 28-Mar-17 15:35:32 GMT; path=/;; HttpOnly", "access-control-allow-origin"=>"*", "x-request-id"=>"667fca74-b53d-43db-bddd-50426a011881", "cf-ray"=>"28ac270abca64207-MSP"}

  # => "NotFound"
except dwollav2.Error:
  # ...

dwollav2.Error subclasses:

See for more info.

  • dwollav2.AccessDeniedError
  • dwollav2.InvalidCredentialsError
  • dwollav2.NotFoundError
  • dwollav2.BadRequestError
  • dwollav2.InvalidGrantError
  • dwollav2.RequestTimeoutError
  • dwollav2.ExpiredAccessTokenError
  • dwollav2.InvalidRequestError
  • dwollav2.ServerError
  • dwollav2.ForbiddenError
  • dwollav2.InvalidResourceStateError
  • dwollav2.TemporarilyUnavailableError
  • dwollav2.InvalidAccessTokenError
  • dwollav2.InvalidScopeError
  • dwollav2.UnauthorizedClientError
  • dwollav2.InvalidAccountStatusError
  • dwollav2.InvalidScopesError
  • dwollav2.UnsupportedGrantTypeError
  • dwollav2.InvalidApplicationStatusError
  • dwollav2.InvalidVersionError
  • dwollav2.UnsupportedResponseTypeError
  • dwollav2.InvalidClientError
  • dwollav2.MethodNotAllowedError
  • dwollav2.ValidationError
  • dwollav2.TooManyRequestsError
  • dwollav2.ConflictError


After checking out the repo, run pip install -r requirements.txt to install dependencies. Then, run python test to run the tests.

To install this gem onto your local machine, run pip install -e ..


Bug reports and pull requests are welcome on GitHub at


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


  • 1.2.0 Refer to Client id as key.
  • 1.1.8 Support verified_account and dwolla_landing auth flags
  • 1.1.7 Use session over connections for performance improvement (#8 - Thanks @bfeeser!)
  • 1.1.5 Fix file upload bug when using with Python 2 (#6)
  • 1.1.2 Add TooManyRequestsError and ConflictError
  • 1.1.1 Add
  • 1.1.0 Support per-request headers