Reconciling Transfers

You can use the /transfer/event/sync endpoint to retrieve all of the events and statuses associated with your transfers. This is useful when performing reconciliation, as it guarantees that you've seen all transfer events. The main identifier for Plaid transfers is the transfer_id. You should plan to store this identifier to help facilitate transfer reconciliation.

First, retrieve from your datastore the last event_id that was retrieved from the sync endpoint and set that as your after_id.

1after_id = yourDatabase.get("after_id")
2events = new Array(BankTransferEvent)

Next, call the /transfer/event/sync endpoint with that after_id and persist the returned events in your datastore. The endpoint will return a maximum of 25 events at a time. Continue calling the /transfer/event/sync endpoint, passing in the last event_id from the previous call until the response has zero results.

1# Start at the last event ID received
2after_id = yourDatabase.get("after_id")
3events = new Array(BankTransferEvent)
4
5# Poll event sync endpoint until there are no more new events
6do {
7  # Fetch the next set of events and update after_id
8  events = plaidClient.BankTransferEventSync(after_id)
9  after_id += len(events)
10
11  # Handle any new events
12  for event in events {
13    # Store ID, event type (e.g. pending, posted, failed, canceled), timestamp
14    yourDatabase.set(event.bank_transfer_id, event.event_type, event.timestamp}
15} while (!events.Empty());

Finally, persist that last event_id in your datastore to use the next time you perform this process.

1yourDatabase.set("after_id", after_id)

For a real-life example of an app that incorporates the /transfer/event/sync endpoint, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer event sync code can be found in handleTransferWebhook.js

A single transfer will have more than one event associated with it. For example, a successful transfer’s status will initially start out as pending before it’s sent to the ACH network, then move to posted when the funds are available in the account. Each of these status updates will return a unique event from the /transfer/event/sync endpoint, so, in this example, you’ll see two events for this particular transfer_id throughout its lifespan.

Listed below are the event transitions you will see as a transfer progresses through its lifespan.