Micro-deposit events

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

Overview

To receive updates on the state of your micro-deposit transfers, you can enable webhooks for Bank Transfers events that notify you of transfer status updates within the ACH network.

Bank Transfers webhooks

To enable Bank Transfers webhooks, contact your account manager. You will need to provide them with the endpoint at which you want to receive the webhooks. For more details on enabling and configuring Bank Transfers webhooks, see Webhooks in Bank Transfers.

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

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

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

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

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.