Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save spencerhunter/998543e83b83992ae00a591e3f37abc7 to your computer and use it in GitHub Desktop.
Save spencerhunter/998543e83b83992ae00a591e3f37abc7 to your computer and use it in GitHub Desktop.
Example of a bank to bank transfer between a Client 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: Client Account bank Destination: Unverified Customer bank.
Transfer scenario 2 - Source: Unverified Customer bank Destination: Client 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

Client 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 Client Account 52fbb333-573a-e711-80f1-0aa34a9b2388
Source transfer_created Client 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 Client Account 52fbb333-573a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_completed Client 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 Client Account 9f819988-a43a-e711-80f1-0aa34a9b2388
Source transfer_created Client 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 Client Account 9f819988-a43a-e711-80f1-0aa34a9b2388
Source transfer_failed Client 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 Client Account 2bd94605-a73a-e711-80f1-0aa34a9b2388
Source transfer_created Client 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 Client Account 2bd94605-a73a-e711-80f1-0aa34a9b2388

Transfer fails to destination bank

Customer Event Topic Name Transfer Id
Source transfer_failed Client 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 Client Account 53ac3cf7-f83a-e711-80f1-0aa34a9b2388
Source transfer_created Client 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 Client Account 53ac3cf7-f83a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_completed Client 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 Client 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 Client Account 36a8e567-fa3a-e711-80f1-0aa34a9b2388
Source transfer_created Client 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 Client Account 36a8e567-fa3a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source transfer_completed Client 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 Client 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 Client 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 Client Account 1952e3a7-6d46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network and to Client Account

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

Transfer completes to destination Account's bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_completed Client 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 Client 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 Client 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 Client 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 Client Account d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination bank_transfer_created Client Account 9a607613-ce46-e711-80f2-0aa34a9b2388

Transfer fails to destination bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_failed Client 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 Client Account's balance once the Client 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 Client 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 Client Account a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination bank_transfer_created Client Account f3dad1dd-cf46-e711-80f2-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination bank_transfer_completed Client 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 Client 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 Client Account 6edb4f36-d146-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network and Client Account

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

Transfer completes to Client Account's bank

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

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

Customer Event Topic Name Transfer Id
Destination bank_transfer_failed Client 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