Language

The Dwolla Balance

Overview

There are two types of Funding Sources available within the Dwolla Platform which include a bank or a 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 balance is made available for account types that have completed “KYC” requirements, which includes customers of Dwolla and their end users that have been on-boarded as Verified Customers.

What makes the Dwolla balance useful in relation to the platform is that the funds are held within the Dwolla network. This means the Dwolla balance acts as a funding source associated directly with each Verified Customer within your application. This funding source can only be accessed from your application by the end user, and you must provide an easily accessible and accurate summary of the total and available balance as well as transfer 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 can use the Dwolla balance to:

  • Receive funds from a bank funding source into the Dwolla Balance
  • Send funds from the Dwolla Balance to a bank funding source
  • Make instant payment transfers between two Dwolla Balance funding sources
  • Hold funds in a Dwolla Balance

To learn more about how to initiate transfers with the Dwolla API, check out our API Reference Docs

Balance Transfer Timing

In production, transfer timing will vary depending on whether the balance is specified as the source or destination of the bank transfer. If transferring between two balance funding sources, the funds will transfer instantly.

Bank to BalanceBalance to BankBalance to Balance
3-4 Business Days1-2 Business DaysInstant

Viewing and Displaying the Balance

The balance Funding Source can be accessed when an account (your Master Dwolla Account or a Verified Customer account) has successfully completed the identity verification process and has a status of verified. Since 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 Master Account Balance Funding Source

To retrieve your Account ID, you will need to call the root of the API. Check out our API Reference Docs to learn more about retrieving the balance funding source for your Dwolla Master Account.

Example request and response
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": []
            }
        ]
    }
}
# 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"
var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${accountUrl}/funding-sources`)
  .then(res => res.body._embedded['funding-sources'][1].name); // => 'Balance'
# 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
$accountUrl = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSources = $fsApi->getAccountFundingSources($accountUrl);
$fundingSources->_embedded->{'funding-sources'}[1]->name; # => "Balance"
?>

Retrieve a Customer’s Balance Funding Source

Check out our API Reference Docs to learn more about retrieving the balance funding source for your Verified Customers.

Example request and response
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"
      }
    ]
  }
}
# 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"
var customerUrl = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';

appToken
  .get(`${customerUrl}/funding-sources`)
  .then(res => res.body._embedded['funding-sources'][0].name); // => 'Balance'
# 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
$customerUrl = 'https://api-sandbox.dwolla.com/customers/5b29279d-6359-4c87-a318-e09095532733';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSources = $fsApi->getCustomerFundingSources($customerUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Balance"
?>

Retrieve the Balance Amount

The Dwolla balance also entails a feature in which you can check the value of the balance at any given time. Being able to know the amount of funds in your balance is necessary information to have 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 to learn more.

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 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

The amount of funds readily available in a Verified Customer Record’s 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

Note: If a return occurs on a Verified Customer Record that return will only impact the Available Balance, but not labeled funds. This could result in a negative Available Balance and the inability to complete the items listed above.

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
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"
}
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"
var fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61';

appToken
  .get(`${fundingSourceUrl}/balance`)
  .then(res => res.body.balance.amount);
# 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
$fundingSourceUrl = 'https://api-sandbox.dwolla.com/funding-sources/e5b8223f-08f7-4a7e-b952-88a773c0df61';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fsApi->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 a Dwolla Balance.

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 transfer balance back to zero.

Transfer failure example

Let’s illustrate a transfer failure with an example:

  • 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. Rather than the funds clearing to their now-closed bank account, an ACH return will be triggered which pushes these funds back to the Dwolla Master Account balance funding source. It is then up to you on whether your application will prompt your user to add another bank or to make payment to the Receive-Only User outside of Dwolla.

For more information on possible transfer failure scenarios and the Return Codes associated with each, check out our Transfer Failures developer resources article.


Status
Production: Operational

Financial institutions play an important role in the Dwolla network.

Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.