Type-Safe Payments: Introducing Dwolla's New TypeScript SDK

Integrating a payment API shouldn't feel like assembling furniture without instructions.

Yet here's what raw API integration often looks like: you misspell amount as ammount in a transfer request, deploy to production, and discover the bug when a payout fails silently. The API just returned a generic 400 error. For payment APIs, where mistakes have real consequences, this friction is a liability.

We've heard from developers who wanted a more robust, type-safe way to integrate. That’s why we've released the Dwolla TypeScript SDK, built with Speakeasy and generated from our OpenAPI spec to bring type-safe API integration to Node.js and TypeScript developers.

Instead of stitching together raw HTTP requests and hoping you got every field and header right, you work with typed methods like dwolla.customers.create() and dwolla.transfers.create(). TypeScript flags mistakes earlier, and the SDK handles OAuth token management so you authenticate once at initialization.

Here’s what’s inside.

Highlights at a Glance

• Full TypeScript support — Helps catch mistakes at compile-time, not in production
• Resource-based API design — dwolla.transfers.create() with full IntelliSense
• 180+ typed error classes — Handle failures precisely with InsufficientFundsError, ValidationError, etc.
• Generated from OpenAPI — Regularly updated with comprehensive coverage of 80+ operations

Getting Started

Install the SDK with your preferred package manager:

npm install dwolla
# or: yarn add dwolla | pnpm add dwolla | bun add dwolla

Initialize the client and make your first call:

import { Dwolla } from "dwolla";

const dwolla = new Dwolla({
  server: "simport { Dwolla } from "dwolla";

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

// List customers
const customers = await dwolla.customers.list({});
console.log(`Found ${customers._embedded?.customers?.length ?? 0}
customers`);

For the complete walkthrough (Sandbox account setup, credentials, environment configuration, and more) see the TypeScript SDK documentation.

What You Get

Type Safety That Catches Mistakes Early

Requests, responses, and errors have comprehensive type definitions. Typos become compile errors instead of production bugs.

Image: TypeScript catching an invalid Dwolla SDK request at compile time in IntelliJ IDEA.

What this means for you:

• Required fields are enforced at compile-time
• Response shapes are known. No more ”undefined is not an object” errors
• Refactoring is safer: Update the SDK, and TypeScript shows affected call sites where types change

Resource-Based API Design for Faster Development

Methods are organized by resources with full IntelliSense. Type ”dwolla.” and explore available operations. No memorizing endpoint paths or tab-switching to docs.

Image: TypeScript autocomplete in IntelliJ IDEA showing available Dwolla SDK resources

What this means for you:

• Autocomplete shows what's available as you type
• Hover over any method to see exactly what it expects
• Onboard new developers faster with discoverable APIs

Automatic OAuth2 Token Management

Provide credentials once at initialization. The SDK acquires and refreshes tokens automatically. No boilerplate token refresh logic cluttering your codebase.

180+ Typed Error Classes for Precise Handling

Catch and handle specific failures instead of parsing error messages with regex.

import * as errors from "dwolla/models/errors";
try {
  await dwolla.transfers.create({ /* ... */ });
} catch (error) {
  if (error instanceof errors.InsufficientFundsError) {
    // Prompt user to add funds
  } else if (error instanceof errors.ValidationError) {
    // Show field-level errors
  } else if (error instanceof errors.DwollaError) {
    console.error(`${error.statusCode}: ${error.message}`);
  }
}

What this means for you:

• Handle different failure modes with type-safe conditionals
• Access structured error data (statusCode, message, full response body)

And More

• Built-in retries — Transient failures are handled automatically with exponential backoff
• Tree-shakable for serverless — Import only what you need for smaller bundles
• Multi-runtime support — Works in Node.js, Bun, Deno, and modern browsers
• File uploads — Upload documents for customer verification using streams or blobs
• Custom HTTP hooks — Inject headers, log requests, or modify behavior with beforeRequest and requestError hooks
• Debug logging — Set DWOLLA_DEBUG=true to enable request and response logging

Why Use the TypeScript SDK?

Here's how it compares to the alternatives.

vs. Direct API Calls

You can always call the Dwolla API directly using fetch or any HTTP client. It works, but you're responsible for:

• Token management — Obtaining tokens, tracking expiration, refreshing before they expire
• Header construction — Getting Content-Type and Accept headers exactly right
• Error handling — Parsing error responses and determining what went wrong
• Retries — Implementing backoff logic for transient failures
• Type safety — None. Typos in the request body compile just fine.

// Direct API call (fetch)
const token = await getToken(); // You manage this
const res = await fetch("https://api-sandbox.dwolla.com/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/vnd.dwolla.v1.hal+json",
    Accept: "application/vnd.dwolla.v1.hal+json",
  },
  body: JSON.stringify({ firstName: "Jane", lastName: "Doe", email:
"jane@example.com" }),
});

// TypeScript SDK
import { Dwolla } from "dwolla";

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

await dwolla.customers.create({
  requestBody: { firstName: "Jane", lastName: "Doe", email:
"jane@example.com" },
});

// dwolla-v2-node
const res = await client.post("customers", { firstName: "Jane", lastName: 
"Doe", email: "jane@example.com" });
const location = res.headers.get("location"); // Untyped

// TypeScript SDK
const res = await dwolla.customers.create({
  requestBody: { firstName: "Jane", lastName: "Doe", email: 
"jane@example.com" },
});
const location = res.location; // Typed string