In order to interact with a user's Dwolla account (e.g. charging, refunding, facilitating payments), you will need to first have that user authenticate into your Dwolla application. This method of authentication works very similarly to Facebook and Twitter's authentication flow. The user is first presented with a permission dialog for your application, in which point the user can either approve the request permissions, or reject them. Once the user approves, a code is sent to your application server, which can be exchanged for a never-expiring OAuth access token. Follow this 3-step guide to start OAuth'ing today.
Dwolla conforms to OAuth version 2. Read more about this standard, here. You may also use a pre-made Dwolla OAuth module such as this one for Ruby.
User Experience
Here's a typical user experience of Dwolla's OAuth + REST API:
-
Customer initiates a checkout on the merchant site, and clicks on a "Pay with Dwolla" button.
-
OAuth permissions dialog pops up (only during first interaction).
-
Customer inputs their PIN code.
-
Merchant server interacts with the customer's Dwolla account.
Obtaining an OAuth access token
First, redirect the user to the permission page:
Include the required permissions scope, and redirection URL for once the user accepts or rejects your request.
Request Parameters:
| Param | Description | |
|---|---|---|
| * | client_id | Consumer key for the application |
| * | response_type | Dwolla OAuth uses the 'code' response type only. |
| redirect_uri | URL to return the user to after they approve or deny the authentication request. If not provided, will default to registered OAuth Callback URL. | |
| * | scope | User's permissions to request access to. Possible values: "Send", "Transactions", "Balance", "Request", "Contacts", "AccountInfoFull", "Funding". Multiple scopes should be chained together with a pipe ("|") symbol. Read more about the scopes ». |
* A note about "state" parameters: While we don't natively support the "state" parameter, you can easily pass that (and any other parameter) by simply specifying them as part of the redirect_uri parameter.
Request format:
https://www.dwolla.com/oauth/v2/authenticate?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope={scope}
Request example:
https://www.dwolla.com/oauth/v2/authenticate?client_id=abcdefg&response_type=code&redirect_uri=https%3A%2F%2Fwww.myredirect.com%2Fredirect&scope=send%7Ctransactions
Here's what the permissions popup looks like:
Second, the user will be redirected back to your site.
The user will be taken back to the supplied redirection URL, along with a temporary code. Note that this is not your access token, yet. You will need to exchange this temporary code for an actual OAuth access token.
Response Parameters:
| Param | Description |
|---|---|
| code | Verification code used in step 3. |
In a successful approval:
{redirect_url}?code={code}
In a failure, or rejection:
{redirect_url}?error=access_denied&error_description=The+user+denied+the+request.
Third, you will exchange the code for an access token.
In this final step of the OAuth flow, you will exchange the code granted on step 2 for a never-expiring Dwolla OAuth access token. In order to do so, you will need to make an HTTP request from your application server, to the Dwolla authentication server.
Request Parameters:
| Param | Description | |
|---|---|---|
| * | client_id | Consumer key for the application. |
| * | client_secret | Consumer secret for the application. |
| * | grant_type | Use a value of 'authorization_code' for a web server application. |
| redirect_uri | The redirect_uri used when the user was redirected for authentication in step 1. | |
| * | code | Code from redirect response in step 2. |
Request format:
https://www.dwolla.com/oauth/v2/token?client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code&redirect_uri={redirect_uri}&code={code}
Request example:
https://www.dwolla.com/oauth/v2/token?client_id=abcdefg&client_secret=abcdefg&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fwww.myredirect.com%2Fredirect&code=abcdefg
Dwolla's authentication server will respond to your request with the following formats, depending on whether your request was successful or not.
Response Parameters:
| Param | Description |
|---|---|
| access_token | Access token used to make authorized requests. |
| error | Error type if an error occurred. |
| error_description | Error description if an error occurred. |
A successful request will respond with:
{
"access_token": "abcdefg"
}
A failed request will respond with:
{
"error": "access_denied",
"error_description": "Application is suspended."
}
OAuth Scopes
When authenticating a user into your Dwolla application, you must explicitly specify which access scopes you will require. This helps users better understand what kind of account permissions you require, and which permissions they are granting you application. Multiple scopes may be scoped in your authorization request using the pipe ("|") character (e.g. scope=send|transactions|etc).
Requested scopes must also be enabled on your application settings (https://www.dwolla.com/applications), otherwise, authenticating will respond with an error stating that your application requested invalid scopes.
| Scope Name | Scope Description | |
|---|---|---|
 |
AccountInfoFull | Detailed information about the authenticated account |
 |
Contacts | Contacts of the authenticated account |
 |
Transactions | Transaction details and listing |
 |
Balance | Dwolla balance of the authenticated account |
 |
Send | Send money from the authenticated account |
 |
Request | Initiate a money request, originating from the authenticated account |
 |
Funding | Funding sources (i.e. bank accounts) linked to the authenticated account |