Skip to content

Instantly share code, notes, and snippets.

@spencerhunter

spencerhunter/TransferAndEvents.md

Last active June 14, 2023 20:10
Show Gist options
  • Save spencerhunter/2ab064e8e76a049eb22e17ed8e92f350 to your computer and use it in GitHub Desktop.
Save spencerhunter/2ab064e8e76a049eb22e17ed8e92f350 to your computer and use it in GitHub Desktop.
Download ZIP
Outlines the sequence of events that are triggered for a subset of Dwolla payment flows that are bank-to-bank via ACH
Raw
TransferAndEvents.md

Overview

Use this doc as a reference to map out the sequence of events your app will receive based on Customer type(s) involved in the transfer 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: Verified Customer bank Destination: Verified Customer bank.
Transfer scenario 2 - Source: Verified Customer bank Destination: Unverified Customer bank.
Transfer scenario 3 - Source: Unverified Customer bank Destination: Verified Customer bank.

Both success and failure cases will be shown as well as 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

Verified Customer A's bank to Verified 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/7e94633f-8916-4ca8-adca-a15400c10c55"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "100.00"
    }
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/caf3e9a7-8239-e711-80f1-0aa34a9b2388

Success

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A c9f3e9a7-8239-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A caf3e9a7-8239-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B caf3e9a7-8239-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network and Customer B

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A c9f3e9a7-8239-e711-80f1-0aa34a9b2388
Source customer_transfer_completed Customer A caf3e9a7-8239-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B caf3e9a7-8239-e711-80f1-0aa34a9b2388
Destination customer_bank_transfer_created Customer B 55140eef-8239-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_completed Customer B 55140eef-8239-e711-80f1-0aa34a9b2388

Fail - ACH return on source Customer's bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A 3d86b835-493a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 3e86b835-493a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 3e86b835-493a-e711-80f1-0aa34a9b2388

Transfer fails to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_failed Customer A 3d86b835-493a-e711-80f1-0aa34a9b2388
Source customer_transfer_failed Customer A 3e86b835-493a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer B 3e86b835-493a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? A common ACH return code from a source bank account is an R01(Insufficient funds). Refer to this resource article for more information on what actions can occur in the Dwolla system when a bank transfer fails.

Fail - ACH return on destination Customer's bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A 2e34ce37-4b3a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 2f34ce37-4b3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 2f34ce37-4b3a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network and Customer B

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A 2e34ce37-4b3a-e711-80f1-0aa34a9b2388
Source customer_transfer_completed Customer A 2f34ce37-4b3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B 2f34ce37-4b3a-e711-80f1-0aa34a9b2388
Destination customer_bank_transfer_created Customer B 722ada79-4b3a-e711-80f1-0aa34a9b2388

Transfer fails to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_failed Customer B 722ada79-4b3a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

The pending bank transfer will be updated to failed status and cause a balance adjustment that results in an increase in the destination Customer's balance.

Possible actions

  • Prompt the receiving user to connect a new bank account. Once the bank account is connected they'll need to initiate a transfer from their balance to the new bank account.
  • Refund the transaction back to the source Customer's bank account.

Fail "post-settlement"- ACH return on source Customer's bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A 9883834f-4e3a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 9983834f-4e3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B 9983834f-4e3a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network and Customer B

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A 9883834f-4e3a-e711-80f1-0aa34a9b2388
Source customer_transfer_completed Customer A 9983834f-4e3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B 9983834f-4e3a-e711-80f1-0aa34a9b2388
Destination customer_bank_transfer_created Customer B 79772592-4e3a-e711-80f1-0aa34a9b2388

Transfer completes to the destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_completed Customer B 79772592-4e3a-e711-80f1-0aa34a9b2388

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

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_failed Customer A 9883834f-4e3a-e711-80f1-0aa34a9b2388
Source customer_transfer_failed Customer A 9983834f-4e3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer B 9983834f-4e3a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

If an ACH return code occurs on the source Customer's bank "post-settlement" a processed transfer will be updated to a failed status. Important: The failed bank transfer in this transfer scenario will cause a balance adjustment which decreases the destination Customer's balance.

Possible actions:

  • Reclaim the funds from the destination Customer's bank account by initiating a transfer from the bank to their balance. This will offset the negative balance from the failed payment.

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

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A f383312d-523a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A f483312d-523a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer B f483312d-523a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network and Customer B

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A f383312d-523a-e711-80f1-0aa34a9b2388
Source customer_transfer_completed Customer A f483312d-523a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer B f483312d-523a-e711-80f1-0aa34a9b2388
Destination customer_bank_transfer_created Customer B 2ae3317a-523a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_completed Customer B 2ae3317a-523a-e711-80f1-0aa34a9b2388

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

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_failed Customer B 2ae3317a-523a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

If an ACH return occurs on the destination Customer's bank "post-settlement" a processed transfer will be updated to a failed status. Important: The failed bank transfer in this transfer scenario will cause a balance adjustment which increases the destination Customer's balance.

Possible actions:

  • Prompt the user to connect a new bank account. Once the bank account is connected they'll need to initiate a transfer from their balance to the new bank account.
  • Refund the transaction back to the source Customer's bank account.

Transfer scenario 2

Verified Customer A's bank to Unverified Customer C'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 customer_bank_transfer_created Customer A 52fbb333-573a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 53fbb333-573a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer C 53fbb333-573a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A 52fbb333-573a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer A 53fbb333-573a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer C 53fbb333-573a-e711-80f1-0aa34a9b2388

Fail - ACH return on source bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A 9f819988-a43a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A a2819988-a43a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer C a2819988-a43a-e711-80f1-0aa34a9b2388

Transfer fails to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_failed Customer A 9f819988-a43a-e711-80f1-0aa34a9b2388
Source customer_transfer_failed Customer A a2819988-a43a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer C a2819988-a43a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? A common ACH return code from a source bank account is an R01(Insufficient funds). Refer to this resource article for more information on what actions can occur in the Dwolla system when a bank transfer fails.

Fail - ACH return on destination bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A 2bd94605-a73a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 01ea700b-a73a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer C 01ea700b-a73a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A 2bd94605-a73a-e711-80f1-0aa34a9b2388

Transfer fails to destination bank

Customer Event Topic Name Transfer Id
Source customer_transfer_failed Customer A 01ea700b-a73a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer C 01ea700b-a73a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

The pending transfer will be updated to failed and cause a balance adjustment that results in an increase in the source Customer's balance.

Possible actions:

  • Refund the transfer back to the source Customer's bank account.
  • Re-attempt the transfer from the source Customer'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 customer_bank_transfer_created Customer A 53ac3cf7-f83a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 54ac3cf7-f83a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer C 54ac3cf7-f83a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A 53ac3cf7-f83a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer A 54ac3cf7-f83a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer C 54ac3cf7-f83a-e711-80f1-0aa34a9b2388

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

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_failed Customer A 53ac3cf7-f83a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

If an ACH return occurs on the source Customer's bank "post-settlement" a processed transfer will be updated to a failed status. Important: The failed bank transfer in this transfer scenario will cause a balance adjustment which decreases the source Customer's balance.

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

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_created Customer A 36a8e567-fa3a-e711-80f1-0aa34a9b2388
Source customer_transfer_created Customer A 37a8e567-fa3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_created Customer C 37a8e567-fa3a-e711-80f1-0aa34a9b2388

Transfer completes to Dwolla network and Customer C

Customer Event Topic Name Transfer Id
Source customer_bank_transfer_completed Customer A 36a8e567-fa3a-e711-80f1-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer A 37a8e567-fa3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_completed Customer C 37a8e567-fa3a-e711-80f1-0aa34a9b2388

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

Customer Event Topic Name Transfer Id
Source customer_transfer_failed Customer A 37a8e567-fa3a-e711-80f1-0aa34a9b2388
Destination customer_transfer_failed Customer C 37a8e567-fa3a-e711-80f1-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

If an ACH return occurs on the destination Customer's bank "post-settlement" a processed transfer will be updated to a failed status. Important: The failed bank transfer in this transfer scenario will cause a balance adjustment which increases the source Customer's balance.

Transfer scenario 3

Unverified Customer C's bank to Verified Customer A'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 C 1952e3a7-6d46-e711-80f2-0aa34a9b2388
Destination customer_transfer_created Customer A 1952e3a7-6d46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network and to Customer A

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer C 1952e3a7-6d46-e711-80f2-0aa34a9b2388
Destination customer_transfer_completed Customer A 1952e3a7-6d46-e711-80f2-0aa34a9b2388
Destination customer_bank_transfer_created Customer A 69d1bdfe-6d46-e711-80f2-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_completed Customer A 69d1bdfe-6d46-e711-80f2-0aa34a9b2388

Fail - ACH return on source bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer C 6d86553e-cd46-e711-80f2-0aa34a9b2388
Destination customer_transfer_created Customer A 6d86553e-cd46-e711-80f2-0aa34a9b2388

Transfer fails to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_transfer_failed Customer C 6d86553e-cd46-e711-80f2-0aa34a9b2388
Destination customer_transfer_failed Customer A 6d86553e-cd46-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? A common ACH return code from a source bank account is an R01(Insufficient funds). Refer to this resource article for more information on what actions can occur in the Dwolla system when a bank transfer fails.

Fail - ACH return on destination bank

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer C d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination customer_transfer_created Customer A d12005f2-cd46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer C d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination customer_transfer_completed Customer A d12005f2-cd46-e711-80f2-0aa34a9b2388
Destination customer_bank_transfer_created Customer A 9a607613-ce46-e711-80f2-0aa34a9b2388

Transfer fails to destination bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_failed Customer A 9a607613-ce46-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

The pending transfer will be updated to failed and cause a balance adjustment that results in an increase in the destination Customer's balance.

Possible actions:

  • Refund the transfer back to the source Customer's bank account.
  • Re-attempt the transfer from the destination Customer'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 customer_transfer_created Customer C a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination customer_transfer_created Customer A a8dc9fbe-cf46-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer C a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination customer_transfer_completed Customer A a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination customer_bank_transfer_created Customer A f3dad1dd-cf46-e711-80f2-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_completed Customer A 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 C a8dc9fbe-cf46-e711-80f2-0aa34a9b2388
Destination customer_transfer_failed Customer A a8dc9fbe-cf46-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

If an ACH return occurs on the source Customer's bank "post-settlement" a processed transfer will be updated to failed. Important: The failed bank transfer in this transfer scenario will cause a balance adjustment which decreases the destination Customer's balance.

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

Transfer initiated

Customer Event Topic Name Transfer Id
Source customer_transfer_created Customer C 6edb4f36-d146-e711-80f2-0aa34a9b2388
Destination customer_transfer_created Customer A 6edb4f36-d146-e711-80f2-0aa34a9b2388

Transfer completes to Dwolla network and Customer A

Customer Event Topic Name Transfer Id
Source customer_transfer_completed Customer C 6edb4f36-d146-e711-80f2-0aa34a9b2388
Destination customer_transfer_completed Customer A 6edb4f36-d146-e711-80f2-0aa34a9b2388
Destination customer_bank_transfer_created Customer A 71f7aa77-d146-e711-80f2-0aa34a9b2388

Transfer completes to destination Customer's bank

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_completed Customer A 71f7aa77-d146-e711-80f2-0aa34a9b2388

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

Customer Event Topic Name Transfer Id
Destination customer_bank_transfer_failed Customer A 71f7aa77-d146-e711-80f2-0aa34a9b2388

What occurs in Dwolla system? There are a subset of ACH return codes that trigger systematic actions within the Dwolla system. For example, removal of funding source or suspension of customer record. Reference the more information in this article on the Dwolla systematic actions and ACH return codes.

If an ACH return occurs on the destination Customer's bank "post-settlement" a processed transfer will be updated to failed. Important: The failed bank transfer in this transfer scenario will cause a balance adjustment which increases the destination Customer's balance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment