-
Notifications
You must be signed in to change notification settings - Fork 8
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.
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
Dev 1620 - Add reauth exchange and bank balance check article #633
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
107 changes: 107 additions & 0 deletions
107
pages/docs/balance/api-reference/open-banking/create-reauth-exchange-session.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,107 @@ | ||
| --- | ||
| layout: guides | ||
| product: balance | ||
| title: "Create a re-auth exchange session" | ||
| guide: | ||
| step: 2 | ||
| meta: | ||
| title: "Dwolla API Reference | Open Banking: Create Re-auth Exchange Session" | ||
| description: "Create a re-auth exchange session." | ||
| --- | ||
|
|
||
| # Create a re-auth exchange session | ||
|
|
||
| This endpoint allows you to initiate a new exchange session to refresh a user's bank account connection when their existing authorization is no longer valid. This is typically required when Dwolla's API returns an `UpdateCredentials` error on a [bank balance check](https://developers.dwolla.com/docs/balance/api-reference/open-banking/retrieve-bank-balance), indicating that the user needs to re-authenticate with their bank. | ||
|
|
||
| ### HTTP request | ||
|
|
||
| > `POST https://api.dwolla.com/exchanges/{id}/exchange-sessions` | ||
|
|
||
| ### Request parameters | ||
|
|
||
| | Property | Required | Type | Description | | ||
| | -------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | \_links | yes | object | A HAL-JSON link that represents the redirect URL for a Visa exchange session. This redirect URL will be validated against a previously configured redirect URL stored in Dwolla. The validated redirect URL will be used to redirect the user back to your application after they complete the re-authorization process with Visa. | | ||
|
|
||
| ### 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/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. | | ||
| | 404 | NotFound | The requested resource was not found. | | ||
|
|
||
| ### Request and Response (Visa) | ||
|
|
||
| ```bash | ||
| POST https://api.dwolla.com/exchanges/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": { | ||
| "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 | ||
| ``` | ||
|
|
||
| ```php | ||
| /** | ||
| * No example for this language yet. | ||
| **/ | ||
| ``` | ||
|
|
||
| ```ruby | ||
| # Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby | ||
| exchange_url = 'https://api.dwolla.com/exchanges/74a207b2-b7b7-4efa-8bf8-582148e7b980' | ||
| request_body = { | ||
| _links: { | ||
| 'redirect-url': { | ||
| href: "https://www.yourdomain.com/iav-callback" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| reauthExchange = app_token.post "#{exchange_url}/exchange-sessions", request_body | ||
| reauthExchange.response_headers[:location] # => "https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d" | ||
| ``` | ||
|
|
||
| ```python | ||
| # Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python | ||
| exchange_url = 'https://api.dwolla.com/exchanges/74a207b2-b7b7-4efa-8bf8-582148e7b980' | ||
| request_body = { | ||
| '_links': { | ||
| 'redirect-url': { | ||
| 'href': 'https://www.yourdomain.com/iav-callback' | ||
| } | ||
| } | ||
| } | ||
|
|
||
| reauthExchange = app_token.post('%s/exchange-sessions' % exchange_url, request_body) | ||
| reauthExchange.headers['location'] # => 'https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d' | ||
| ``` | ||
|
|
||
| ```javascript | ||
| // Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node | ||
| var exchangeUrl = | ||
| "https://api.dwolla.com/exchanges/74a207b2-b7b7-4efa-8bf8-582148e7b980"; | ||
| var requestBody = { | ||
| _links: { | ||
| "redirect-url": { | ||
| href: "https://www.yourdomain.com/iav-callback", | ||
| }, | ||
| }, | ||
| }; | ||
|
|
||
| dwolla | ||
| .post(`${exchangeUrl}/exchange-sessions`, requestBody) | ||
| .then((res) => res.headers.get("location")); // => 'https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d' | ||
| ``` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| --- | ||
| layout: guides | ||
| title: "Bank Balance Check" | ||
| guide: | ||
| step: 2 | ||
| meta: | ||
| title: "Dwolla Balance: Open Banking - Bank Balance Check | Dwolla API Documentation" | ||
| description: "Explore Dwolla's Open Banking solution and the benefits of using Bank Balance Check for your ACH payments." | ||
| --- | ||
|
|
||
| # Bank Balance Check | ||
|
|
||
| Account-to-account (A2A) payments offer businesses an efficient and cost-effective means for handling account-to-account transfers. However, they are not without risks, the most notable being ACH returns due to insufficient funds. Such returns can cause significant delays, frustrations and even fees for both businesses and customers. | ||
|
|
||
| As part of Dwolla’s [Open Banking Services](https://developers.dwolla.com/docs/balance/open-banking), the real-time balance check add-on to our Instant Account Verification (IAV) feature (“Bank Balance Check”) enables businesses to see the current and available balance of a sender’s bank account before processing a transaction. By giving insights into bank account balances, real-time Bank Balance Checks help reduce the likelihood of ACH returns, helping businesses maintain smoother and more reliable payment flows. | ||
|
|
||
| ### **Overview of Benefits** | ||
|
|
||
| - **Reduced Risk of Insufficient Funds Returns:** Receiving information about the available and current balance in a bank account prior to initiating a transaction helps businesses avoid initiating payments that are likely to fail. | ||
| - **Improved Payment Success Rate:** With fewer returned transactions, businesses experience smoother operations and faster transaction processing times. | ||
| - **Enhanced User Experience:** Notifying users of insufficient funds before initiating the transaction gives them the opportunity to take corrective action (e.g., cancel or modify the payment, move money between accounts to cover the transaction, etc.). | ||
| - **Cost Savings:** Minimizing ACH returns reduces potential fees associated with failed transactions, saving businesses both time and money. | ||
|
|
||
| ### **How It Works** | ||
|
|
||
| 1. **Initiating a Bank Balance Check:** | ||
| - Before calling the API to create a transfer, you can initiate a Bank Balance Check to retrieve the sender’s current and available account balance in real time. | ||
| 2. **Evaluating the Response:** | ||
| - Even if the Bank Balance Check shows there are sufficient funds in a sender’s account, you should still use your own discretion when deciding whether to initiate a transaction. You may have your own criteria, such as requiring a buffer beyond the transaction amount. As an example as to why, the sender could make a withdrawal from his/her account from an ATM right after the Bank Balance Check shows sufficient funds in the sender’s account. While the Bank Balance Check offers valuable insight, it's important to consider your specific risk policies and other factors before proceeding with an ACH debit. | ||
| 3. **ACH Window Processing:** | ||
| - If the payment is queued, the Bank Balance Check can be triggered just before the ACH processing window closes so you receive the most up-to-date balance information available. | ||
|
|
||
| ### **Retrieving current and available balance** | ||
|
|
||
| Bank Balance Checks are most effective when performed as close as possible to the close of an ACH processing window, as this is the final moment to show the available and current balance in a user’s bank account before funds are debited or credited . By checking the balance at this time, businesses can provide users with actionable insights, such as the need to top up their account or adjust the transaction, avoiding potential delays or returns. | ||
|
|
||
| When checking a user's bank account balance, it's important to differentiate between the **closing** balance and the **available** balance. | ||
|
|
||
| `available` \- The amount of funds the customer is able to withdraw from the account, not including any credit facility that may be available. The balance includes pending inflows or outflows on the account. | ||
|
|
||
| `closing` \- This represents the current balance of the account, not accounting for pending debits and credits. | ||
|
|
||
| `lastUpdated` \- When calling the balance endpoint on a Customer’s funding source initially or on a refresh request, the response will include a lastUpdated parameter with a UTC timestamp value. This timestamp value refers to the last time the Customer’s bank account balance was retrieved from the open banking provider. | ||
|
|
||
| **Request and response** | ||
|
|
||
| ```bash | ||
| GET https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418/balance | ||
| Accept: application/vnd.dwolla.v1.hal+json | ||
| Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY | ||
|
|
||
| { | ||
| "_links": { | ||
| "self": { | ||
| "href": "https://api.dwolla.com/funding-sources/42f48a64-2a9b-40df-9777-603ed2fe2764/balance", | ||
| "type": "application/vnd.dwolla.v1.hal+json", | ||
| "resource-type": "balance" | ||
| }, | ||
| "funding-source": { | ||
| "href": "https://api.dwolla.com/funding-sources/42f48a64-2a9b-40df-9777-603ed2fe2764", | ||
| "type": "application/vnd.dwolla.v1.hal+json", | ||
| "resource-type": "funding-source" | ||
| } | ||
| }, | ||
| "available": { | ||
| "value": "542.00", | ||
| "currency": "USD" | ||
| }, | ||
| "closing": { | ||
| "value": "542.00", | ||
| "currency": "USD" | ||
| }, | ||
| "lastUpdated": "2024-09-09T16:39:14.219Z" | ||
| } | ||
| ``` | ||
|
|
||
| ```ruby | ||
| # Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby | ||
| funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418' | ||
|
|
||
| funding_source = app_token.get "#{funding_source_url}/balance" | ||
| ``` | ||
|
|
||
| ```php | ||
| <?php | ||
| // Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php | ||
| $fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418'; | ||
|
|
||
| $fsApi = new DwollaSwagger\FundingsourcesApi($apiClient); | ||
|
|
||
| $fundingSource = $fsApi->getBalance($fundingSourceUrl); | ||
| ?> | ||
| ``` | ||
|
|
||
| ```python | ||
| # Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python | ||
| funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418' | ||
|
|
||
| funding_source = app_token.get('%s/balance' % funding_source_url) | ||
| ``` | ||
|
|
||
| ```javascript | ||
| // Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node | ||
| var fundingSourceUrl = | ||
| "https://api-sandbox.dwolla.com/funding-sources/c2eb3f03-1b0e-4d18-a4a2-e552cc111418"; | ||
|
|
||
| dwolla | ||
| .get(`${fundingSourceUrl}/balance`) | ||
| .then((res) => res.body.available.value); | ||
| ``` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Everything looks good to me!
Just adding a note, we should likely add the
UpdateCredentialserror in the Balance check reference as well under the table "HTTP status and error codes".