Micro-deposit events

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.

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.

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.

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.

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

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.

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.