Create an exchange session for an external party - Dwolla Developer Portal

Create an exchange session for an external party

To initiate Instant Account Verification for an external party using Dwolla’s trusted open banking partners, you’ll need to create an exchange session. Currently, Plaid and MX are the supported partners. When creating an exchange session, provide the following information:

_links.exchange-partner: The unique identifier for the desired open banking partner. Use the list exchange partners endpoint to retrieve available partners and their corresponding identifiers.
_links.redirect-url (conditional): A required redirect URL for Plaid mobile/native app integrations. This URL will be used to redirect the user back to your application after completing the authorization process. For Plaid web-based integrations and MX exchange sessions, this parameter is not required.

HTTP request

POST https://api.dwolla.com/external-parties/{id}/exchange-sessions

Request parameters

Property	Required	Type	Description
_links	yes	object	A HAL-JSON link that represents the Exchange Partner resource. This identifies the open banking provider used for creating the exchange session.

HTTP status and error codes

HTTP Status	Code	Message	Description
201	-	-	The Dwolla API accepted the request and created an exchange session resource. You can reference the Location header to retrieve a link that represents the created exchange session resource.
400	Invalid	/_links/exchange-partner/href is invalid.	ValidationError. Returned if the exchange partner URL is invalid.
400	Invalid	/_links/redirect-url/href is invalid.	ValidationError. Returned if the redirect URL is invalid.
400	Invalid	The provided redirect URL must exactly match one of the configured URLs for the account.	ValidationError. The redirect url does not match what is configured for the Dwolla account.
401	InvalidScope	Missing or invalid scopes for requested endpoint.
403	Forbidden	The exchange partner specified does not support this product.	Returned if the exchange partner specified does not support the creation of exchange sessions.
404	NotFound	The requested resource was not found.

Request and Response

POST https://api.dwolla.com/external-parties/74a207b2-b7b7-4efa-8bf8-582148e7b980/exchange-sessions
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
    "_links": {
        "exchange-partner": {
            "href": "https://api.dwolla.com/exchange-partners/292317ec-e252-47d8-93c3-2d128e037aa4"
        },
        "redirect-url": {
            "href": "https://www.yourdomain.com/iav-callback"
        }
    }
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d

/**
 * No example for this language yet.
 **/

# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
external_party_url = 'https://api.dwolla.com/external-parties/74a207b2-b7b7-4efa-8bf8-582148e7b980'
request_body = {
  _links: {
    'exchange-partner': {
      href: "https://api.dwolla.com/exchange-partners/292317ec-e252-47d8-93c3-2d128e037aa4"
    },
    'redirect-url': {
      href: "https://www.yourdomain.com/iav-callback"
    }
  }
}

exchange = app_token.post "#{external_party_url}/exchange-sessions", request_body
exchange.response_headers[:location] # => "https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d"

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
external_party_url = 'https://api.dwolla.com/external-parties/74a207b2-b7b7-4efa-8bf8-582148e7b980'
request_body = {
  '_links': {
    'exchange-partner': {
      'href': 'https://api.dwolla.com/exchange-partners/292317ec-e252-47d8-93c3-2d128e037aa4'
    },
    'redirect-url': {
      'href': 'https://www.yourdomain.com/iav-callback'
    }
  }
}

exchange = app_token.post('%s/exchange-sessions' % external_party_url, request_body)
exchange.headers['location'] # => 'https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d'

// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var externalPartyUrl =
  "https://api.dwolla.com/external-parties/74a207b2-b7b7-4efa-8bf8-582148e7b980";
var requestBody = {
  _links: {
    "exchange-partner": {
      href: "https://api.dwolla.com/exchange-partners/292317ec-e252-47d8-93c3-2d128e037aa4",
    },
    "redirect-url": {
      href: "https://www.yourdomain.com/iav-callback",
    },
  },
};

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