> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Balance Funding Source
> Send to, receive from, or hold funds within the Dwolla network for client master accounts and Verified Customer accounts.
## Overview
There are two types of [Funding Sources](/docs/api-reference/funding-sources) available within the Dwolla Platform: a bank account and a user’s Dwolla Balance. A bank account is commonly used as the source or destination for ACH transfers. The Dwolla `balance` is a Funding Source that can be utilized like a “wallet” for holding a stored value of USD funds. The Dwolla Balance is made available for account types that have completed [“KYC” requirements](https://www.dwolla.com/updates/guide-customer-identification-program-payments-api/), which includes clients of Dwolla and their end users that have been on-boarded as [Verified Customers](/docs/customer-types#verified-customer). All funds held in a Dwolla Balance are held by Dwolla’s [financial institution partner(s)](https://www.dwolla.com/legal/about-our-financial-institution-partner/) and not by Dwolla.
What makes the Dwolla Balance useful in relation to the platform is that the funds are immediately available within the Dwolla network. This means the Dwolla Balance acts as a funding source associated directly with each Verified Customer within your application. Your Customer can only access their Dwolla Balance through your application. You must provide an easily accessible and accurate summary of the [total and available balance](#total-and-available-balance) as well as transaction history for the Customer’s Dwolla Balance.
## Functionality and benefits
The Dwolla Balance allows for greater flexibility for your desired funds flow and delivers another efficient method to move funds.
#### Transfers
As a Funding Source, you and your end users can use the Dwolla Balance to:
* Receive funds from a bank account into the Dwolla Balance
* Send funds from the Dwolla Balance to a bank account
* Make instant payment transfers between two Dwolla Balances
* Keep funds accessible in a Dwolla Balance
To learn more about how to initiate transfers with the Dwolla API, check out our [API Reference Docs](/docs/api-reference/transfers)
#### Balance transfer timing
In production, transfer timing will vary depending on whether the Dwolla Balance is specified as the `source` or `destination` of the bank transfer. If transferring between two Dwolla Balances, the funds will transfer instantly.
| Bank to Balance | Balance to Bank | Balance to Balance |
| ----------------- | ----------------- | ------------------ |
| 3-4 Business Days | 1-2 Business Days | Instant |
## Viewing and displaying the balance
The Dwolla Balance is a Funding Source that can be accessed when an account, your [Main Dwolla Account](/docs/api-reference/accounts) or a [Verified Customer account](/docs/customer-types#verified-customer), has successfully completed the identity verification process and has a status of `verified`. Because this funding source exists within the Dwolla Network, you can obtain the details by utilizing the Dwolla API to retrieve the account’s list of funding sources.
#### Retrieve Dwolla Main Account Balance Funding Source
To retrieve your Account ID, you will need to call the [root](/docs/api-reference/root) of the API. Check out our API Reference Docs to learn more about retrieving the Balance funding source for [your Dwolla Main Account](/docs/api-reference/accounts/list-funding-sources-for-an-account).
##### Example request and response (Main Dwolla Account)
```bash HTTP theme={"dark"}
GET https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources",
"resource-type": "funding-source"
}
},
"_embedded": {
"funding-sources": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
}
},
"id": "04173e17-6398-4d36-a167-9d98c4b1f1c3",
"status": "verified",
"type": "bank",
"bankAccountType": "checking",
"name": "My Account - Checking",
"created": "2017-09-25T20:03:41.000Z",
"removed": false,
"channels": [
"ach"
],
"bankName": "First Midwestern Bank"
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
},
"account": {
"href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
},
"with-available-balance": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
},
"balance": {
"href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7/balance",
}
},
"id": "b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
"status": "verified",
"type": "balance",
"name": "Balance",
"created": "2017-08-22T18:21:51.000Z",
"removed": false,
"channels": []
}
]
}
}
```
```ruby list_account_funding_sources.rb theme={"dark"}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
funding_sources = app_token.get "#{account_url}/funding-sources"
funding_sources._embedded['funding-sources'][1].name # => "Balance"
```
```javascript listAccountFundingSources.js theme={"dark"}
var accountUrl =
"https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b";
dwolla
.get(`${accountUrl}/funding-sources`)
.then((res) => res.body._embedded["funding-sources"][1].name); // => 'Balance'
```
```python list_account_funding_sources.py theme={"dark"}
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'
funding_sources = app_token.get('%s/funding-sources' % account_url)
funding_sources.body['_embedded']['funding-sources'][1]['name'] # => 'Balance'
```
```php list_account_funding_sources.php theme={"dark"}
getAccountFundingSources($accountUrl);
$fundingSources->_embedded->{'funding-sources'}[1]->name; # => "Balance"
?>
```
#### Retrieve a Customer’s Dwolla Balance Funding Source
Check out our API Reference Docs to learn more about retrieving the Dwolla Balance funding source for [your Verified Customers](/docs/api-reference/funding-sources/list-customer-funding-sources).
##### Example request and response (Customer)
```bash HTTP theme={"dark"}
GET https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733/funding-sources"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
}
},
"_embedded": {
"funding-sources": [
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
},
"with-available-balance": {
"href": "https://api-sandbox.dwolla.com/funding-sources/ab9cd5de-9435-47af-96fb-8d2fa5db51e8"
}
},
"id": "ab9cd5de-9435-47af-96fb-8d2fa5db51e8",
"status": "verified",
"type": "balance",
"name": "Balance",
"created": "2015-10-02T21:00:28.153Z",
"removed": false,
"channels": []
},
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/98c209d3-02d6-4bee-bc0f-61e18acf0e33"
},
"customer": {
"href": "https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733"
}
},
"id": "98c209d3-02d6-4bee-bc0f-61e18acf0e33",
"status": "verified",
"type": "bank",
"bankAccountType": "checking",
"name": "Jane Doe’s Checking",
"created": "2015-10-02T22:03:45.537Z",
"removed": false,
"channels": [
"ach"
],
"fingerprint": "4cf31392f678cb26c62b75096e1a09d4465a801798b3d5c3729de44a4f54c794"
}
]
}
}
```
```ruby list_customer_funding_sources.rb theme={"dark"}
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'
funding_sources = app_token.get "#{customer_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Balance"
```
```javascript listCustomerFundingSources.js theme={"dark"}
var customerUrl =
"https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733";
dwolla
.get(`${customerUrl}/funding-sources`)
.then((res) => res.body._embedded["funding-sources"][0].name); // => 'Balance'
```
```python list_customer_funding_sources.py theme={"dark"}
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733'
funding_sources = app_token.get('%s/funding-sources' % customer_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Balance'
```
```php list_customer_funding_sources.php theme={"dark"}
getCustomerFundingSources($customerUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Balance"
?>
```
## Create Transfers using the Dwolla Balance
In order to create a transfer using the Dwolla Balance, you will first need the Dwolla Balance funding-source ID. Check out the above section on [Viewing and Displaying the Balance](#viewing-and-displaying-the-balance) in order to learn how to retrieve this ID. Once you have the Balance ID, it can be used as the `source` or the `destination` in a [transfer](/docs/api-reference/transfers) request depending on if you want to send funds out of the Dwolla Balance or into the Dwolla Balance, respectively.
### Add funds into the Dwolla Balance
There are several reasons you may want to pre-load a Dwolla Balance. Commonly, a pre-loaded Dwolla Balance is used to speed up payouts to Customers. According to the [transfer processing timing](/docs/transfer-processing-times#standard-ach-transfers) at Dwolla, standard transfers from a bank account into the Dwolla network takes 3-4 business days to settle, and transfers out of the Dwolla Network to a bank account take 1-2 business days to settle. If your use case involves creating payouts to your Customers and you do not want them to wait for 4-6 business days from the time of transfer creation to receive the funds, you can add funds into your Dwolla Balance in advance so that payouts to Customers will only take 1-2 business days from the time of transfer creation.
When [creating a transfer](/docs/api-reference/transfers/initiate-a-transfer) to add funds into a Dwolla Balance, you will have to make sure to use the Balance funding-source ID in the `destination` URL. The `source` can be a bank account funding-source or even another Balance funding-source from which you want to debit the funds.
### Transfer funds out of the Dwolla Balance
You can also create transfers from a Dwolla Balance out to another Dwolla Balance or an attached bank account funding-source. In the example above, this may be part of your application design to push funds out to Customers from your Dwolla Balance. It’s also possible that funds will unintentionally accumulate in your or a Verified Customer’s Balance if funds transferred through the Dwolla Network do not succeed in reaching the final destination source due to technical errors in your application or ACH Returns or Reversals (see the [transfer failure example](#transfer-failures) below for more details). You or your Customer may want to withdraw those accumulated funds into a bank account or send them to another Dwolla Balance.
When [creating a transfer](/docs/api-reference/transfers/initiate-a-transfer) to send funds out from a Dwolla Balance, you will have to make sure to use the Balance funding-source ID in the `source` URL. The `destination` can be a bank account funding-source or even another Dwolla Balance funding-source to which you want to sends funds.
## Retrieve the balance Amount
You can check the amount in a Dwolla Balance at any given time. You’ll want to be sure you and your end users know the amount available in your respective Dwolla Balances prior to sending funds. You must also be able to show the available balance at all times within your application to your Verified Customers. Check out our [API Reference Docs](/docs/api-reference/funding-sources/retrieve-funding-source-balance) to learn more.
#### Total and Available Balance
There are two different amounts returned in the API response when [retrieving a balance](/docs/api-reference/funding-sources/retrieve-funding-source-balance) which correspond to a `total` and `available` balance. **Note:** Unless your application utilizes [Labels](/docs/api-reference/labels) functionality, the amounts that are returned in both the balance and total object 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`.
##### Available Balance
Available Balance means the amount readily available in a Verified Customer’s Dwolla Balance that can be sent, withdrawn, or labeled. The “Available Balance” does not include labeled funds. The amount of funds for the following actions are limited to the amount of the Available Balance:
* Creating and adding funds to a new Label
* Increasing an existing Label
* Withdrawing funds
* Available Balance transfers, i.e. send or withdraw
If a Return occurs on a Verified Customer’s transfer sourced from a Dwolla
Balance, that Return will only impact the Available Balance, but not the
labeled funds. This could result in a negative Available Balance. If a Dwolla
Balance has a negative Available Balance, funds cannot be transferred out of
the Dwolla Balance, even if the Total Balance is positive. To resume use of
the Dwolla Balance, funds from labels will need to be “un-labeled” by creating
a label ledger entry or additional funds will need to be added to the Available Balance.
##### Total Balance
Represents the Verified Customer Record’s total balance held in the Dwolla network. This includes both labeled funds and the Available Balance, i.e. both labeled and unlabeled funds.
##### Example request and response
```bash HTTP theme={"dark"}
GET https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61/balance
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61/balance",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "balance"
},
"funding-source": {
"href": "https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
}
},
"balance": {
"value": "142.50",
"currency": "USD"
},
"total": {
"value": "142.50",
"currency": "USD"
},
"lastUpdated": "2019-06-03T14:28:12.679Z"
}
```
```ruby retrieve_balance.rb theme={"dark"}
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61'
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
funding_source = app_token.get "#{funding_source_url}/balance"
```
```javascript retrieveBalance.js theme={"dark"}
var fundingSourceUrl =
"https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61";
dwolla
.get(`${fundingSourceUrl}/balance`)
.then((res) => res.body.balance.amount);
```
```python retrieve_balance.py theme={"dark"}
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
funding_source_url = 'https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61'
funding_source = app_token.get('%s/balance' % funding_source_url)
```
```php retrieve_balance.php theme={"dark"}
getBalance($fundingSourceUrl);
?>
```
## Transfer failures
The amount in a Dwolla Balance can be adjusted when a bank transfer failure occurs. In a transaction, if funds fail to process to a destination bank, they will be sent back to either the sender’s or the receiver’s Dwolla Balance, depending on which of the parties is a Verified Customer with a Dwolla Balance funding source.
Funds can also be pulled from a Balance funding source in a transfer failure. In the case of transfer failure, funds may be pulled out of a Dwolla Balance to fund the transfer. In this case, responsibility falls on you to bring the Dwolla Balance back to zero.
#### Transfer failure example
Let’s illustrate a transfer failure with an example: Say you, Dwolla’s Client, are using Dwolla to send payments to your vendors, who are established as Receive-only Users. You send a payment from your bank account to the vendor’s bank account.
* Source - Dwolla Master Account’s Bank Funding Source
* Destination - Receive-only User’s Bank Funding Source
In this example, our Receive-only User closes down their bank account while the transaction has a `pending` status. The funds cannot settle in a closed bank account, and the receiving bank will send an ACH return. This will send these funds back to your Dwolla Master Account Balance funding source, not all the way back to your bank account. You can decide whether to build your application to prompt your Receive-only User to add another bank account, or if you want to withdraw that failed transfer amount to your bank account and attempt another method to make the payment.
For more information on possible transfer failure scenarios and the ACH Return Codes associated with each, check out our [Transfer Failures](/docs/transfer-failures) developer resource article.