Receive Money from Users
Learn the key steps involved with receiving funds from your end user’s bank account.
Overview
This guide is designed to get you up and running quickly through creating a one-time transfer from an end user via the Dwolla API. In this guide, we’ll cover the basics of integrating this lightweight payment flow, receiving funds (also referred to as “pay-ins”), by breaking down the steps to create a bank transfer. For simplicity, we’ll represent a one-to-one transfer between two end users, where the source user is the individual or business that has been onboarded as a Dwolla Customer record. The destination user is identified as your Main Dwolla Account.
In this quickstart guide, you’ll learn the following key concepts involved with receiving funds from your end user’s bank account:
Choose and Create Customer Type
Select and create the appropriate Customer type for your sending Customer. Both unverified and verified Customer types are eligible to send funds.
Attach Funding Source
Add and verify a bank account (funding source) to the Customer. This is required for the Customer to be eligible to send funds.
Fetch Available Funding Sources
Retrieve the list of available funding sources for both your Customer and your Main Dwolla Account.
Initiate Transfer
Create a transfer from your Customer’s bank account to your Main Dwolla Account’s bank account.
Before you begin
We encourage you to create a account, if you haven’t already. This will allow you to follow along with the steps outlined in this guide. Check out our Sandbox guide to learn more on creating an account.
After creating a sandbox account, you’ll obtain your API Key and Secret, which are used to obtain an OAuth access token. An access token is required in order to authenticate against the Dwolla API. Learn more about how to obtain an access token in our guide.
Lastly, in this sandbox walkthrough, we recommend having an active webhook subscription. This will help notify your application of various events that occur within the Dwolla API. Check out our guide to learn more.
Let’s get started!
Step 1 - Creating your Customer
Choose the Customer Type for your Funds Flow
Before your end user can send funds, they must be created as a Customer via the Dwolla API. The pay-ins funds flow is flexible in terms of choosing a Customer type to onboard, as both the unverified Customer and verified Customer types are eligible to send funds. To learn more on the different Customer types and the capabilities of each, check out our customer types resource article.
Create the Customer
While you can use the verified Customer type in this funds flow, we will be creating an unverified Customer in this guide.
Request Parameters - Unverified Customer
| Parameter | Required? | Type | Description |
|---|---|---|---|
| firstName | yes | string | Customer’s first name |
| lastName | yes | string | Customer’s last name |
| yes | string | Customer’s email address | |
| businessName | conditional | string | Customer’s registered business name (optional if not a business entity) |
| ipAddress | no | string | Customer’s IP address |
Providing the IP address of the end user accessing your application as the
ipAddress parameter. This enhances fraud detection and tracking.
When the Customer is successfully created by your application, you will receive a 201 HTTP response with an empty response body. You can reference the Location header to retrieve a link that represents the created Customer resource. We recommend storing the full URL for future use, as it will be necessary to complete additional actions, such as attaching a bank or correlating that are triggered for the end user in the Dwolla system.
Handle Webhooks
If you have an active webhook subscription, you will receive the customer_created webhook immediately after the resource has been created.
Step 2 - Adding a Funding Source
Within Dwolla, the sending party must always have a verified funding source. Since your Customer is the one sending funds, they will need to both add and verify their bank funding source before being eligible to send funds.
The destination party, or the party receiving funds, does not need to have a verified funding source to receive these funds.
Bank Addition and Verification Methods
There are multiple ways of adding a bank to a Customer with the Dwolla API. A simplified table below outlines the similarities and differences of each method.
| Bank Addition Method | Will the bank be verified? | Required Information |
|---|---|---|
| API - Account & Routing Number | Optional - With Microdeposits | Bank Account and Routing Number |
| Dwolla + Open Banking | Yes | Online banking credentials |
| Drop-in components | Optional - With Microdeposits | Bank Account and Routing Number |
| Dwolla + Secure Exchange solution | Yes | Online banking credentials |
| Other Approved Third-party Provider | Yes | Variable |
For more information on securely submitting a user’s bank details directly to Dwolla from the client-side of your application, reference our Drop-in components .
Add a Bank to an Unverified Customer
In this step, we will create and attach a verified funding source to your Customer using Dwolla’s Open Banking solution with Visa, a leading Open Banking service provider that Dwolla partners with. This method will give your Customers the ability to add and verify their bank account in a matter of seconds by authenticating using their online banking credentials.
Once your Customer reaches the page in your application to add a bank account, you will use Open Banking with Visa to authenticate the user’s bank account. This involves initiating an with Dwolla, guiding the user through the verification process with their bank, and then using the details to create a funding source in Dwolla.
To integrate Open Banking with Visa, we recommend checking out our integration guide. Additionally, if you would like to see a working example that verifies a bank using Open Banking with Visa and attaches it as a verified funding source to a Dwolla Customer, please check out our open-banking/visa integration example on our GitHub profile.
Step-by-step guide on implementing Open Banking with Visa
Handle Webhooks
If you have an active webhook subscription, you should receive both the customer_funding_source_added and customer_funding_source_verified immediately following the request to Dwolla to add a funding source using Open Banking.
Step 3 - Retrieving Funding Sources
Now that you’ve created a Customer and associated its funding source, you are close to being able to initiate your first transfer. The transfer requires the following information:
- A funding source to pull the funds from (your Customer’s linked bank funding source)
- A funding source to push the funds to (your Main Dwolla Account’s linked bank funding source)
Dwolla uses URLs to represent relations between resources. Therefore, you’ll need to provide the full URL of the funding source and recipient.
Retrieve your Customer’s list of available Funding Sources
In order to find your Customer’s available bank and balance funding sources, you will need to first retrieve the funding sources from your Customer, via the API.
Request and response
Retrieve your Main Dwolla Account’s list of available Funding Sources
In order to find your Main Account’s available bank funding sources, you will need to first retrieve the funding sources from your Main Account, via the API. You’ll need your account URL which can be retrieved by calling the Root of the API.
Request and response
When the funding sources are successfully retrieved, you will receive a 200 HTTP response with the details of the funding sources. After retrieving the funding sources, we recommend storing the full URL for future use as it will be referenced when creating the transfer to this end user’s bank account.
Step 4 - Initiating a Transfer
Identify Source and Destination For Transfer
Since you are utilizing a receive funds flow, you will need to ensure that you know who the funds are going to.
- Source - Your Customer’s Bank Funding Source
- Destination - Your Main Dwolla Account Bank Funding Source
Initiate a Transfer
To initiate a transfer, we will need to specify the source and destination funding source URLs in the _links parameter.
Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| _links | yes | object | A _links JSON object describing the desired source and destination of a transfer. Reference the Source and Destination object to learn more about possible values for source and destination. |
| amount | yes | object | An amount JSON object. Reference the amount JSON object to learn more. |
Within a transfer request, Dwolla supports additional optional parameters.
These can range from clearing to specify the processing timing
for the transfer, or correlationId to help correlate transfers
from end-to-end. The object facilitator-fee isn’t supported for
this funds flow. For more information on all available transfer request
parameters, check out our API reference documentation.
Request and response
When the transfer is created, you will receive a 201 HTTP response with an empty response body. You can refer to the Location header to retrieve a link to the created Transfer resource. All bank transactions that are sourced from a bank or that are going to a bank will have an initial status of pending. We recommend storing the full Transfer URL for future use, as it will be needed for correlating transfer update that are triggered for the user in the Dwolla system.
Handle Webhooks
A single API call to create a payment transfer can trigger several transfer-related webhook events. The number of webhooks and type of webhook events can vary depending on the Customer type(s) involved in the transfer, as well as the source and destination for the funds transfer. For more information on which webhooks will be fired for a given section of a transfer, refer to our Developer Resource Article.
Simulate Payment Processing
To simulate payment ACH processing in the Dwolla environment, navigate to the Sandbox Dashboard. From here, you will want to click the “Process Bank Transfers” button on the top of the screen. Your Sandbox transfer will be moved out of a pending status and moved to a processed status.
Production payment processing timing
While ACH funds transfer processing can be simulated at any time in the sandbox, behavior will vary in production depending on what transfer clearing options you specify. Refer to our developer resource article to learn more on transfer timing in production.
Verify Status of Transfer
Since ACH transactions in production can take a few days to complete, webhooks are an efficient way to notify you of when a transfer is completed and processed to a destination funding source. However, if you want to verify the status of a transfer at any given point in time, you can make a call to the API to retrieve the transfer by its unique id.