Quickstart - Dwolla Developer Portal

What you’ll do

By the end of this guide you’ll have an access token and a successful response from the Dwolla sandbox — the foundation for every other API call. From there, pick a funds flow to build your real integration.

  1. Create a sandbox account
    The Dwolla sandbox is a complete, free replica of production. You only need a valid email address to sign up.
    Create your sandbox account
    You’ll be prompted to verify your email, then redirected to the sandbox dashboard.
    Need more detail? See the Testing in the Sandbox guide.

  2. Grab your API key and secret
    From the sandbox dashboard, navigate to Applications to find your client_id and client_secret. Dwolla automatically creates an application for your sandbox account along with a $5,000 test balance.
    Treat your client_secret like a password. Never commit it to source control or expose it on the client side.

  3. Request an access token
    Exchange your credentials for an access token by POSTing to /token with grant_type=client_credentials. The Authorization header uses HTTP Basic auth: Base64(client_id:client_secret).

   curl -X POST 'https://api-sandbox.dwolla.com/token' \
     -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=client_credentials'

   // Using dwolla — https://github.com/Dwolla/dwolla-typescript
   import { Dwolla } from "dwolla";

const dwolla = new Dwolla({
     security: {
       clientID: process.env.DWOLLA_CLIENT_ID ?? "",
       clientSecret: process.env.DWOLLA_CLIENT_SECRET ?? "",
     },
     server: "sandbox",
   });

// The SDK requests and caches tokens automatically on your first API call.

# Using dwollav2 — https://github.com/Dwolla/dwolla-v2-python
import dwollav2

client = dwollav2.Client(
  key=os.environ["DWOLLA_APP_KEY"],
  secret=os.environ["DWOLLA_APP_SECRET"],
  environment="sandbox",
)

app_token = client.Auth.client()

<?php
// Using dwolla-php — https://github.com/Dwolla/dwolla-php
declare(strict_types=1);

require 'vendor/autoload.php';

use Dwolla;
use Dwolla\Models\Components;

$sdk = Dwolla\Dwolla::builder()
    ->setSecurity(
        new Components\Security(
            clientID: getenv('DWOLLA_CLIENT_ID'),
            clientSecret: getenv('DWOLLA_CLIENT_SECRET'),
        )
    )
    ->setServer('sandbox')
    ->build();

// The SDK requests and caches tokens automatically on your first API call.
?>

# Using dwolla-v2-ruby — https://github.com/Dwolla/dwolla-v2-ruby
require 'dwolla_v2'

$dwolla = DwollaV2::Client.new(
  key: ENV['DWOLLA_APP_KEY'],
  secret: ENV['DWOLLA_APP_SECRET']
) do |config|
  config.environment = :sandbox
end

app_token = $dwolla.auths.client

A successful response returns a JSON payload with an access_token, expiration, and scope. Tokens are valid for one hour — request a new one when yours expires.

Response

{
  "access_token": "0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q",
  "token_type": "bearer",
  "expires_in": 3600
}

  1. Make your first API call
    Use the access token as a Bearer credential to call the Root endpoint. The response contains the _links you’ll use to interact with the rest of the API — most importantly, your account URL.

    curl -X GET 'https://api-sandbox.dwolla.com/' \
  -H 'Accept: application/vnd.dwolla.v1.hal+json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

    const root = await dwolla.root.get();
console.log(root.object?._links?.account?.href);
// => "https://api-sandbox.dwolla.com/accounts/..."

    root = app_token.get("/")
print(root.body["_links"]["account"]["href"])
# => "https://api-sandbox.dwolla.com/accounts/..."

    <?php
$response = $sdk->root->get();

if ($response->root !== null) { // handle response } ?>


```ruby
root = app_token.get "/"
puts root._links["account"].href
# => "https://api-sandbox.dwolla.com/accounts/..."

Response

{
  "_links": {
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "account"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    }
  }
}

That account href is your Platform Account — you’ll reference it when creating funding sources, initiating transfers, and listing activity.

You did it

You’ve authenticated against the Dwolla API and made your first request. Next, pick the funds flow that matches your use case and start building.

Going deeper