Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

Official Dwolla V2 API client

Project description

# DwollaV2

![Build Status](

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

[API Documentation](

## Installation

pip install dwollav2

## `dwollav2.Client`

### Basic usage

Create a client using your application's consumer key and secret found on the applications page
([Sandbox][apsandbox], [Production][approd]).


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.

## `Token`

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`][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`][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][rua] 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:

`Token`s can be initialized with the following attributes:

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

## Requests

`Token`s 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:

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

## Responses

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

# => ''

## Errors

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

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`

## Development

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

## Contributing

Bug reports and pull requests are welcome on GitHub at

## License

The package is available as open source under the terms of the [MIT License](

## Changelog

- **1.2.4** Create a new session for each Token.
- **1.2.3** Check if IOBase when checking to see if something is a file.
- **1.2.2** Strip domain from URLs provided to token.* methods.
- **1.2.1** Update sandbox URLs from uat => sandbox.
- **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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
dwollav2-1.2.4.tar.gz (8.9 kB) Copy SHA256 hash SHA256 Source None Sep 13, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page