Businesses rely on Dwolla to provide a flexible and intuitive API for creating an embedded payments experience. This core service makes it crucial for us to provide transparency and traceability throughout the transfer process.
The initiation and settlement of an account-to-account transfer involves traversing multiple independent steps throughout its lifecycle. The most complex payment flow is of a bank-to-bank transfer between two Verified Customer records. Since the customers on either side of the transaction have the ability to hold a balance, their transactions will flow through the Dwolla Network before making it into the destination bank account.
As the funds move through each step, Dwolla records the changes by creating new, related transfer resources and events. These events trigger webhooks that developers can subscribe to in order to receive real-time updates on a transfer's status. In order to help businesses more efficiently track and reconcile transfers happening across the network, Dwolla’s Correlation IDs have proven their value.
The problem
While Dwolla is providing transparency into the transfer’s lifecycle, there are multiple transfer IDs to keep track of for a single end-to-end transfer, which can become cumbersome.
The Correlation ID request parameter was introduced as a way to correlate transfers created in Dwolla with an internal ID that Clients may use in their own application. We quickly realized that it could also be used to address other challenges, such as the one mentioned above – tracking and connecting the various transfer resources involved in a single end-to-end transaction.
Let’s expand on that.
What is a Correlation ID?
A CorrelationId can be any unique string that makes sense to you and your application when it comes to transactions. It can be an invoice number, an order confirmation number, a business ID or an internal ID you use for transfers. It is common to use UUIDs and we recommend doing so. However, it is important to ensure that the string does not contain any personal identifiable information.
How does a Correlation ID help with tracking related transfers?
Let’s take the example of a bank-to-bank transfer created between Verified Customers A and B. This will end up creating three separate transfer resources as outlined below:
- Transfer #1 - Funds moving from Customer A’s Bank into Customer A’s balance in the Dwolla Network
- Transfer #2 - Funds moving from Customer A’s Dwolla Balance into Customer B’s balance in the Dwolla Network
- Transfer #3 - Funds moving from Customer B’s balance in the Dwolla Network to Customer B’s Bank
This is great for tracking each leg of the transfer to determine where the funds are as they pass through the Dwolla Network at any given moment. However, reconciling the transfers and traversing forward or backwards in the transfer flow can be difficult.
As an example, let’s say you get a webhook `customer_bank_transfer_completed` for Transfer ID #3 and wish to locate the transfer that comes before it. You will need to first retrieve Transfer ID #3 from the API. In the response you’ll find a `funding-transfer` link that points to Transfer ID #2. To find further information about #2, you will need to make an additional API call to retrieve that transfer as well.
Instead, you can make one call to Dwolla’s List and Search Transfers for a Customer endpoint, filtered by CorrelationId. Both the incoming and outgoing transfers for that Customer will be returned in a single API response. You don’t need to make any additional API calls to retrieve related transfers. With that said, keep in mind that subsequent transfers are only created once the initial leg of the transfer completes.
GET https: //api.dwolla.com/customers/{customer_id}/transfers?correlationId=DB-ID-123abc
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
"_links": {
"self": {
"href": "https://api.dwolla.com/customers/70088704-f2f1-443e-bd41-f20305d6c912/transfers?correlationId=DB-ID-123abc",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"first": {
"href": "https://api.dwolla.com/customers/70088704-f2f1-443e-bd41-f20305d6c912/transfers?correlationId=DB-ID-123abc&limit=25&offset=0",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"last": {
"href": "https://api.dwolla.com/customers/70088704-f2f1-443e-bd41-f20305d6c912/transfers?correlationId=DB-ID-123abc&limit=25&offset=0",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
}
},
"_embedded": {
"transfers": [
{
"_links": {
"cancel": {
"href": "https://api.dwolla.com/transfers/7a2c9236-257b-ed11-814a-d69963ad6ab7",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"source": {
"href": "https://api.dwolla.com/customers/70088704-f2f1-443e-bd41-f20305d6c912",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"funding-transfer": {
"href": "https://api.dwolla.com/transfers/056a0699-247b-ed11-814a-d69963ad6ab7",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"destination-funding-source": {
"href": "https://api.dwolla.com/funding-sources/3a284e29-94b0-418a-aa57-31be740b59dc",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"self": {
"href": "https://api.dwolla.com/transfers/7a2c9236-257b-ed11-814a-d69963ad6ab7",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"destination": {
"href": "https://api.dwolla.com/funding-sources/3a284e29-94b0-418a-aa57-31be740b59dc",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
}
},
"id": "7a2c9236-257b-ed11-814a-d69963ad6ab7",
"status": "pending",
"amount": {
"value": "123.45",
"currency": "USD"
},
"created": "2022-12-13T20:32:13.913Z",
"clearing": {
"destination": "next-day"
},
"correlationId": "DB-ID-123abc",
"individualAchId": "IK76ZXZL"
},
{
"_links": {
"source": {
"href": "https://api.dwolla.com/customers/cf3f1ad4-fc48-45d3-8aff-0ef5577b8a17",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
},
"destination-funding-source": {
"href": "https://api.dwolla.com/funding-sources/3a284e29-94b0-418a-aa57-31be740b59dc",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"self": {
"href": "https://api.dwolla.com/transfers/056a0699-247b-ed11-814a-d69963ad6ab7",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"funded-transfer": {
"href": "https://api.dwolla.com/transfers/7a2c9236-257b-ed11-814a-d69963ad6ab7",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "transfer"
},
"source-funding-source": {
"href": "https://api.dwolla.com/funding-sources/6b57166c-a0ae-45f3-abc1-0889e0f3559d",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "funding-source"
},
"destination": {
"href": "https://api.dwolla.com/customers/70088704-f2f1-443e-bd41-f20305d6c912",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
}
},
"id": "056a0699-247b-ed11-814a-d69963ad6ab7",
"status": "processed",
"amount": {
"value": "123.45",
"currency": "USD"
},
"created": "2022-12-13T20:27:44.127Z",
"correlationId": "DB-ID-123abc"
}
]
},
"total": 2
}
You can find more detailed code snippets demonstrating how to use a Correlation ID within the Transfer Lifecycle concept article in the developer documentation.
Can a Correlation ID track unrelated transfers?
Correlation IDs can be used to track multiple transfers on Dwolla's platform that may not seem related to each other, but may have a connection within your application.
Let's take Koala Investment Platform as an example; it allows customers to save funds in their Dwolla balance before investing them. The "n" number of deposits into the Dwolla balance and the outgoing investment are completely unrelated in the Dwolla API.
You can use the same CorrelationId each time a customer makes a deposit into their Dwolla balance, and again when an investment is made using the funds from the Dwolla balance. By using the same CorrelationId for both the deposits and the investment transfer, you can create a connection between these otherwise unrelated transfers in the Dwolla API. This allows you to filter and view only the transfers related to a particular investment by using the CorrelationId as a criterion.
How can I access the CorrelationId in the webhook payload?
Each leg of the transfer also triggers webhooks whenever the Dwolla transfer status is created, processed, failed or canceled. We try to keep the webhook payload pretty lightweight, with links to relevant resources, the ID, topic and created timestamp of the event, and the resource ID the event is related to. Check out our documentation for more details about Webhook Events.
{
"_links": {
"self": {
"href": "https://api.dwolla.com/events/2f18b87b-4588-44a6-9cc0-4aa19b33fd61",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "event"
},
"resource": {
"href": "https://api.dwolla.com/transfers/056a0699-247b-ed11-814a-d69963ad6ab7",
"type": "application/vnd.dwolla.v1.hal+json"
},
"account": {
"href": "https://api.dwolla.com/accounts/0ee84069-47c5-455c-b425-633523291dc3",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "account"
},
"customer": {
"href": "https://api.dwolla.com/customers/70088704-f2f1-443e-bd41-f20305d6c912",
"type": "application/vnd.dwolla.v1.hal+json",
"resource-type": "customer"
}
},
"correlationId": "DB-ID-123abc",
"id": "2f18b87b-4588-44a6-9cc0-4aa19b33fd61",
"created": "2022-12-13T20:32:10.975Z",
"topic": "customer_transfer_completed",
"resourceId": "056a0699-247b-ed11-814a-d69963ad6ab7"
}
In the past, when Clients received these webhooks for a secondary leg of a transfer, they would not have been able to map it to a transfer in their database. They would have had to take the following steps to locate the original transfer:
- Call the API to obtain the transfer resource mentioned in the webhook
- Use the links within the transfer to find the transfer ID that it maps to their database
Now, with the CorrelationId attribute included in the webhook, Clients can directly check in their database to locate the original transfer. This saves an extra call to the API for each webhook and shaves off some processing time. Clients can also take the CorrelationId and the customer ID present in the payload to retrieve all legs of the transfer that pertain to this specific Customer.
Taking the above transfer as an example, let’s assume that the receiver is a Verified Customer. In that case, the `customer_transfer_completed` event denotes that the funds have been processed into the Dwolla balance of the receiver. When you retrieve the list of transfers associated with that CorrelationId, you should find 2 items in the list:
- one representing the transfer from Customer A’s balance to Customer B’s balance,
- another one representing the credit portion of the transfer from Customer B’s balance into their own bank account.
Try it out in the Sandbox
We hope that this helps you efficiently track the multiple steps involved in an account-to-account transfer, saving you time and effort. Test adding CorrelationIds to your transfers in the Sandbox environment before releasing it to Production. If you have any other uses for the CorrelationId that we did not mention, or if you have ideas to expand its functionality, we would love to hear them!