Reconciling Transfers
Learn how to reconcile transfers
Transfer is only supported in Plaid's Sandbox and Production environments.
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.
Syncing Transfer events
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 received2after_id = yourDatabase.get("after_id")3events = new Array(BankTransferEvent)45# Poll event sync endpoint until there are no more new events6do {7 # Fetch the next set of events and update after_id8 events = plaidClient.BankTransferEventSync(after_id)9 after_id += len(events)1011 # Handle any new events12 for event in events {13 # Store ID, event type (e.g. pending, posted, failed, canceled), timestamp14 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)
Sample app code
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
Progression of Transfer events
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.
Description | Event(s) |
---|---|
You submitted a transfer | pending |
You cancelled the transfer | pending → cancelled |
The transfer could not be processed, reach out to your Plaid point of contact | pending → failed |
Funds are available in your or your user’s account | pending → posted |
Transfer has resulted in an ACH return and funds have been clawed back | pending → posted → returned |