Dwolla V2 Python client. For the V1 Python client see Dwolla/dwolla-python.
pip install dwollav2
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_ID'], secret = os.environ['DWOLLA_SECRET'])client = dwollav2.Client(
id = os.environ['DWOLLA_ID'],
secret = os.environ['DWOLLA_SECRET'],
environment = 'sandbox'
)environment defaults to 'production'.
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.
# config/initializers/dwolla.rb
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.
Tokens can be used to make requests to the Dwolla V2 API. There are two types of 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:
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 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 https://uat.dwolla.com/applications (sandbox) or https://www.dwolla.com/applications (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 dwolla.com 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:
# http://www.twobotechnologies.com/blog/2014/02/importance-of-state-in-oauth2.html
state = binascii.b2a_hex(os.urandom(15))
auth = client.Auth(redirect_uri = 'https://yoursite.com/callback',
scope = 'ManageCustomers|Funding',
state = state)
# redirect the user to dwolla.com for authorization
redirect_to(auth.url)
# exchange the code for a token
token = auth.callback({'code': '...', 'state': state})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)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.
# GET api.dwolla.com/resource?foo=bar
token.get('resource', foo = 'bar')
# POST api.dwolla.com/resource {"foo":"bar"}
token.post('resource', foo = 'bar')
# POST api.dwolla.com/resource multipart/form-data foo=...
token.post('resource', foo = ('mclovin.jpg', open('mclovin.jpg', 'rb'), 'image/jpeg'))
# PUT api.dwolla.com/resource {"foo":"bar"}
token.put('resource', foo = 'bar')
# DELETE api.dwolla.com/resource
token.delete('resource')Requests return a Response.
res = token.get('/')
res.status
# => 200
res.headers
# => {'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=/; domain=.dwolla.com; HttpOnly', 'x-request-id'=>'69a4e612-5dae-4c52-a6a0-2f921e34a88a', 'cf-ray'=>'28ac1f81875941e3-MSP'}
res.body['_links']['events']['href']
# => 'https://api-uat.dwolla.com/events'If the server returns an error, a dwollav2.Error (or one of its subclasses) will be raised.
dwollav2.Errors are similar to Responses.
try:
token.get "/not-found"
except dwollav2.NotFoundError:
e.status
# => 404
e.headers
# => {"server"=>"cloudflare-nginx", "date"=>"Mon, 28 Mar 2016 15:35:32 GMT", "content-type"=>"application/vnd.dwolla.v1.hal+json; profile=\"http://nocarrier.co.uk/profiles/vnd.error/\"; charset=UTF-8", "content-length"=>"69", "connection"=>"close", "set-cookie"=>"__cfduid=da1478bfdf3e56275cd8a6a741866ccce1459179332; expires=Tue, 28-Mar-17 15:35:32 GMT; path=/; domain=.dwolla.com; HttpOnly", "access-control-allow-origin"=>"*", "x-request-id"=>"667fca74-b53d-43db-bddd-50426a011881", "cf-ray"=>"28ac270abca64207-MSP"}
e.body.code
# => "NotFound"
except dwollav2.Error:
# ...See https://docsv2.dwolla.com/#errors for more info.
dwollav2.AccessDeniedErrordwollav2.InvalidCredentialsErrordwollav2.NotFoundErrordwollav2.BadRequestErrordwollav2.InvalidGrantErrordwollav2.RequestTimeoutErrordwollav2.ExpiredAccessTokenErrordwollav2.InvalidRequestErrordwollav2.ServerErrordwollav2.ForbiddenErrordwollav2.InvalidResourceStateErrordwollav2.TemporarilyUnavailableErrordwollav2.InvalidAccessTokenErrordwollav2.InvalidScopeErrordwollav2.UnauthorizedClientErrordwollav2.InvalidAccountStatusErrordwollav2.InvalidScopesErrordwollav2.UnsupportedGrantTypeErrordwollav2.InvalidApplicationStatusErrordwollav2.InvalidVersionErrordwollav2.UnsupportedResponseTypeErrordwollav2.InvalidClientErrordwollav2.MethodNotAllowedErrordwollav2.ValidationError
After checking out the repo, run pip install -r requirements.txt to install dependencies.
Then, run python setup.py 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 https://github.com/Dwolla/dwolla-v2-python.
The package is available as open source under the terms of the MIT License.