Plaid logo
Docs
ALL DOCS

Auth

  • Introduction to Auth
  • Add Auth to your app
  • Money movement partnerships
  • Increasing pay-by-bank adoption
  • Additional Auth flows
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

    Micro-deposit events

    Learn how to use Bank Transfers webhooks to receive micro-deposit status updates

    Overview

    If you are using the optional Same Day Micro-deposits verification flow for Auth and want to receive updates on the state of your micro-deposit transfers, you can enable webhooks for Bank Transfer events that notify you of transfer status updates for Plaid-initiated transfers within the ACH network.

    Bank Transfers webhooks

    To enable Bank Transfers webhooks, add your endpoint on the account webhooks page of the dashboard. You will need to have received production approval for Auth before being able to add an endpoint.

    Bank Transfers webhooks are not part of Plaid's Transfer product. All Auth customers have access to Bank Transfer webhooks; it is not required to sign up for Plaid Transfer to use these webhooks.

    To confirm that your endpoint has been correctly configured, you can trigger a test webhook via /sandbox/bank_transfer/fire_webhook. You should receive the payload body specified below.

    1{
    2 "webhook_type": "BANK_TRANSFERS",
    3 "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE"
    4}

    Once you have enabled Bank Transfers webhooks, the /bank_transfer/event/sync endpoint can be called to discover new ACH events. To know when you should call this endpoint, listen for the BANK_TRANSFERS_EVENTS_UPDATE webhook. You will receive a Bank Transfers webhook any time you have posted or returned ACH micro-deposit events available. You can also search or filter micro-deposit events using the /bank_transfer/event/list endpoint.

    Bank Transfers webhooks and the Bank Transfers endpoint will reflect any micro-deposit sent by Plaid, including both Same Day Micro-deposits and Automated Micro-deposits, if enabled. Bank Transfers webhooks and endpoints will only reflect data about ACH events initiated through Plaid. They do not reflect other ACH activity on a linked account.

    Event types

    Once your user successfully completes the micro-deposit Link flow, you will receive an account_id in the success callback. Bank Transfers events also contain an account_id, which you should use to connect events to the corresponding user.

    Pending

    A pending event type means that we have a record of the micro-deposit in our systems, but it has not yet been sent. You may assume that micro-deposits are in a pending state once you exchange the corresponding Item’s public token for an access token. Note that Plaid does not send webhooks for new pending events, but you will still see pending events in event sync responses.

    1{
    2 "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9",
    3 "bank_transfer_amount": "0.01",
    4 "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8",
    5 "bank_transfer_iso_currency_code": "USD",
    6 "bank_transfer_type": "credit",
    7 "direction": "outbound",
    8 "event_id": 5,
    9 "event_type": "pending",
    10 "failure_reason": null,
    11 "origination_account_id": null,
    12 "receiver_details": null,
    13 "timestamp": "2021-03-22T18:52:02Z"
    14}
    Recommended action

    No action needed

    Posted

    For successful micro-deposit transfers, posted events are the terminal event type, and no more events will be issued. Note that the end user may not receive the micro-deposit until several banking hours after the posted event. In addition, a posted event does not guarantee that the micro-deposit was successful; if the micro-deposit fails, a reversed event will eventually occur some time after the posted event.

    1{
    2 "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9",
    3 "bank_transfer_amount": "0.01",
    4 "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8",
    5 "bank_transfer_iso_currency_code": "USD",
    6 "bank_transfer_type": "credit",
    7 "direction": "outbound",
    8 "event_id": 5,
    9 "event_type": "posted",
    10 "failure_reason": null,
    11 "origination_account_id": null,
    12 "receiver_details": null,
    13 "timestamp": "2021-03-22T18:52:02Z"
    14}
    Recommended Action

    If the micro-deposit succeeds, all posted transfers will land in the end user’s account by 8:30am EST on the following banking day.

    After the micro-deposit settlement time, Plaid recommends sending the end user an alert (through SMS, email, or push notification) to verify the micro-deposit amounts.

    If you have enabled both Same Day and Automated micro-deposits, then before notifying the user, you should first confirm that the event corresponds to a Same Day micro-deposit by checking that the verification status is pending_manual_verification (and not pending_automatic_verification, which would correspond to an Automated Micro-deposit). Because Plaid handles Automated Micro-deposits without user interaction, it is not necessary to prompt the user during the Automatic Micro-deposit flow.

    If you have not already stored the verification status, you can obtain it by calling /accounts/get.

    Reversed

    A reversed event indicates that a micro-deposit attempt has failed. Reversed events will contain an ACH return code that indicates why the micro-deposit failed.

    1{
    2 "account_id": "bV8WNn73rLI5Ln1MmdErsDn9jv7w37uGMaQvP",
    3 "bank_transfer_amount": "0.01",
    4 "bank_transfer_id": "826712b2-c707-cf98-5ba9-13bd3cc2b2f0",
    5 "bank_transfer_iso_currency_code": "USD",
    6 "bank_transfer_type": "credit",
    7 "direction": "outbound",
    8 "event_id": 5,
    9 "event_type": "reversed",
    10 "failure_reason": {
    11 "ach_return_code": "R03",
    12 "description": "No account or unable to locate account"
    13 },
    14 "origination_account_id": null,
    15 "receiver_details": null,
    16 "timestamp": "2021-03-25T21:35:47Z"
    17}
    Recommended Action

    Contact the user with a notification that authentication has failed. Once they return to your application, restart the Link flow to begin another authentication attempt.

    Was this helpful?
    Developer community
    GitHub
    GitHub
    Stack Overflow
    Stack Overflow
    YouTube
    YouTube
    Discord
    Discord