Initiate a transfer #

This section covers how to initiate a transfer from either a Dwolla Account or Dwolla API Customer resource.

Prevent duplicate transfers with idempotency key #

To prevent an operation from being performed more than once, Dwolla supports passing in an Idempotency-Key header with a unique key as the value. Multiple POSTs with the same idempotency key won't result in multiple resources being created.

For example, if a request to initiate a transfer fails due to a network connection issue, you can reattempt the request with the same idempotency key to ensure that only a single transfer is created.

Refer to our idempotency key section to learn more.

HTTP request #

POST https://api.dwolla.com/transfers

Request parameters #

Parameter	Required	Type	Description
_links	yes	object	A _links JSON object describing the desired `source` and `destination` of a transfer. Reference the Source and Destination object to learn more about possible values for `source` and `destination`.
amount	yes	object	An amount JSON object. Reference the amount JSON object to learn more.
metadata	no	object	A metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters).
fees	no	array	An array of fee JSON objects that contain unique fee transfers. Reference the facilitator fee JSON object to learn more.
clearing	no	object	A clearing JSON object that contains `source` and `destination` keys to slow down or expedite a transfer. Reference the clearing JSON object to learn more.
achDetails	no	object	An ACH details JSON object which represents additional information sent along with a transfer to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. Reference the achDetails JSON object to learn more
rtpDetails	no	object	An RTP® details JSON object which represents additional information sent along with an RTP® credit transfer to the receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. Reference the rtpDetails JSON object to learn more
correlationId	no	string	A string value attached to a transfer which can be used for traceability between Dwolla and your application. Note: A correlationId is not a replacement for an idempotency-key. Must be less than or equal to 255 characters and contain no spaces. Acceptable characters are: `a-Z`, `0-9`, `-`, `.`, and `_`. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID.
processingChannel	no	object	A processingChannel JSON object that contains a key-value pair with a string key and string value of `destination` and `real-time-payments`.

HTTP status and error codes #

HTTP Status	Error Message	Description
201	Created.	A transfer was created.
400	Funding source not found.	Double check the funding source Id, and make sure you are using the correct funding source Id.
400	Invalid funding source.	The `source` funding source must be verified in order to send funds. Make sure your `source` funding source is `verified`.
400	Metadata not supported for this type of transfer.	Metadata is unable to be passed in on transfers with a Balance Funding Source.
400	Sender // Receiver Restricted.	The `source` or `destination` Customer is either `deactivated` or `suspended` and not eligible for transfers.
400	Invalid amount	The supplied amount is greater than your transaction limit. This error can also be triggered for PAYG Clients if the amount is less than 10 cents. For more information on transaction limits for various Customer types, check out our Customer Types article.
400	Invalid amount	The supplied amount must be a positive number.
401	Invalid access token	Access token not valid. Generate a new one and try again.
403	Forbidden	Not authorized to create a transfer.
403	Forbidden	Invalid Funds Flow: this operation requires the funds flow (`facilitate`/`receive`/`send`) to be enabled.
429	TooManyRequests	Concurrent transfers with the given funding source are not supported. Please wait a short period of time before re-attempting the request. Note: We don’t support concurrent transfers sourced from a Dwolla balance.

Request and response #

The reference example below shows what a request looks like when sending a transfer. Please note this example is using same-day clearing to a Dwolla API Customer's bank account, part of Dwolla's API.

JavaScript

// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var requestBody = {
  _links: {
    source: {
      href: "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4",
    },
    destination: {
      href: "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C",
    },
  },
  amount: {
    currency: "USD",
    value: "1.00",
  },
  metadata: {
    paymentId: "12345678",
    note: "payment for completed work Dec. 1",
  },
  clearing: {
    destination: "next-available",
  },
  achDetails: {
    source: {
      addenda: {
        values: ["ABC123_AddendaValue"],
      },
    },
    destination: {
      addenda: {
        values: ["ZYX987_AddendaValue"],
      },
    },
  },
  correlationId: "8a2cdc8d-629d-4a24-98ac-40b735229fe2",
};

dwolla
  .post("transfers", requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'

Overview

Retrieve a transfer

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys

Dwolla

Product

Developers

Financial institutions play an important role in our network.

All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.