Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Example of a bank to bank transfer between a Partner Dwolla Account and an Unverified Customer as well as related events

Overview

Use this doc as a reference to map out the sequence of events your app will receive based on the account type(s) involved in the transaction as well as where the funds are coming from and going to (bank or balance). The following transfer scenarios are covered in this doc:

Transfer scenario 1 - Source: Partner Account bank Destination: Unverified Customer bank.
Transfer scenario 2 - Source: Unverified Customer bank Destination: Partner Account bank.

Both success and failure cases will be shown as well as additional information on what occurs in the event of a bank transfer failure.

General recommendations: Webhook endpoints may occasionally receive the same event more than once. We advise you to build in logic to protect against duplicated events by making your event processing idempotent. Additionally, keep in mind that Dwolla cannot guarantee the order of fired webhooks.

Transfer scenario 1

Partner Account's bank to Unverified Customer B's bank

Example HTTP request and response:
POST https://api-sandbox.dwolla.com/transfers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer {accessToken}
{
    "_links": {
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/c91d6516-1855-4d36-be7c-bc78cc7c52c3"
        },
        "destination": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/e3103a12-63b5-4d5e-a0be-20ae2ee22264"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "100.00"
    }
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/53fbb333-573a-e711-80f1-0aa34a9b2388

Success

Transfer initiated

Customer Event Topic Name Transfer Id
Source bank_transfer_created Partner Account 52fbb333-573a-e711-80f1-0aa34a9b2388
Source transfer_created Partner Account 53fbb333-573a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 53fbb333-573a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source bank_transfer_completed Partner Account 52fbb333-573a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_completed Partner Account 53fbb333-573a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B 53fbb333-573a-e711-80f1-0aa34a9b2388

Fail - ACH return on source bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source bank_transfer_created Partner Account 9f819988-a43a-e711-80f1-0aa34a9b2388
Source transfer_created Partner Account a2819988-a43a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B a2819988-a43a-e711-80f1-0aa34a9b2388

Transfer fails to Dwolla network

Customer Event Topic Name Transfer Id
Source bank_transfer_failed Partner Account 9f819988-a43a-e711-80f1-0aa34a9b2388
Source transfer_failed Partner Account a2819988-a43a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer B a2819988-a43a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? A common ACH return from a source bank account is an R01(Insufficient funds). If an R01 is returned the bank account stays connected, however other R codes may trigger other Account or Funding Source events. Reference the list of possible events in our API docs.

Fail - ACH return on destination bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source bank_transfer_created Partner Account 2bd94605-a73a-e711-80f1-0aa34a9b2388
Source transfer_created Partner Account 01ea700b-a73a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 01ea700b-a73a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source bank_transfer_completed Partner Account 2bd94605-a73a-e711-80f1-0aa34a9b2388

Transfer fails to destination bank

Customer Event Topic Name Transfer Id
Source transfer_failed Partner Account 01ea700b-a73a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer B 01ea700b-a73a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? A bank transfer that fails as the result of an ACH return may trigger various events in Dwolla. Reference the list of possible events in our API docs. The pending transfer will be updated to failed and cause a balance adjustment that results in an increase in the source Accounts's balance.

Recommendation:

  • Refund the transfer back to the source bank account.
  • Re-attempt the transfer from the source Account's balance once the destination Customer has corrected the issue with their bank.

Fail "post-settlement"- ACH return on source bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source bank_transfer_created Partner Account 53ac3cf7-f83a-e711-80f1-0aa34a9b2388
Source transfer_created Partner Account 54ac3cf7-f83a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 54ac3cf7-f83a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source bank_transfer_completed Partner Account 53ac3cf7-f83a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_completed Partner Account 54ac3cf7-f83a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B 54ac3cf7-f83a-e711-80f1-0aa34a9b2388

Transfer fails "post-settlement" on source Account's bank

Customer Event Topic Name Transfer Id
Source bank_transfer_failed Partner Account 53ac3cf7-f83a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? A common ACH return from a source bank account is an R01(Insufficient funds). If an R01 is returned the bank account stays connected, however other R codes may trigger other Account or Funding Source events. Reference the list of possible events in our API docs.

Fail "post-settlement"- ACH return on destination bank account

Transfer initiated

Customer Event Topic Name Transfer Id
Source bank_transfer_created Partner Account 36a8e567-fa3a-e711-80f1-0aa34a9b2388
Source transfer_created Partner Account 37a8e567-fa3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 37a8e567-fa3a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network and Customer B

Customer Event Topic Name Transfer Id
Source bank_transfer_completed Partner Account 36a8e567-fa3a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_completed Partner Account 37a8e567-fa3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B 37a8e567-fa3a-e711-80f1-0aa34a9b2388

Transfer fails "post-settlement" on destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_failed Partner Account 37a8e567-fa3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer B 37a8e567-fa3a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? A bank transfer that fails as the result of an ACH return may trigger various events in Dwolla. Reference the list of possible events in our API docs. The pending transfer will be updated to failed and cause a balance adjustment that results in an increase in the source Accounts's balance.


Transfer scenario 2

Unverified Customer B's bank to Partner Account's bank

Example HTTP request and response:
POST https://api-sandbox.dwolla.com/transfers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer {accessToken}
{
    "_links": {
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/c91d6516-1855-4d36-be7c-bc78cc7c52c3"
        },
        "destination": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/e3103a12-63b5-4d5e-a0be-20ae2ee22264"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "100.00"
    }
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/1952e3a7-6d46-e711-80f2-0aa34a9b2388

Success

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer B 1952e3a7-6d46-e711-80f2-0aa34a9b2388
Destination transfer_created Partner Account 1952e3a7-6d46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network and to Partner Account

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer B 1952e3a7-6d46-e711-80f2-0aa34a9b2388
Destination transfer_completed Partner Account 1952e3a7-6d46-e711-80f2-0aa34a9b2388
Destination bank_transfer_created Partner Account 69d1bdfe-6d46-e711-80f2-0aa34a9b2388

Transfer completes to destination Account's bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_completed Partner Account 69d1bdfe-6d46-e711-80f2-0aa34a9b2388

Fail - ACH return on source bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer B 6d86553e-cd46-e711-80f2-0aa34a9b2388
Destination transfer_created Partner Account 6d86553e-cd46-e711-80f2-0aa34a9b2388

Transfer fails to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_transfer_failed Customer B 6d86553e-cd46-e711-80f2-0aa34a9b2388
Destination transfer_failed Partner Account 6d86553e-cd46-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? A common ACH return from a source bank account is an R01(Insufficient funds). If an R01 is returned the bank account stays connected, however other R codes may trigger other Account or Funding Source events. Reference the list of possible events in our API docs.

Fail - ACH return on destination bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer B d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination transfer_created Partner Account d12005f2-cd46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer B d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination transfer_completed Partner Account d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination bank_transfer_created Partner Account 9a607613-ce46-e711-80f2-0aa34a9b2388

Transfer fails to destination bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_failed Partner Account 9a607613-ce46-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? A bank transfer that fails as the result of an ACH return may trigger various events in Dwolla. Reference the list of possible events in our API docs. The pending transfer will be updated to failed and cause a balance adjustment that results in an increase in the destination Account's balance.

Recommendation:

  • Refund the transfer back to the source Customer's bank account.
  • Re-attempt the transfer from the Partner Account's balance once the Partner Account has corrected the issue with their bank.

Fail "post-settlement"- ACH return on source bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer B a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination transfer_created Partner Account a8dc9fbe-cf46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer B a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination transfer_completed Partner Account a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination bank_transfer_created Partner Account f3dad1dd-cf46-e711-80f2-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_completed Partner Account f3dad1dd-cf46-e711-80f2-0aa34a9b2388

Transfer fails "post-settlement" on source Customer's bank

Customer Event Topic Name Transfer Id
Source customer_transfer_failed Customer B a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination transfer_failed Partner Account a8dc9fbe-cf46-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? A common ACH return from a source bank account is an R01(Insufficient funds). If an R01 is returned the bank account stays connected, however other R codes may trigger other Account or Funding Source events. Reference the list of possible events in our API docs.

Fail "post-settlement"- ACH return on destination bank account

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer B 6edb4f36-d146-e711-80f2-0aa34a9b2388
Destination transfer_created Partner Account 6edb4f36-d146-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network and Partner Account

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer B 6edb4f36-d146-e711-80f2-0aa34a9b2388
Destination transfer_completed Partner Account 6edb4f36-d146-e711-80f2-0aa34a9b2388
Destination bank_transfer_created Partner Account 71f7aa77-d146-e711-80f2-0aa34a9b2388

Transfer completes to Partner Account's bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_completed Partner Account 71f7aa77-d146-e711-80f2-0aa34a9b2388

Transfer fails "post-settlement" on Partner Account's bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_failed Partner Account 71f7aa77-d146-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? A bank transfer that fails as the result of an ACH return may trigger various events in Dwolla. Reference the list of possible events in our API docs. The pending transfer will be updated to failed and cause a balance adjustment that results in an increase in the destination Accounts's balance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.