Dwolla Developers Logo
Home
Guides
Concepts
SDKs & Tools
API DocsOpen in new tabChangelog
Get API Keys
API DocsOpen in new tabChangelog
JavaScript
Get API Keys

Build an Integration

Integrate a third-party application with a Dwolla client.

By supporting integrations with third-party applications, Dwolla’s clients can gain access to additional tools and services they need to grow their businesses. A partner integration allows a Dwolla Client to authenticate with Dwolla and authorize a third party application to interact with data stored in Dwolla via the application's user interface. Publish your integration to Dwolla’s marketplace and make our clients your clients too.

This document is here to help navigate your way through creating an integration with the Dwolla Platform.

Terminology

Before learning more on the authorization process, review some of the key terms used in this guide:

  • Partner (Integrator): You, the service provider creating a partner integration with Dwolla
  • Client: Dwolla’s clients, applications utilizing Dwolla to power their payments
  • Client Application: An application created in the sandbox to validate your integration testing
  • Partner Portal: Interface for Dwolla Partners to create and manage partner integrations
  • Partner Integration: An integration created in the Partner Portal. Each integration receives a key & secret to use when integrating
  • Key: A unique key identifying your partner integration, and used to integrate with the Dwolla API. This value is considered public, and will be passed in URLs during the authorization flow.
  • Secret: A secret value for your partner integration used to integrate with the Dwolla API. This value should be protected and is considered private.
  • OAuth Redirect URL: The URL where your integration will handle the Dwolla OAuth authorization flow. This URL must be publicly accessible.
  • Sandbox: Dwolla’s testing environment
  • Dashboard: Interface for Dwolla Clients to view application information and activity

Create a Partner Portal Account

To create a Partner Portal account, start here. To sign-up, you’ll need to provide your Name, Business Name, Business URL, Job Title, Email Address, Password, and Country. The email address provided must be verified to proceed to the Partner Portal.

After creating your Application in sandbox, you will need to contact partnerships@dwolla.com to finish setting up your integration. When you contact Dwolla, please provide the following pieces of information to begin the approval process:

Create a Test Integration

Once in the Partner Portal, you’ll have the ability to create a Test Integration. Select the “Create a Test Integration” button on the landing page of the Partner Portal. You’ll need to provide an Integration Name and the Oauth Redirect URL.

Create a Test Integration

Your test integration will have some permissions by default that will control what access you have to a Client’s data through the Dwolla API. These default permissions include the following:

If your test integration needs more permission to access other endpoints in the Dwolla API on the Client’s behalf, such as the ability to create/update data, please reach out to partnerships@dwolla.com and detail what your integration does and what endpoints you would like to access.

Validate your Test Partner Integration with a Sandbox Dwolla Client account

Request Authorization - redirect user to Dwolla

Dwolla's API enables you to interact with a Dwolla Client’s account on their behalf to perform actions such as creating Customer records, viewing transaction history, and more. To do so, your partner integration first needs to request authorization.

If you don’t have a Sandbox Dwolla Client account to test against, you can register for one here. Test partner integrations will not work with Production Dwolla Client accounts. You should use your own Sandbox Dwolla Client accounts when testing your partner integration.

Dwolla uses OpenID Connect which is a layer built on top of the OAuth 2.0 protocol to facilitate this authorization. The user (Dwolla Client) is first presented with a permission dialog for your partner integration, at which point the user can either approve the permissions requested, or reject them. Once the user approves, an authorization_code is sent to your partner integration, which will then be exchanged for an access_token and a refresh_token pair.

Info
The User (Dwolla Client) can revoke access at any time by visiting https://dashboard-sandbox.dwolla.com/account/integrations and disabling an integration.

The OpenID Connect flow is designed for web applications which leverages a browser-based interaction for user authentication.

Token lifetimes

Access tokens are short lived: 1 hour. Refresh tokens are long lived: 60 days. A refresh token can be used within 60 days to generate a new access_token and refresh_token pair. So long as you refresh your authorization at least every 60 days, your partner integration can maintain authorization indefinitely without requiring the user to re-authorize.

Step 1

To start the OpenID flow, construct the initiation URL which the user will visit in order to grant permission to your integration. It describes who the Partner Integration is (client_id), and where the user should be redirected to after they grant or deny permissions to your integration (redirect_uri). You will use the key from the Partner Portal as your client_id.

Example URL Format
plaintext
https://accounts-sandbox.dwolla.com/auth?client_id=/<key>&redirect_uri=/<redirectUri>&response_type=code`

Request parameters

ParameterDescriptionclient_idPartner Integration key. The key for the integration created above. (Can be retrieved in the Partner Portal) Partner Portalredirect_uriURL where the user will be redirected to after accepting or rejecting permissions. The value of this parameter must match the value specified on the integration in the Partner Portal. (We compare: protocol, subdomain, domain, tld, and file path. Additional query string parameters are ignored)response_typeThis must always be set with the value code.
Info
Remember to url-encode all query string parameters

Step 2

After redirecting, you will be prompted to login to Dwolla Sandbox with your test Client account. After logging in, you will be prompted to grant authorization to the partner integration using the account with which you just authenticated. This step is simulating what a Client of Dwolla’s would do when enabling your partner integration.

Sandbox Login Screen

Step 3

After logging in to the Client account, you will be asked to approve the Partner Integration access to the Client account.

Step 4

Once validated, Dwolla will redirect the user to the partner integration’s redirect URI with a query parameter called “code” if the Client approves the request. If the Client did not approve the request, Dwolla will redirect Client to the partner integration’s redirect URI with two query parameters: error & error_description. These values should be used to display a meaningful error message to the user in your application.

Auth Flow Callback

Step 5: Finish authorization - exchange code for access token

As mentioned in the previous step, the "code" query parameter will need to be exchanged for a Dwolla access token and refresh token pair, requiring an API POST to the https://accounts-sandbox.dwolla.com/token endpoint with a x-www-form-urlencoded form request with the following attributes:

  • "Authorization" header with the key and secret for your integration joined by a ‘:’, then base64 encoded. The key and secret can be found in the Partner Portal
    • Authorization: Basic <Base64(key:secret)>
  • "Content-Type" header with value: application/x-www-form-urlencoded
  • "Body" form parameters (key: value)
    • code: the code received from Dwolla via a query parameter.
      Info
      This code has an expiry time of 60 seconds. If not exchanged within 60 seconds you’ll need to prompt the user to restart the OpenID flow.
    • grant_type: authorization_code
    • redirect_uri: the OAuth Redirect Url set when creating your test integration
Example request
JavaScript
const auth = dwolla.auth({ redirect_uri: "https://mysite.com/dwolla/callback" })
auth.url # => "https://accounts.dwolla.com/auth?response_type=code&client_id=my-client-id&redirect_uri=https%3A%2F%2Fmysite.com%2Fdwolla%2Fcallback"

auth.callback(code: "my-code").then(token => {
  token.access_token // => "new-access-token"
  token.get("customers")
})

Step 6

The API POST to the token endpoint will return a JSON response that includes the fields "access_token" and "refresh_token". The access_token can be leveraged to call the API on behalf of the account that granted the permissions. If the token expires, the refresh_token should be used to get a new access_token.

Example response
json
{
  "access_token": "zNLXAACWfCOb859MBGR12x4I67tWJB7y6eUQVdQT8zsLabBk8R",
  "token_type": "Bearer",
  "refresh_token": "YY5Upft2c9Ci0OOWPijyHrOsEdnaoeZGAjAtLVwlpgb2LD4Zf8",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI3ZTE1ZGZjMy0wNGU2LTRlYTYtOTYwNS1hMzYzMDE1NDcxOGEiLCJhdWQiOiJmS1NDM2JRYkxleHlURFNYVnZUdjdEZjB6NW93NTJZTTlUb3RiS2VLcnljblluS3duWCIsImFtciI6WyJwdyJdLCJpc3MiOiJkd29sbGEuY29tIiwiZXhwIjoxNTU5MDkyMzUwLCJpYXQiOjE1NTkwNjM1NTB9.VzJN0VFV_SKkwZM2gM1lNJUvhtjRmUXuZLgpUaVJmIdMoV3lbbK677e-_CPXviniLEtI_pebTTyJP6Uan_IG-A"
}

Step 7: Refresh authorization

A refresh token can be used to refresh authorization on the account. A new access token and refresh token pair will be returned after making a successful API POST request to the token exchange endpoint.

HTTP request

Production: POST https://api.dwolla.com/token Sandbox: POST https://api-sandbox.dwolla.com/token

Including the Content-Type: application/x-www-form-urlencoded header, the request is sent to the token endpoint with the following form-encoded parameters:

ParameterRequiredTypeDescriptionclient_idyesstringPartner Integration key. Navigate to https://partners.dwolla.com for your partner integration key.client_secretyesstringPartner Integration secret. Navigate to https://partners.dwolla.com for your partner integration secret.grant_typeyesstringThis must be set to refresh_token.refresh_tokenyesstringA valid refresh token.

Step 8

The API POST to the token endpoint for retrieving a new access token and refresh token pair will return a JSON response that includes the fields "access_token" and "refresh_token". These tokens can be used in the same way as the ones generated in Step 6 are.

json
{
  "access_token": "uBa6RPl9Btb2M41ysgRmGnGAxpBZe9vqqHUjedQRFi6hTQ9b9C",
  "token_type": "Bearer",
  "refresh_token": "YY5Upft2c9Ci0OOWPijyHrOsEdnaoeZGAjAtLVwlpgb2LD4Zf8",
  "expires_in": 3600,
  "refresh_expires_in": 60000
}

Subscribing to Dwolla Webhooks

Subscribing to Dwolla webhooks for a Dwolla Client’s account will allow your partner integration to receive notifications when actions happen on a client’s account, thereby allowing you to take actions in your partner integration. Reference a list of all available webhook events in our developer documentation. You can leverage the access_token access token granted in Step 6 or Step 8 to create a webhook subscription.

2020 All Rights Reserved

Dwolla

  • About
  • Blog
  • Pricing
  • Contact Sales
  • Terms of Service
  • Privacy Policy
Financial institutions play an important role in our network.

Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.

Sponsorship and Settlement of Push-to-Debit payment services provided by MetaBank®, N.A.
Push-to-Debit payments are typically available within 30 minutes.