;
};
## Overview
To initiate a transfer, you can either make an API request or use the Dwolla Dashboard. You will
need to specify the source and destination funding sources, which can be either a
[bank account](/docs/bank-funding-source) or a [Dwolla Wallet](/docs/balance-funding-source).
It's important to note that all account-to-account transfers are two-sided. When a transfer request
is received, it is broken down into "hops" or "legs," which describe each step of the process, such
as pulling funds into a Dwolla Wallet and pushing funds out of it.
## Transfer Statuses
As outlined in our [transfer resource](/docs/api-reference/transfers), transfers can have the
following statuses: `pending`, `processed`, `cancelled`, or `failed`.
* `pending` - A pending transfer hasn't been sent to the payment network or has been sent but not
processed. This means that it may still be cancellable or may result in a transfer failure.
* `processed` - The meaning of a "processed" status varies based on the transfer destination. If
it's going to a Dwolla Wallet, the funds have cleared successfully. If it's going to a linked bank
account, enough time has passed for the funds to clear into that account.
* `cancelled` - A transfer can be cancelled in two ways: either Dwolla cancels it systematically, or
your application sends an API request. If a funding source is removed during the transfer's
journey to that bank account, Dwolla will cancel the transfer.
* `failed` - A failed status is associated with an ACH network return, meaning that Dwolla received
an ACH return code from the RDFI (Receiving Depository Financial Institution). You can fetch the
failure reason via an additional API request.
[Learn more on transfer failures](/docs/transfer-failures).
## Flow of Funds
It's crucial to understand how funds flow into and out of the Dwolla Network because all transfers
require at least one user (either the sender or receiver) to hold a balance in a Dwolla Wallet. In
other words, **all transfers flow through a Dwolla Wallet, either explicitly or implicitly**.
* With an explicit flow of funds, the source of the transfer is a bank account (funding source) and
the destination is a Dwolla Wallet, or vice versa. In this scenario, the funds are explicitly
pushed into or pulled out of a Dwolla Wallet when the transfer is initiated.
* With an implicit flow of funds, the source and destination of the transfer are both bank accounts
(funding sources). In this scenario, the funds first enter the Dwolla Network by flowing through a
Dwolla Wallet of either the sender or receiver (or both, depending on the customer type), before
ultimately exiting to the destination bank account.
## Tracking Transfers
As mentioned previously, all account-to-account payments are two-sided. This can make it difficult
to track the status of a transfer at any given time. To address this, Dwolla supports two ways to
track transfers throughout their lifecycle:
* **Correlation ID**: This value is supplied by your application when the transfer is created, and
you can use it to track the transfer through the Dwolla API.
* **Response JSON `_links` property**: This property is automatically populated by Dwolla in the
response JSON for a transfer. It contains links to other resources that you can use to track the
transfer, such as the transfer's status and the transfer's history.
### Correlation ID
Many Dwolla resources allow a correlation ID—[Customers](/docs/api-reference/customers),
[Mass Payments](/docs/api-reference/mass-payments), and [Transfers](/docs/api-reference/transfers).
Through correlation IDs your application can send an ID of your choosing (generally a pseudo-random
alphanumeric string) that is attached to the resource once it’s created in the Dwolla system. In
particular, transfers are easily traceable in our API, as our transfers endpoint allows listing and
searching based on a `correlationId` value.
#### Create Transfer with Correlation ID
```javascript createTransfer.js theme={"dark"}
// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
const requestBody = {
_links: {
source: {
href: "https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4",
},
destination: {
href: "https://api.dwolla.com/funding-sources/ab443d36-3757-44c1-a1b4-29727fb3111c",
},
},
amount: {
currency: "USD",
value: "10.00",
},
correlationId: "8a2cdc8d-629d-4a24-98ac-40b735229fe2",
};
dwolla .post("transfers", requestBody) .then((res) => res.headers.get("Location")); // =>
'https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'
```
```php create_transfer.php theme={"dark"}
create([
'_links' => [
'source' => [
'href' => 'https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4',
],
'destination' => [
'href' => 'https://api.dwolla.com/funding-sources/ab443d36-3757-44c1-a1b4-29727fb3111c'
]
],
'amount' => [
'currency' => 'USD',
'value' => '10.00'
],
'correlationId' => '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
]);
$transfer; # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
```
```ruby create_transfer.rb theme={"dark"}
# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
:_links => {
:source => {
:href => "https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
:destination => {
:href => "https://api.dwolla.com/funding-sources/ab443d36-3757-44c1-a1b4-29727fb3111c"
}
},
:amount => {
:currency => "USD",
:value => "10.00"
},
:correlationId => "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
transfer = app_token.post "transfers", request_body
transfer.response_headers[:location] # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
```
```python create_transfer.py theme={"dark"}
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
'_links': {
'source': {
'href': 'https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
},
'destination': {
'href': 'https://api.dwolla.com/funding-sources/ab443d36-3757-44c1-a1b4-29727fb3111c'
}
},
'amount': {
'currency': 'USD',
'value': '10.00'
},
'correlationId': '8a2cdc8d-629d-4a24-98ac-40b735229fe2'
}
transfer = app_token.post('transfers', request_body)
transfer.headers['location'] # => 'https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'
```
```bash HTTP theme={"dark"}
POST https://api.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.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
"destination": {
"href": "https://api.dwolla.com/funding-sources/ab443d36-3757-44c1-a1b4-29727fb3111c"
}
},
"amount": {
"currency": "USD",
"value": "10.00"
},
"correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
...
HTTP/1.1 201 Created
Location: https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388
```
#### List (Search) Customer Transfers via Correlation ID
```javascript searchTransfer.js theme={"dark"}
// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
const customerUrl =
"https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295";
dwolla .get( `${customerUrl}/transfers?correlationId=8a2cdc8d-629d-4a24-98ac-40b735229fe2` )
.then((res) => res.body.\_embedded["transfers"][0].status); // => "pending"
```
```php search_transfer.php theme={"dark"}
getCustomerTransfers($customerUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "pending"
```
```ruby search_transfer.rb theme={"dark"}
# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295'
transfers = app_token.get "#{customer_url}/transfers?correlationId=8a2cdc8d-629d-4a24-98ac-40b735229fe2"
transfers._embedded['transfers'][0].status # => "pending"
```
```python search_transfer.py theme={"dark"}
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295'
transfers = app_token.get('%s/transfers?correlationId=%s' % customer_url % '8a2cdc8d-629d-4a24-98ac-40b735229fe2')
transfers.body['_embedded']['transfers'][0]['status'] # => 'pending'
```
```bash HTTP theme={"dark"}
GET https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers?correlationId=8a2cdc8d-629d-4a24-98ac-40b735229fe2
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...
{
"_links": {
"self": {
"href": "https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers"
},
"first": {
"href": "https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers?&limit=25&offset=0"
},
"last": {
"href": "https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295/transfers?&limit=25&offset=0"
}
},
"_embedded": {
"transfers": [
{
"_links": {
"self": {
"href": "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
},
"source": {
"href": "https://api.dwolla.com/customers/39e21228-5958-4c4f-96fe-48a4bf11332d"
},
"source-funding-source": {
"href": "https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
},
"destination": {
"href": "https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295"
},
"destination-funding-source": {
"href": "https://api.dwolla.com/funding-sources/ab443d36-3757-44c1-a1b4-29727fb3111c"
}
},
"id": "74c9129b-d14a-e511-80da-0aa34a9b2388",
"status": "pending",
"amount": {
"value": "10.00",
"currency": "USD"
},
"created": "2018-11-29 21:00:59 UTC",
"correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
]
},
"total": 1
}
```
### Response JSON Links
In addition to using a correlation ID, Dwolla automatically appends two resource `_links` properties
in all transfers: funding-transfer and funded-transfer, both of which can be used to traverse
programmatically a single transfer chain.
* `funding-transfer`: A resource link that points to the previous transfer in the overall chain (if
applicable). It identifies the previous transfer that, once processed, funded the current
transfer.
* `funded-transfer`: A resource link that points to the next transfer in the overall chain (if
applicable). It identifies the next transfer that the current transfer will fund, once processed.
**Example**
Consider a successful account-to-account transfer where a Verified Customer (VCR-1) sends money from
their bank account to the bank account of another Verified Customer (VCR-2). The “legs” of the
overall transfer lifecycle would look like this: Verified Customer (VCR-1) Bank to Verified Customer
(VCR-2) Bank
| Name | Transfer ID | Resource Links |
| ----------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| VCR-1 Bank → VCR-1 Balance | a379c863-77f2-4248-8b37-486bc10b3817 | `funding-transfer`: N/A
`funded-transfer`: N/A |
* The `funding-transfer` link for the first transfer is N/A because there is no previous transfer in
the chain.
* The `funded-transfer` link for the first transfer points to the second transfer, since the funds
from the first transfer funded the second transfer.
* The `funding-transfer` link for the second transfer points to the first transfer, which is the
transfer that funded it.
* The `funded-transfer` link for the third transfer is N/A because there are no further transfers in
the chain.
## Interactive Transfer Lifecycle