> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.npmjs.com/package/dwolla) with [source code](https://github.com/Dwolla/dwolla-typescript) 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](https://www.npmjs.com/package/dwolla) to distribute this package.

```shell theme={"dark"}
# 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](https://dashboard.dwolla.com/applications)
* Sandbox: [https://dashboard-sandbox.dwolla.com/applications](https://dashboard-sandbox.dwolla.com/applications)

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

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
// 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: "jane.doe@example.com",
});

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

### Authentication

The SDK supports multiple authentication schemes:

#### OAuth2 Client Credentials (Recommended)

```typescript theme={"dark"}
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:

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

### Working with Transfers

```typescript theme={"dark"}
// 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

```typescript theme={"dark"}
// 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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
// 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:

```typescript theme={"dark"}
// 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:

```typescript theme={"dark"}
// 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](https://discuss.dwolla.com/) or by [creating a GitHub issue](https://github.com/Dwolla/dwolla-typescript/issues/new).
* 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.