Transfer Lifecycle - Dwolla Developer Portal

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 or a Dwolla Wallet. 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, 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.

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, Mass Payments, and 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

createTransfer.js

create_transfer.php

create_transfer.rb

create_transfer.py

HTTP

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

// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);

$transfer = $transfersApi->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"

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

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

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

searchTransfer.js

search_transfer.php

search_transfer.rb

search_transfer.py

HTTP

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

// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$customerUrl = 'https://api.dwolla.com/customers/33e56307-6754-41cb-81e2-23a7f1072295';

$TransfersApi = new DwollaSwagger\TransfersApi($apiClient);

$transfers = $TransfersApi->getCustomerTransfers($customerUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "pending"

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

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

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`: 5dc959dd-29ec-436f-8cdc-dd7269fd4e7c
VCR-1 Balance → VCR-2 Balance	5dc959dd-29ec-436f-8cdc-dd7269fd4e7c	`funding-transfer`: a379c863-77f2-4248-8b37-486bc10b3817 `funded-transfer`: a91f21c1-d9bb-41a6-8aab-981e763bd325
VCR-2 Balance → VCR-2 Bank	a91f21c1-d9bb-41a6-8aab-981e763bd325	`funding-transfer`: 5dc959dd-29ec-436f-8cdc-dd7269fd4e7c `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.