Create an exchange for a customer #

This section contains information on how to create an exchange for an end-user/Customer. The creation of an exchange serves as the “hand-shake” between Dwolla and a trusted ecosystem partner. The creation of an exchange requires a _link to the exchange partner and tokenized data which encapsulates limited permissioned access between an ecosystem partner and Dwolla.

HTTP request #

POST https://api.dwolla.com/customers/{id}/exchanges

Request parameters #

Parameter	Required	Type	Description
_links	yes	object	A _links JSON object containing an exchange partner link. See example raw request and response below.
token	conditional	string	A third party provider processor token. Required for MX integration.
finicity	conditional	object	Finicity resource object containing access key receipt information. Required for Finicity integration. See `finicity` JSON object below (including nested `product` and `accessPeriod` JSON objects).

Finicity JSON Object #

Parameter	Type	Description
profile	integer	Int value obtained by the party integrating with Finicity.
version	string	String value obtained by the party integrating with Finicity.
receiptId	string	String value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response.
receiptVersion	string	String value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response.
customerId	string	String value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response.
partnerId	integer	Int value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response.
products	object	Array of Finicity Product objects obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response.

Finicity product JSON Object

Parameter	Type	Description
product	string	String value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response
accountId	string	String value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response
accessPeriod	object	Finicity Access Period objects obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response

Finicity accessPeriod JSON object

Parameter	Type	Description
type	string	String value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response
startTime	integer	Int value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response
endTime	integer	Int value obtained by the party integrating with Finicity. From Finicity `https://api.finicity.com/aggregation/v1/partners/accessKey` response

HTTP status and error codes #

HTTP Status	Code	Description
201	Created	The Dwolla API accepted the request and created an exchange resource. You can reference the Location header to retrieve a link that represents the created exchange resource.
400	ValidationError	Validation error(s) present. See embedded errors list for more details.
401	InvalidScope	Missing or invalid scopes for requested endpoint.
404	NotFound	The requested resource was not found.

Request and Response (MX) #

JavaScript

// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var customerUrl =
  "https://api.dwolla.com/customers/74a207b2-b7b7-4efa-8bf8-582148e7b980";
var requestBody = {
  _links: {
    "exchange-partner": {
      href: "https://api.dwolla.com/exchange-partners/292317ec-e252-47d8-93c3-2d128e037aa4",
    },
  },
  token: "someMXProcessorToken",
};

dwolla
  .post(`${customerUrl}/exchanges`, requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api.dwolla.com/exchanges/fcd15e5f-8d13-4570-a9b7-7fb49e55941d'

Request and Response (Finicity) #

JavaScript

// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var customerUrl =
  "https://api.dwolla.com/customers/74a207b2-b7b7-4efa-8bf8-582148e7b980";
var requestBody = {
  _links: {
    "exchange-partner": {
      href: "https://api.dwolla.com/exchange-partners/292317ec-e252-47d8-93c3-2d128e037aa4",
    },
  },
  finicity: {
    profile: 3,
    version: "1",
    receiptId: "cr_4N47ou7SlppuIxq0ZUtACh10vYcloY",
    receiptVersion: "1",
    customerId: "5454874858510164117",
    partnerId: 2445583946651,
    products: [
      {
        product: "moneyTransferDetails",
        accountId: "1015199035827334916",
        accessPeriod: {
          type: "timeframe",
          startTime: "2022-07-06",
          endTime: "2022-08-16T06:06:20Z",
        },
      },
    ],
    timestamp: "2022-07-11T06:06:23Z",
  },
};

dwolla
  .post(`${customerUrl}/exchanges`, requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api.dwolla.com/exchanges/fcd15e5f-8d13-4570-a9b7-7fb49e55941d'

Create an exchange for an account

Retrieve an exchange

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.