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. If you are not able to access the page, contact your Plaid Account Manager.

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.

Bank transfers endpoints will only provide data about ACH events initiated through Plaid. They do not fire for other ACH activity on a linked account.

If you are a customer participating in the Transfer (beta) and already using Transfer endpoints, you will receive micro-deposit updates via the Transfer webhooks and the /transfer/event/sync endpoint instead of via Bank Transfer webhooks and endpoints.

See the Transfer webhooks reference for more details.

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. Each account_id will have two micro-deposit credits for authentication and one clawback debit to bring the funds back to Plaid.

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.52",
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}

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.08",
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}

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.

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.32",
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}

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.