skip to navigation
skip to content

dwollav2 1.1.7

Official Dwolla V2 API client

Latest Version: 1.2.0

# 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
([UAT][apuat], [Production][approd]).


client = dwollav2.Client(id = os.environ['DWOLLA_ID'], secret = os.environ['DWOLLA_SECRET'])

### Using the sandbox environment (optional)

client = dwollav2.Client(
id = os.environ['DWOLLA_ID'],
secret = os.environ['DWOLLA_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(
id = os.environ['DWOLLA_ID'],
secret = os.environ['DWOLLA_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:


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:


state = binascii.b2a_hex(os.urandom(15))
auth = client.Auth(redirect_uri = ''
scope = 'ManageCustomers|Funding',
state = state)

# redirect the user to for authorization

# exchange the code for a token
token = auth.callback({'code': '...', 'state': state})

### 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 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.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  
File Type Py Version Uploaded on Size
dwollav2-1.1.7.tar.gz (md5) Source 2016-06-20 8KB