Plaid logo
Docs
ALL DOCS

Transfer

  • Transfer Overview
  • Transfer Application
  • Creating transfers
  • Monitoring transfers
  • Plaid Ledger flow of funds
  • Transfer Dashboard
  • Refunds
  • Recurring transfers
  • Transfer UI
  • Platform Payments
  • Errors and troubleshooting
  • Testing in Sandbox
  • Legacy Flow of funds
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus 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 Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    Get API Keys
    Open nav

    Monitoring transfers

    Monitor for updates to transfers, sweeps, and refunds

    Event monitoring

    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.

    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". 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.

    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 sweeps with your bank account

    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:

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

    Performing financial reconciliation audits

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

    Flow of funds

    Understand how your money moves through the Plaid network

    Learn more

    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
    Discord
    Discord