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.
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
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 |
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.
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.
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.
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.
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
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 |
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.
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.
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.
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.