Tracking transfer status

All transfers initiated via ACH (including refunds and sweeps) move through a set of statuses that correspond to phases in the ACH lifecycle. Understanding these lets you forecast funds availability and surface accurate messaging to your end users.

Plaid creates a transfer event any time the transfer.status changes. For example, when a transfer is sent to the payment network, the transfer.status moves to posted and a posted event is emitted. Likewise, when an ACH return is received, a returned event will be emitted as the transfer.status is updated. By monitoring transfer events, you can stay informed about their current status and notify customers in case of a canceled, failed, or returned transfer. When transfer.status moves to settled, you can safely expect that the consumer can see the transaction reflected in their personal bank account.

Events are also emitted for changes to a sweep's and refund's status property. These events follow an [object].[status] format, such as sweep.posted and refund.posted.

For a list of all event types and descriptions, see the API Reference.

Most integrations proactively monitor all events for every transfer. This allows you to respond to transfer events with business logic operations, such as:

• Kicking off the fulfillment of an order once the transfer has settled
• Making funds available to your end consumers for use in your application
• Monitoring returns to know when to claw these services back, or retry the transfer

To do this, set up Transfer webhooks to listen for updates as they happen. You must register a URL to enable webhooks to be sent.

You can do this in the webhook settings page of the Plaid Dashboard. Click New Webhook and specify a webhook URL for a "Transfer Webhook". You must be enabled for Production access to Transfer in order to access this option. To confirm that your endpoint has been correctly configured, you can trigger a test webhook via /sandbox/transfer/fire_webhook.

Now, every time there are new transfer events, Plaid will fire a notification webhook.

1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "TRANSFER_EVENTS_UPDATE",
4  "environment": "production"
5}

To receive details about the event, call /transfer/event/sync.

1{
2  # Return the next 20 transfer events after the transfer event with id 4
3  "after_id": "4",
4  "count": "20"
5}

You can then store the highest event_id returned by the response and use that value as the after_id the next time you call /transfer/event/sync to get only the new events.

Note that webhooks don't contain any identifying information about what transfer has updated; only that an update happened. As an alternative to listening to webhooks, your application could also call /transfer/event/sync on a regular basis to process the most recent batch of Transfer events.

For a real-life example of an app that incorporates the transfer webhook and tests it using the /sandbox/transfer/fire_webhook 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 webhook handler can be found in handleTransferWebhook.js and the test which fires the webhook can be found at events.js.

Calling /transfer/event/list will get a list of transfer events based on specified filter criteria. For example, you could search for all events for a specific transfer_id. If you do not specify any filter criteria, this endpoint will return the latest 25 transfer events.

You can apply filters to only fetch specific event types, events for a specific transfer type, a specific sweep, etc.

1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "transfer_amount": "12.34",
6      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "transfer_type": "credit",
8      "event_id": 1,
9      "event_type": "pending",
10      "failure_reason": null,
11      "origination_account_id": null,
12      "originator_client_id": null,
13      "refund_id": null,
14      "sweep_amount": null,
15      "sweep_id": null,
16      "timestamp": "2019-12-09T17:27:15Z"
17    }
18  ],
19  "request_id": "mdqfuVxeoza6mhu"
20}

As Plaid moves money in and out of your business account as you process transfers and cashout the Plaid Ledger balance, you might want to match the account activity in your bank account with the associated transfers.

Plaid will deposit or draw money from your business checking account in the form of a sweep. This means that any time you are interacting with your bank statement, you are viewing sweeps, not specific transfers.

To match an entry in your bank account with a sweep in Plaid's records, Plaid ensures the first 8 characters of the sweep's sweep_id will show up on your bank statements. For example, consider the following entries in your bank account from Plaid:

You can use this 8 character string from your bank statement to search for the sweep via /transfer/sweep/get, or in your Plaid Transfer dashboard.

To follow the lifecycle of a sweep, and monitor funds coming into and out of your business checking account due to Plaid Transfer activity, observe the sweep.* events in the /transfer/event/sync endpoint. To view all sweeps, use /transfer/sweep/list.

To see if a given debit transfer has been included in a sweep transaction, check the transfer's status field. If it has been swept, it will have the funds_available status.

For information on performing financial reconciliation audits, see Report extraction.