Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Dev 1561 #634

Merged
merged 3 commits into from
Nov 1, 2024
Merged

Dev 1561 #634

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0e8829e
add list available exchange connections endpoint for MX Open Banking
spencerhunter Nov 1, 2024
77266f8
clarify what availableConnectionToken is tied to
spencerhunter Nov 1, 2024
8045f68
Apply suggestions from code review
spencerhunter Nov 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions pages/docs/balance/api-reference/exchanges/create-exchange-for-a-customer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,12 @@ This section contains information on how to create an exchange for an end-user/C

### 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, Flinks and Plaid integrations. |
| finicity | conditional | object | Finicity resource object containing access key **receipt** information. **Required** for Mastercard integration. See `finicity` JSON object below (including nested `product` and `accessPeriod` JSON objects). |
| 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, Flinks and Plaid integrations. |
| mx | conditional | object | Contains an `availableConnectionToken`. The `availableConnectionToken` is tied to the [Exchange Sessions API](/docs/balance/api-reference/open-banking/create-exchange-session-for-a-customer) within Dwolla's Open Banking product. It is a unique identifier associated with each available exchange connection retrieved through the [list available exchange connections endpoint](/docs/balance/api-reference/open-banking/list-available-exchange-connections). |
| finicity | conditional | object | Finicity resource object containing access key **receipt** information. **Required** for Mastercard integration. See `finicity` JSON object below (including nested `product` and `accessPeriod` JSON objects). |

### Finicity JSON Object

Expand Down Expand Up @@ -167,8 +168,7 @@ Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
}
},
"mx": {
"memberId": "MBR-7e01bbe1-59cb-4256-a04b-71d4f6b6047d",
"accountId": "ACT-6bade551-7fbb-4ce1-a74d-f9b6425570ae"
"availableConnectionToken": "eyJhY2NvdW50SWQiOiJBQ1QtMjAxY2FkM2MtYzc2Yi00N2M1LWI3Y2QtMTkxY2FhNzdlZWM5IiwibWVtYmVySWQiOiJNQlItZGNjZWY0ZWMtOGM4MC00NTlmLTlhMGItMTc1ZTA0OTJmZWIzIn0="
}
}

Expand Down
112 changes: 112 additions & 0 deletions ...docs/balance/api-reference/open-banking/list-available-exchange-connections.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
layout: guides
product: balance
title: "List available exchange connections for a customer"
guide:
step: 4
meta:
title: "Dwolla API Reference | Open Banking: List available exchange connections"
description: "Retrieve a list of available exchange connections for a customer after they have completed the MX Connect widget flow. These connections represent external bank accounts that can be used to create funding sources for transfers."
---

spencerhunter marked this conversation as resolved.
Show resolved Hide resolved
import conceptsIcon from "../../../../../assets/images/content-images/content-icons/concepts.svg";

# List available exchange connections for a customer

This endpoint retrieves a list of a customer's external bank accounts that have been authorized through MX Connect. Each account is represented as an "available exchange connection" with details like the account name and associated `availableConnectionToken`. This information is essential for creating an exchange and corresponding funding source within Dwolla.

<InlineCTA
icon={conceptsIcon}
text="Understand the MX integration flow. Read the Open Banking concept article which outlines the seqence of steps."
href="/docs/balance/open-banking"
/>

### HTTP request

> `GET https://api.dwolla.com/customers/{id}/available-exchange-connections`

### Request parameters

| Parameter | Required | Type | Description |
| --------- | -------- | ------ | ------------------------------------ |
| id | yes | string | Customer resource unique identifier. |

### HTTP status and error codes

| HTTP Status | Code | Description |
| ----------- | -------- | ------------------------------------------------------------ |
| 200 | Ok | The Dwolla API accepted the request and returned a response. |
| 404 | NotFound | The requested resource was not found. Check Customer ID. |

### Request and response

```bash
GET https://api.dwolla.com/customers/1b54c81a-261f-4779-bb57-9405e6e00694/available-exchange-connections
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
"_links": {
"self": {
"href": "https://api.dwolla.com/customers/1b54c81a-261f-4779-bb57-9405e6e00694/available-exchange-connections",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"customers": {
"href": "https://api.dwolla.com/customers/1b54c81a-261f-4779-bb57-9405e6e00694",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
}
},
"_embedded": {
"available-exchange-connections": [
{
"availableConnectionToken": "eyJhY2NvdW50SWQiOiJBQ1QtMjAxY2FkM2MtYzc2Yi00N2M1LWI3Y2QtMTkxY2FhNzdlZWM5IiwibWVtYmVySWQiOiJNQlItZGNjZWY0ZWMtOGM4MC00NTlmLTlhMGItMTc1ZTA0OTJmZWIzIn0=",
"name": "XYZ Checking"
},
{
"availableConnectionToken": "eyJhY2NvdW50SWQiOiJBQ1QtNWY1ZWIwYTgtYTJiNC00NGQxLTk3ODYtMWVmOTM5NzZkYTU4IiwibWVtYmVySWQiOiJNQlItNTcxN2E5MDQtNDA0NC00YjQyLWIxMDctZDQyOWE0YjIzOGY5In0=",
"name": "ABC Savings"
}
]
}
}
```

```ruby
# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api.dwolla.com/customers/1b54c81a-261f-4779-bb57-9405e6e00694'

available_exchange_connections = app_token.get "#{customer_url}/available-exchange-connections"
available_exchange_connections._embedded['available-exchange-connections'][0].availableConnectionToken # => "eyJhY2NvdW50SWQiOiJBQ1QtMjAxY2FkM2MtYzc2Yi00N2M1LWI3Y2QtMTkxY2FhNzdlZWM5IiwibWVtYmVySWQiOiJNQlItZGNjZWY0ZWMtOGM4MC00NTlmLTlhMGItMTc1ZTA0OTJmZWIzIn0="
```

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

```python
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api.dwolla.com/customers/1b54c81a-261f-4779-bb57-9405e6e00694'

available_exchange_connection = app_token.get('%s/available-exchange-connections' % customer_url)
available_exchange_connection.body['_embedded']['available-exchange-connections'][0]['availableConnectionToken'] # => 'eyJhY2NvdW50SWQiOiJBQ1QtMjAxY2FkM2MtYzc2Yi00N2M1LWI3Y2QtMTkxY2FhNzdlZWM5IiwibWVtYmVySWQiOiJNQlItZGNjZWY0ZWMtOGM4MC00NTlmLTlhMGItMTc1ZTA0OTJmZWIzIn0='
```

```javascript
// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var customerUrl =
"https://api.dwolla.com/customers/1b54c81a-261f-4779-bb57-9405e6e00694";

dwolla
.get(`${customerUrl}/available-exchange-connections`)
.then(
(res) =>
res.body._embedded["available-exchange-connections"][0]
.availableConnectionToken
); // => 'eyJhY2NvdW50SWQiOiJBQ1QtMjAxY2FkM2MtYzc2Yi00N2M1LWI3Y2QtMTkxY2FhNzdlZWM5IiwibWVtYmVySWQiOiJNQlItZGNjZWY0ZWMtOGM4MC00NTlmLTlhMGItMTc1ZTA0OTJmZWIzIn0='
```
9 changes: 5 additions & 4 deletions pages/docs/balance/open-banking/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,13 +70,14 @@ We explore the specific flows for each provider below.
- **User Grants Permissions:** The user logs in to their bank account and grants your application permission to access specific financial data.
- **Error Handling:** Implement proper mechanisms to handle potential errors during the verification process.

#### 3. Data Retrieval and Exchange Creation:
#### 3. Handle MX Callback and List Available Connections:

- **Successful Authorization:** Upon successful user authorization, you'll receive user and account details from the Open Banking provider. Use this information to create an exchange with Dwolla's "create an exchange" endpoint.
- **Dwolla Retrieves Account Data:** Dwolla securely retrieves relevant account data from the user's bank through the established Open Banking provider connection.
- **MX Callback:** You'll [receive an event](https://docs.mx.com/connect/guides/handling-events/) from the MX Connect Widget indicating the completion of the IAV flow and providing details about the authorized account(s).
- **List Available Connections:** Use the [list available exchange connections endpoint](/docs/balance/api-reference/open-banking/list-available-exchange-connections) to retrieve a list of available exchange connections associated with the customer. These connections represent the external bank accounts that the user has authorized through MX Connect that can be used to create funding sources.

#### 4. Funding Source Creation and Account Verification:
#### 4. Exchange and Funding Source Creation:

- **Create Exchange:** Once the user selects an account, you will make a request to the [create an exchange](/docs/balance/api-reference/exchanges/create-exchange-for-a-customer) endpoint, providing the `availableConnectionToken` of the chosen available exchange connection. This creates an "exchange" representing the link between the Dwolla customer and their external bank account.
- **Create Funding Source:** Use the [create a funding source endpoint](/docs/balance/api-reference/funding-sources/create-funding-source-for-customer) with the exchange resource from the previous step.
- **Verification Complete:** Dwolla responds with a 201 code and triggers the `customer_funding_source_added` and `customer_funding_source_verified` webhooks indicating successful funding source creation and verification.

Expand Down
Loading