Plaid logo
Docs
ALL DOCS

Transfer

  • Transfer Overview
  • Transfer Application
  • Creating transfers
  • Reconciling transfers
  • Flow of funds
  • Transfer Dashboard
  • Refunds
  • Recurring transfers
  • Transfer UI
  • Errors and troubleshooting
  • Testing in Sandbox
Plaid logo
Docs
Close search modal
Experimental
Ask Finn!Ask a question to get started
Note: Finn isn't perfect. He's just a chatbot that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Finn any PII -- he's scared of intimacy. All chats with Finn are subject to Plaid's Privacy Policy.
Plaid.com
Get API keys
Open nav

Reconciling Transfers

Monitor transfers updates

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

Transfer event monitoring

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.

Overview of status and sweep status updates
Overview of status and sweep status updates

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.

Ingesting event updates

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.

Filtering for specific events

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}

Reconciling transfers with your bank account

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:

EntryAmountDate
PLAID 6c036ea0 CCD-$5,264.62November 18, 2022
PLAID ae42c210 CCD$2,367.80November 16, 2022
PLAID 550c85fc CCD$6,007.49November 10, 2022

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.

Select Language
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.

Select Language
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}

Flow of funds

Understand how your money moves through the Plaid network

Learn more
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord