Skip to main content

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
([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`

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

Files for dwollav2, version 1.1.1
Filename, size File type Python version Upload date Hashes
Filename, size dwollav2-1.1.1.tar.gz (8.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page