Using Postman to explore and debug Dwolla's v2 API

(Spencer Hunter) #1

What Postman is and why you should use it

Postman, a Chrome application, is a powerful tool for testing calls to the Dwolla API. Whether you are new to Dwolla, want to explore the API, or are deep into your Dwolla integration debugging requests, Postman offers a simple interface to quickly consume the API. It’s my go-to app, I even use it on a daily basis when working with external developers!

One common issue I debug with developers is malformed requests. Whether it’s a mis-typed request parameter or you aren’t passing in the correct headers for the request, small issues like these can seriously delay the integration process.

With this in mind, I decided to put together a Postman collection— essentially a templated series of all requests in the API pointing towards our Sandbox environment. My hope is that you will find this collection useful in improving your development workflow efficiency. Read on for more info on getting set up with Postman and using the collection…

Setting up Postman and importing the Dwolla API v2 collection

To get started, make sure you have Google Chrome and can download Postman from the Chrome Web store (or the Mac app). Once you’re all set up with Postman, click the button below which will prompt you to open Postman and import the collection.

Run in Postman

The collection—“Dwolla API v2 - UAT”—will show up in the left-side pane. Here you’ll see folders corresponding to resources in the API.

Before you can start submitting requests you’ll need to configure a few variables within Postman, such as an OAuth account access token which is used to authenticate against the API.

Configuring environment variables

The collection is preconfigured to use environment/global variables that look like this: {{variableName}}. To import a template of these required (and optional) variables, click on the dropdown in the top right corner of the app to “Manage an Environment”.

On the pop-up window, select the import button to import the key/value pairs that make up the environment variables used throughout the collection. Unzip the file below and import the file named DwollaUATv2.postman_environment.json into Postman.

Link to Postman environment variables template

Once the environment variables collection is imported you’ll need to at least set a value for “accountToken” which is an OAuth account access token.

Where do you obtain an OAuth account access token?

After setting up a Sandbox account you’ll want to create an application. Be sure to enable the Send, Transactions, Funding, and ManageCustomers scopes when creating the application as they will be needed to call various protected resources in the API. On the view applications page you’ll click the “Create token” button underneath your client_id and client_secret, which will then generate an OAuth account access token that is issued to the created application. Set the generated token string as the “accountToken” value in your Postman environment.

Now that you have your account token set, click save and you’re ready to start calling the API.

Using the collection

It is recommended to start out by calling the root of the API to fetch your accountId; this should then be updated as an environment variable value. New environment variables such as transferId, masspaymentId, and customerId should then be set once these resources are created in the API.

The screenshot below shows fetching an Account’s list of funding sources. You’ll notice and inspect a few things when you select a request within the collection on the left sidebar: 1) a description of the endpoint you’re calling as well as required and optional parameters. 2) the request URL 3) the required headers and 4) a sample request body if it’s a POST request.

After clicking the blue “Send” button, you should then get a response back from the API allowing you to inspect: the response body (if applicable), response headers, and HTTP status code. Viewing sample JSON POST bodies provided in this collection will hopefully give you, as the developer, a point of reference as to what a request should look like.

Comfortable with using cURL to send requests to the API through the CLI or another language like Python? Postman contains a handy “Generate Code” button that allows to to see what the request looks like in a different language.

Questions about using Postman or have suggestions on improving the provided collection? Please don’t hesitate to reach out—we’re here to help!

API v2 - Invalid funding source ValidationError