The Dwolla Balance #

Overview #

There are two types of 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, 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.

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

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.

Viewing and displaying the balance #

The Dwolla Balance is a Funding Source that 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. 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 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 (Master Dwolla Account)

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": []
            }
        ]
    }
}

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.

Example request and response (Customer)

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"
      }
    ]
  }
}

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

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

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

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 developer resource article.