diff --git a/pages/changelog.mdx b/pages/changelog.mdx index a815a37b..9ef7acbb 100644 --- a/pages/changelog.mdx +++ b/pages/changelog.mdx @@ -14,6 +14,18 @@ Keep up to date on new product features and enhancements, API docs, tools change ## Completed +### 2024-09-16 + +**ADDED** + +- Added support for retrieving real-time bank balance information using Dwolla's Open Banking solution. Businesses can now verify the current balance of a user's bank account before initiating ACH payments. This feature helps mitigate the risk of insufficient funds and improves payment processing efficiency. + +##### Updated API Endpoint: + +To facilitate retrieving the bank balance, we've updated an API endpoint to support a new schema for bank balances: + +- **/funding-sources/id/balance (GET):** This API endpoint will return a JSON response containing the balance amount, currency, available balance, closing balance, and last updated timestamp. Refer to the developer documentation for detailed usage instructions and [API reference](https://developers.dwolla.com/docs/balance/api-reference/open-banking/retrieve-bank-balance). + ### 2024-06-10 **ADDED** diff --git a/pages/docs/balance/api-reference/funding-sources/retrieve-funding-source-balance.mdx b/pages/docs/balance/api-reference/funding-sources/retrieve-funding-source-balance.mdx index 2c091aac..ef83cab0 100644 --- a/pages/docs/balance/api-reference/funding-sources/retrieve-funding-source-balance.mdx +++ b/pages/docs/balance/api-reference/funding-sources/retrieve-funding-source-balance.mdx @@ -1,17 +1,19 @@ --- layout: guides product: balance -title: "Retrieve a funding source balance" +title: "Retrieve a Dwolla wallet balance" guide: step: 8 meta: - title: "Retrieve a Funding Source Balance | Dwolla API Documentation" + title: "Retrieve a Dwolla Wallet Balance | Dwolla API Documentation" --- -# Retrieve a funding source balance +# Retrieve a Dwolla wallet balance This section covers how to retrieve the total and available amount for a [Dwolla balance](https://developers.dwolla.com/concepts/balance-funding-source) funding source. The funding source type `balance` exists for [Verified Customer](https://developers.dwolla.com/concepts/customer-types#verified-customer) accounts and represents a balance held in the Dwolla network. +A Dwolla Wallet Balance, also referred to as [Dwolla Balance](https://developers.dwolla.com/concepts/balance-funding-source), is a funding source within the Dwolla platform that can be utilized like a "wallet" for holding a stored value of USD funds. It is made available for account types that have completed "KYC" requirements, which includes clients of Dwolla and their end users that have been on-boarded as Verified Customers. All funds held in a Dwolla Balance are held by Dwolla’s financial institution partner(s) and not by Dwolla. + #### Total and Available Balance There are two different amounts returned in the API response when retrieving a balance which correspond to a `total` and `available` balance. **Note:** Unless your application utilizes [Labels](https://developers.dwolla.com/api-reference/labels) functionality, the amounts that are returned in both the `balance` and `total` objects will be the same. Available balance can be accessed via the `balance` attribute, whereas total balance can be accessed via the `total` attribute within the Balance object. Both `balance` and `total` are JSON objects that contain key value pairs for `value` and `currency`. diff --git a/pages/docs/balance/api-reference/open-banking/retrieve-bank-balance.mdx b/pages/docs/balance/api-reference/open-banking/retrieve-bank-balance.mdx new file mode 100644 index 00000000..f16d0799 --- /dev/null +++ b/pages/docs/balance/api-reference/open-banking/retrieve-bank-balance.mdx @@ -0,0 +1,114 @@ +--- +layout: guides +product: balance +title: "Retrieve bank balance" +guide: + step: 3 +meta: + title: "Dwolla API Reference | Open Banking: Retrieve bank balance" + description: "Retrieve bank balances with Dwolla's Open Banking solution" +--- + +# Retrieve bank balance + +This section covers how to retrieve the current and available amount for a bank account added using Dwolla's [Open Banking solution](https://developers.dwolla.com/docs/balance/open-banking). This feature is designed to help businesses make more informed decisions before initiating ACH transactions, reducing the risk of failed payments due to insufficient funds. + +#### Available and Closing Balance + +There are two different amounts returned in the API response when retrieving a balance which correspond to a `available` and `closing` balance. Both balances provide important insights for businesses, with the `available` balance being the most relevant for determining whether there are sufficient funds to initiate an ACH transaction. + +##### Available balance + +Available balance is 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 and is the closest to real-time balance. The account's available balance is immediately updated all day long to reflect all the charges/transactions/deposits as they happen. **Note:** The available balance won't always be returned. + +##### Closing balance + +The closing (or booked) balance represents the current balance of the account without factoring in any pending debits or credits. It reflects the settled balance as of the end of the previous business day, providing a snapshot of the funds that have been fully processed. + +#### Last Updated + +When calling the balance endpoint on a funding source, either initially or during a refresh, the response will include a `lastUpdated` parameter with a UTC timestamp. This timestamp indicates the most recent time Dwolla retrieved the balance from the open banking provider. The balance is cached by default and automatically refreshed in the background when the balance status changes, ensuring up-to-date information is available without requiring frequent manual checks. + +### HTTP request + +> `GET https://api.dwolla.com/funding-sources/{id}/balance` + +### Request parameters + +| Parameter | Required | Type | Description | +| --------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | yes | string | A unique identifier representing the funding source for which the balance is being retrieved. This funding source must correspond to an existing and valid funding source that is linked using Dwolla's Open Banking Instant Account Verification solution. | + +### HTTP status and error codes + +| HTTP Status | Code | Message | Description | +| ----------- | -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 404 | NotFound | The requested resource was not found. | The requested bank account could not be found. This may occur if the funding source ID is invalid or if it does not exist in our system. Please verify that the correct funding source ID is being used and try again. | +| 400 | UnsupportedOperation | Retrieving the balance is not supported for this type of funding source. | This funding source may not allow balance checks, or it may not be eligible for this operation. | +| 400 | UnsupportedOperation | Balance Check is not supported by your exchange partner. | This may occur if your financial institution or Open Banking service provider does not offer balance verification. | +| 403 | Forbidden | Balance Check not enabled for this account. | Your account does not have the necessary permissions or features activated to perform balance checks. | + +### 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 +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.balance.value); +```