TypeScript

Use Dwolla’s SDK for TypeScript to build applications that interact with the Dwolla API to perform account-to-account payment functions.

dwolla is available on NPM with source code available on our GitHub page.

Getting Started

Installation

To begin using this SDK, you will first need to download and install it on your machine. We use npm to distribute this package.

# npm
$ npm install dwolla

# yarn
$ yarn add dwolla

# pnpm
$ pnpm add dwolla

# bun
$ bun add dwolla

[!NOTE] This package is published with CommonJS and ES Modules (ESM) support.

Initialization

Before any API requests can be made, you must first determine which environment you will be using, as well as fetch the application key and secret. To fetch your application key and secret, please visit one of the following links:

• Production: https://dashboard.dwolla.com/applications
• Sandbox: https://dashboard-sandbox.dwolla.com/applications

Finally, you can create an instance of Dwolla with your application credentials:

import { Dwolla } from "dwolla";

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

Making Requests

Once you’ve created a Dwolla client, you can make requests using the high-level SDK methods or low-level HTTP requests.

High-Level SDK Methods

The TypeScript SDK provides strongly-typed methods for all Dwolla API operations:

// Get root API information
const rootInfo = await dwolla.root.get();

// List customers
const customers = await dwolla.customers.list({
  limit: 10,
  offset: 0,
});

// Create a customer
const newCustomer = await dwolla.customers.create({
  firstName: "Jane",
  lastName: "Doe",
  email: "[e-mail]",
});

// Get customer details
const customer = await dwolla.customers.get({
  id: "customer-id-here",
});

Authentication

The SDK supports multiple authentication schemes:

OAuth2 Client Credentials (Recommended)

import { Dwolla } from "dwolla";

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

Application Access Token Creation

When creating application access tokens, you’ll need to provide Basic Authentication at the request level:

const result = await dwolla.tokens.create({
  basicAuth: process.env.DWOLLA_BASIC_AUTH ?? "",
}, {
  grantType: "client_credentials",
});

Working with Transfers

// Initiate a transfer
const transfer = await dwolla.transfers.create({
  _links: {
    source: {
      href: "https://api-sandbox.dwolla.com/funding-sources/source-id",
    },
    destination: {
      href: "https://api-sandbox.dwolla.com/funding-sources/destination-id",
    },
  },
  amount: {
    currency: "USD",
    value: "10.00",
  },
});

// Get transfer details
const transferDetails = await dwolla.transfers.get({
  id: "transfer-id-here",
});

// Cancel a transfer (if eligible)
await dwolla.transfers.cancel({
  id: "transfer-id-here",
});

Working with Funding Sources

// List customer funding sources
const fundingSources = await dwolla.customers.fundingSources.list({
  id: "customer-id-here",
});

// Create a funding source
const newFundingSource = await dwolla.customers.fundingSources.create({
  id: "customer-id-here",
  requestBody: {
    routingNumber: "222222226",
    accountNumber: "123456789",
    bankAccountType: "checking",
    name: "My Checking Account",
  },
});

// Get funding source balance
const balance = await dwolla.fundingSources.balance.get({
  id: "funding-source-id-here",
});

File Uploads

The SDK supports file uploads for document verification:

import { openAsBlob } from "node:fs";

const result = await dwolla.customers.documents.create({
  id: "customer-id-here",
  requestBody: {
    documentType: "license",
    file: await openAsBlob("path/to/document.jpg"),
  },
});

Error Handling

The SDK provides comprehensive error handling with typed error classes:

import { Dwolla } from "dwolla";
import * as errors from "dwolla/models/errors";

try {
  const result = await dwolla.customers.get({
    id: "invalid-customer-id",
  });
} catch (error) {
  if (error instanceof errors.NotFoundError) {
    console.log("Customer not found:", error.message);
    console.log("Status code:", error.statusCode);
  } else if (error instanceof errors.BadRequestError) {
    console.log("Bad request:", error.message);
  } else if (error instanceof errors.DwollaError) {
    console.log("API error:", error.message);
  }
}

Retries

The SDK supports configurable retry strategies:

// Configure retries globally
const dwolla = new Dwolla({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

// Configure retries per-operation
const result = await dwolla.customers.list({}, {
  retries: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

Server Selection

You can specify which Dwolla environment to use:

// Use sandbox environment
const dwolla = new Dwolla({
  server: "sandbox",
});

// Use production environment
const dwolla = new Dwolla({
  server: "prod",
});

// Use custom server URL
const dwolla = new Dwolla({
  serverURL: "https://api-sandbox.dwolla.com",
});

Standalone Functions

All SDK methods are also available as standalone functions for tree-shaking and smaller bundle sizes. This is particularly useful in serverless environments like AWS Lambda, Google Cloud Functions, or Vercel Edge Functions where minimizing bundle size improves cold start performance:

// AWS Lambda function example
import { customersGet, transfersCreate } from "dwolla";

export const handler = async (event) => {
  // Only import the specific functions you need
  const customer = await customersGet({
    security: {
      clientID: process.env.DWOLLA_CLIENT_ID ?? "",
      clientSecret: process.env.DWOLLA_CLIENT_SECRET ?? "",
    },
  }, {
    id: event.customerId,
  });

  // Create a transfer for this customer
  const transfer = await transfersCreate({
    security: {
      clientID: process.env.DWOLLA_CLIENT_ID ?? "",
      clientSecret: process.env.DWOLLA_CLIENT_SECRET ?? "",
    },
  }, {
    _links: {
      source: { href: event.sourceUrl },
      destination: { href: event.destinationUrl },
    },
    amount: {
      currency: "USD",
      value: event.amount,
    },
  });

  return {
    statusCode: 200,
    body: JSON.stringify({ transferId: transfer.headers.get("Location") }),
  };
};

Community

• If you have any feedback, please reach out to us on our forums or by creating a GitHub issue.
• While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we’ll do our best to include it in a future release.