VANs - Send or Receive Transactions in Your Dwolla Balance With a Virtual Account Number

No, Dwolla isn’t venturing into the sneaker business, nor are we releasing a motor vehicle (at least, not yet). We’re talking about “Virtual Account Numbers,” which allow you to access your Dwolla Balance from outside the Dwolla Network.

“Wait, how do I do that?” you ask. First, create a VAN (virtual account number) for your Dwolla Balance. This VAN becomes a unique account and routing number, which you can then use for ACH transactions outside of Dwolla! It’s quite neat!

Use Cases and Applications

Our VANs feature is unique, enabling account-to-account transfers instead of the more common association with credit cards. We like thinking differently though!

Intrigued about the possibilities and benefits? Here’s an example use case where that shows one of the ways that VANs can help.

Direct Deposit

Let’s say you’re building a savings application that lets users set aside certain amounts of funds to save in their virtual wallet (aka the Dwolla Balance). Previously, users would have to attach and verify their bank accounts, then directly initiate a transfer through your app in order to transfer funds to the Dwolla Balance.

Using a VAN, the user now simply allocates a portion of their paycheck directly into the VAN through their employer’s direct deposit options!

Eligibility and Considerations

VANs can be utilized by any account that has access to a Dwolla Balance; this includes your main Dwolla Account, as well as Personal and Business Verified Customer accounts.

Some considerations include:

  • The same sending limit for transactions you have in your main Dwolla Account applies to transfers out of a VAN. There is no limit for receiving funds into a VAN.
  • A VAN funding-source counts towards the limit of funding-sources that an account can have.
  • Additional review and application information is required for approval to use the VANs feature.
  • If you are currently a Dwolla client, you will likely have to migrate your integration to the financial institution partner that supports VANs. Ask our Sales team or your Account Manager for more information on migrating your existing account over to start using VANs.

How to Use a Dwolla VAN

Enabling VANs in Your Production Account

The VANs service is a premium feature that requires further approvals from the Dwolla team to enable in production. To enable VANs and other premium features in production, please reach out to your Dwolla account manager or sales representative.

Once you are ready to start using VANs, check out our new documentation about VANs to learn how to utilize them.

Example Scenario

Let’s take the above example of creating a direct deposit into the VAN for a user. These are the specific steps you would take.

Creating a VAN for a Verified Customer

The first step involves creating a VAN as a Funding Source for your user. This creates a new resource that can be accessed via the API to view the Account and Routing Number information. However, this resource cannot be used as the source or destination when calling the Dwolla API to initiate a transfer.

POST https://api.dwolla.com/customers/{id}/funding-sources
{
  “name”: “My First VAN”,
  “type”: “virtual”,
  “bankAccountType”: “checking”,
}

Retrieving the Account and Routing Numbers

Then, to make the Account and Routing numbers available to your user, you will call the /ach-routing endpoint.

GET https://api.dwolla.com/funding-sources/{id}/ach-routing

{
  “_links”: {...},
  “_embedded”: {...},
  “accountNumber”: “12345”,
  “routingNumber”: “222222226”
}

Your user can now enter the Account and Routing numbers in their payroll profile to allocate a portion of a paycheck to the VAN.

Once the payroll is processed, and Dwolla is notified of the transaction by the ACH Network, the transfer resource will be made available via the API for you to view. The new transfer can be accessed via the /transfers/{id} endpoint. The response will have the source as the VAN funding source and the destination as the Dwolla Balance funding source. The achDetails object will hold additional details about the external transaction.

Retrieving a Virtual Account Transfer

For brevity, the response is shortened in the example below.

GET https://api.dwolla.com/transfers/a1c86862-4c80-ec11-813d-ca84ae5ee1fb

. . .

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/transfers/a1c86862-4c80-ec11-813d-ca84ae5ee1fb",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/858a6908-1162-4a2d-b2ac-d79d37246e35",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "destination": {
            "href": "https://api-sandbox.dwolla.com/accounts/0ee84069-47c5-455c-b425-633523291dc3",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "account"
        }
    },
    "id": "a1c86862-4c80-ec11-813d-ca84ae5ee1fb",
    "status": "pending",
    "amount": {
        "value": "10.00",
        "currency": "USD"
    },
    "created": "2022-01-28T15:10:10.850Z",
    "achDetails": {
        "source": {
            "addenda": {
                "values": [
                    "addenda"
                ]
            },
            "beneficiaryName": "Fake name",
            "companyName": "Fake company name",
            "companyEntryDescription": "",
            "effectiveDate": "2022-01-28",
            "postingData": "Fake company name:Fake discretionary data:Fake name",
            "routingNumber": "222222226",
            "traceId": "222222221335387"
        },
        "destination": {}
    }
}

Enabling and Testing in the Sandbox

To enable the VANs feature in your Dwolla Sandbox account for testing, please message us here on the discuss forum or support@dwolla.com.

Once VANs are enabled and created, use the /sandbox-simulations endpoint to simulate an external transaction. Find out more about testing VANs in our Sandbox guide.

Example Request

POST https://api-sandbox.dwolla.com/sandbox-simulations

{
  “type”: “virtual”,
  “transfers”: [
   {
      “_link”: {
        “[source/destination]”: {
          “href”: “{{VAN funding source URL}}”
        }
      },
      “amount”: {
        “currency”: “USD”,
        “value”: “{{amount}}”
      },
      “achDetails”: {						// optional
        “companyEntryDescription”: “{{value}}”,	// optional   
        “routingNumber”: “{{routingNumber}}”,	// optional
        “addenda”: “{{addenda}}”,                // optional
        “beneficiaryName”: “{{name}}”			// optional
        “companyDiscretionaryData”: “{{value}}”, // optional
        “companyId”: “{{companyId}}”             // optional
        “companyName”: “{{name}}”,               // optional
      }
   }
  ]
}

Webhook Notifications

The following webhooks are associated with VANs and external transactions involving VANs.

Event Description
funding_source_added A VAN funding-source was created for a Dwolla Account.
funding_source_verified A VAN funding-source was marked as verified.
funding_source_removed A VAN funding source was removed from a Dwolla Account.
customer_funding_source_added A VAN funding-source was created for a Verified Customer Account.
customer_funding_source_verified A Customer’s VAN funding-source was marked as verified.
customer_funding_source_removed A VAN funding source was removed from a Customer.
bank_transfer_created An external transfer was created.
bank_transfer_completed An external transfer has cleared successfully.
bank_transfer_failed An external transfer failed to clear successfully.
customer_bank_transfer_created An external transfer was created for a Customer.
customer_bank_transfer_completed An external transfer that was created for a Customer has cleared successfully.
customer_bank_transfer_failed An external transfer that was created for a Customer failed to clear successfully.

We hope you’re as excited about VANs as we are! Want to learn more? Check out our Developer Docs for more information on implementing this feature.

If you have some feedback or are interested in testing VANs in the Sandbox environment, let us know!