## 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: 1. **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. 2. **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. 3. **Fetch Available Funding Sources** Retrieve the list of available funding sources for both your Customer and your Main Dwolla Account. 4. **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 Sandbox 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](https://developers.dwolla.com/docs/testing) 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. If you haven’t already, run through the [Quickstart](https://developers.dwolla.com/docs/quickstart) to get your first token, or see the [Authentication guide](https://developers.dwolla.com/docs/api-reference/api-fundamentals/making-requests-and-authentication) for OAuth details. 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](https://developers.dwolla.com/docs/working-with-webhooks). # 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](https://developers.dwolla.com/docs/customer-types). ### 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 | | email | 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 | ```ruby POST https://api-sandbox.dwolla.com/customers Content-Type: application/vnd.dwolla.v1.hal+json Accept: application/vnd.dwolla.v1.hal+json Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY { "firstName": "Jane", "lastName": "Doe", "email": "janeDoe@nomail.net", "ipAddress": "99.99.99.99", } ``` Providing the IP address of the end user accessing your application as the `ipAddress` parameter 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 webhooks 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](https://developers.dwolla.com/docs/open-banking) | Yes | Online banking credentials | | [Drop-in components](https://developers.dwolla.com/docs/drop-in-components) | Optional - With Microdeposits | Bank Account and Routing Number | | [Dwolla + Secure Exchange solution](https://developers.dwolla.com/docs/secure-exchange) | 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](https://developers.dwolla.com/docs/drop-in-components#create-a-funding-source). ### 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 Plaid, 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. ### Handle Webhooks If you have an active webhook subscription, you should receive both the `customer_funding_source_added` and `customer_funding_source_verified` webhooks 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) ### 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 ```http GET https://api-sandbox.dwolla.com/customers/2e09d295-e0b4-48e1-9ad0-69eafd47f212/funding-sources Accept: application/vnd.dwolla.v1.hal+json Authorization: Bearer [YOUR_OAUTH_TOKEN_HERE] { "_links": { "self": { "href": "https://api-sandbox.dwolla.com/customers/2e09d295-e0b4-48e1-9ad0-69eafd47f212/funding-sources?removed=false", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "customer": { "href": "https://api-sandbox.dwolla.com/customers/2e09d295-e0b4-48e1-9ad0-69eafd47f212", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "customer" } }, "_embedded": { "funding-sources": [ { "_links": { "transfer-from-balance": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "self": { "href": "https://api-sandbox.dwolla.com/funding-sources/c4805686-dee2-4f5a-ae8c-f269e29658b2", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "transfer-to-balance": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "transfer-send": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "remove": { "href": "https://api-sandbox.dwolla.com/funding-sources/c4805686-dee2-4f5a-ae8c-f269e29658b2", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "customer": { "href": "https://api-sandbox.dwolla.com/customers/2e09d295-e0b4-48e1-9ad0-69eafd47f212", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "customer" }, "transfer-receive": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" } }, "id": "c4805686-dee2-4f5a-ae8c-f269e29658b2", "status": "verified", "type": "bank", "bankAccountType": "checking", "name": "Plaid Test", "created": "2022-06-01T20:50:17.276Z", "removed": false, "channels": [ "ach", "real-time-payments" ], "bankName": "SANDBOX TEST BANK", "fingerprint": "dcd236c37358c1e4a306e6fb1b37dac85e0b2cc9925d4719f1e72d7731a80923" } ] } } ``` ### 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. ##### Request and response ```http GET https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254/funding-sources?removed=false Accept: application/vnd.dwolla.v1.hal+json Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q { "_links": { "self": { "href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254/funding-sources" } }, "_embedded": { "funding-sources": [ { "_links": { "transfer-from-balance": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "self": { "href": "https://api-sandbox.dwolla.com/funding-sources/b5e68264-7d4d-42a9-88d4-5616c77c6baa", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "remove": { "href": "https://api-sandbox.dwolla.com/funding-sources/b5e68264-7d4d-42a9-88d4-5616c77c6baa", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "transfer-send": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "transfer-receive": { "href": "https://api-sandbox.dwolla.com/transfers", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "account": { "href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "account" } }, "id": "b5e68264-7d4d-42a9-88d4-5616c77c6baa", "status": "verified", "type": "bank", "bankAccountType": "checking", "name": "ABC Bank Checking", "created": "2019-03-14T15:18:51.336Z", "removed": false, "channels": [ "ach" ], "bankName": "SANDBOX TEST BANK" } ] } } ``` ### 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. | | amount | yes | object | An amount JSON object. | 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.](https://developers.dwolla.com/docs/api-reference/transfers/initiate-a-transfer) ##### Request and response ```http POST https://api-sandbox.dwolla.com/transfers Accept: application/vnd.dwolla.v1.hal+json Content-Type: application/vnd.dwolla.v1.hal+json Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77 { "_links": { "source": { "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4" }, "destination": { "href": "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C" } }, "amount": { "currency": "USD", "value": "10.00" }, } ``` 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 webhooks that are triggered for the user in the Dwolla system. ### 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. ```json { "_links": { "source": { "href": "https://api-sandbox.dwolla.com/accounts/30a6cb55-1754-4948-b431-ebe48288ef25", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "account" }, "funding-transfer": { "href": "https://api-sandbox.dwolla.com/transfers/6fdd095c-afd7-e811-8111-bec1f96924ed", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "destination-funding-source": { "href": "https://api-sandbox.dwolla.com/funding-sources/AB443D36-3757-44C1-A1B4-29727FB3111C", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "self": { "href": "https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "transfer" }, "source-funding-source": { "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "funding-source" }, "destination": { "href": "https://api-sandbox.dwolla.com/customers/4e988dba-0a1e-4591-ad04-eab3613e2f83", "type": "application/vnd.dwolla.v1.hal+json", "resource-type": "customer" } }, "id": "74c9129b-d14a-e511-80da-0aa34a9b2388", "status": "processed", "amount": { "value": "10.00", "currency": "USD" } } ```