Reconciling Transfers

Monitor transfers as they move through the ACH network and reconcile transfers with your bank accounts.

Plaid creates a transfer event any time the transfer.status or transfer.sweep_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 or returned transfer. When a transfer gets settled, you can alert customers or release goods and services.

There are two types of statuses: transfer.status and transfer.sweep_status. transfer.status indicates the transfer's movement through the network from your consumer's perspective. transfer.sweep_status reflects whether Plaid has swept the amount to your own business account (if this is a debit, this means depositing funds to your final account; in case of a credit, this means collecting funds from your final account).

The transfer status settled indicates that the funds have either been taken from or arrived into the customer account. Similarly, the sweep status swept_settled indicates that the funds have arrived into or been taken from your account. You can view the events fired for a given transfer in the dashboard under a transfer’s "Activity Log" in the Dashboard.

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". 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 id reported by the latest response and use that id the next time you call /transfer/event/sync.

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, 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 a sweep in your bank account to the set of transfers included in that sweep, 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 in your Plaid Transfer dashboard. On your dashboard, you can view the sweep details as well as the associated transfers in that sweep.

You can also do the same lookup via API. Once you identify and isolate the sweep prefix (such as 6c036ea0), pass it to /transfer/sweep/list to obtain the full sweep_id, then use that sweep_id to query /transfer/event/list and retrieve all the associated transfer_ids in that sweep.

1curl -X POST https://production.plaid.com/transfer/sweep/list \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "sweep_id": "6c036ea0"
5  }'

1{
2  "sweeps": [
3    {
4      "id": "6c036ea0-911a-43e8-9848-ba531d6dc39a",
5      "amount": "-5264.62",
6      "created": "2022-11-18T07:10.824Z"
7    },
8  ],
9  "request_id": "saKrIBuEB9qJZno"
10}

Now, take the sweep_id and find all transfers bundled into that sweep.

1curl -X POST https://production.plaid.com/transfer/event/list \
2  -H 'content-type: application/json' \
3  -d '{
4    "sweep_id": "6c036ea0-911a-43e8-9848-ba531d6dc39a"
5  }'

1{
2  "transfer_events": [
3    {
4      "account_id": "AgbZBPQPWwT15dZnyEzLs1dLWlK4XrF1awz1m",
5      "event_id": "1002",
6      "event_type": "swept",
7      "sweep_amount": "5.00",
8      "sweep_id": "6c036ea0-911a-43e8-9848-ba531d6dc39a",
9      "timestamp": "2022-11-18T02:25.436Z",
10      "transfer_amount": "5.00",
11      "transfer_id": "a574f217-6963-49d3-84f3-c3b83975ced5",
12      "transfer_type": "debit"
13    },
14    {
15      "account_id": "vQJblmka1Vt5pabdlZnmHwG4RpV5VMhWlLrXm",
16      "event_id": "1001",
17      "event_type": "return_swept",
18      "sweep_amount": "-2348.00",
19      "sweep_id": "6c036ea0-911a-43e8-9848-ba531d6dc39a",
20      "timestamp": "2022-11-18T02:25.436Z",
21      "transfer_amount": "2348.00",
22      "transfer_id": "945bcfaf-3047-4b98-b4f6-f96dfa63fae2",
23      "transfer_type": "debit"
24    },
25    ...
26  ],
27  "request_id": "saKrIBuEB9qJZno"
28}