# Microdeposit verification Verify that buyers own their bank accounts before you debit them. Bank accounts must be verified before they can be used for payments. Verification confirms that the person adding a bank account is its owner, which protects you from fraud and reduces ACH returns. A sale created with a Payment Instrument that requires Microdeposit verification will fail. Finix supports two ways to verify a bank account: - **[Plaid](/guides/online-payments/bank-payments/plaid-integration) (recommended):** Buyers log in to their bank, and Plaid verifies account existence and ownership instantly. Bank accounts created with Plaid are verified and ready to use immediately. - **Microdeposits:** When buyers enter their bank account details manually, Finix sends a single $0.01 deposit carrying a unique verification code. The buyer confirms ownership by finding the code on their bank statement and submitting it. ## How it works Plaid bank accounts skip Microdeposit verification Bank accounts created with [Plaid](/guides/online-payments/bank-payments/plaid-integration) are already verified and do not require Microdeposit verification. 1. After creating a Payment Instrument, the following fields are set: `enabled: false` and `disabled_code: MICRODEPOSIT_VERIFICATION_REQUIRED`. The Payment Instrument cannot be used for payments until it is verified. 2. Finix sends a single $0.01 deposit to the bank account. The deposit's statement descriptor carries a unique verification code that begins with `FNX` (for example, `FNX7Q2M`). 3. The buyer finds the code on their bank statement and submits it as the `verification_code`. 4. When the submitted code matches, Finix enables the Payment Instrument. The Payment Instrument is now ready to use for payments. The buyer is granted 3 tries to submit the correct code and must complete verification within 30 days or the Microdeposit verification expires. The following bank account Payment Instrument resource is pending Microdeposit verification: ```json Bank account Payment Instrument - Pending Microdeposit verification { "id" : "PIg9NYD5RnZ9C5ACDw1w8zoS", "created_at" : "2026-09-09T18:27:49.33Z", "updated_at" : "2026-09-09T18:27:49.33Z", "application" : "APc9vhYcPsRuTSpKD9KpMtPe", "created_via" : "API", "currency" : "USD", "disabled_code" : "MICRODEPOSIT_VERIFICATION_REQUIRED", "disabled_message" : "Bank account is pending microdeposit verification.", "enabled" : false, "fingerprint" : "FPRuMHQDQbdKZsiRYc9ZHzPVQ", "identity" : "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type" : "BANK_ACCOUNT", "microdeposit" : "microdeposit_9944AfJkuMjmkcd4W6MmFK", "microdeposit_verification_url" : "https://link.sandbox-payment-form.com/ltLgBI", "account_type" : "BUSINESS_CHECKING", "bank_account_validation_check" : "INCONCLUSIVE", "bank_code" : "122105278", "country" : "USA", "institution_number" : null, "masked_account_number" : "XXXXX5702", "name" : "Smith & Associates Consulting", "transit_number" : null, "tags" : { }, "third_party" : null, "third_party_token" : null, "type" : "BANK_ACCOUNT", "_links" : { "self" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIg9NYD5RnZ9C5ACDw1w8zoS" }, "authorizations" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIg9NYD5RnZ9C5ACDw1w8zoS/authorizations" }, "transfers" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIg9NYD5RnZ9C5ACDw1w8zoS/transfers" }, "verifications" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIg9NYD5RnZ9C5ACDw1w8zoS/verifications" }, "application" : { "href" : "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity" : { "href" : "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` The `microdeposit` field contains the ID of the Microdeposit resource. ## Verifying the Microdeposit To verify the Microdeposit, send a PUT /payment_instruments/{id} request with the `verification_code` from the buyer's bank statement and `verify_microdeposits` set to `true`: ```shell Verify Microdeposits request curl https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ \ -X PUT \ -H "Content-Type: application/json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "verification_code": "FNX7Q2M", "verify_microdeposits": true }' ``` If the code matches, the Payment Instrument is enabled and is ready for payments: ```json Payment Instrument - verified { "id" : "PIkfiTDWYhQ4VbtQkC1U1ceJ", "created_at" : "2024-06-21T04:09:03.77Z", "updated_at" : "2024-06-21T04:09:03.77Z", "application" : "APgPDQrLD52TYvqazjHJJchM", "created_via" : "API", "currency" : "USD", "disabled_code" : null, "disabled_message" : null, "enabled" : true, "fingerprint" : "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity" : "IDpYDM7J9n57q849o9E9yNrG", "instrument_type" : "BANK_ACCOUNT", "account_type" : "BUSINESS_CHECKING", "bank_account_validation_check" : "NOT_ATTEMPTED", "bank_code" : "122105278", "country" : "USA", "institution_number" : null, "masked_account_number" : "XXXXXX0019", "name" : "Smith & Associates Consulting", "transit_number" : null, "tags" : { }, "third_party" : null, "third_party_token" : null, "type" : "BANK_ACCOUNT", "_links" : { "self" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ" }, "authorizations" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/authorizations" }, "transfers" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/transfers" }, "verifications" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/verifications" }, "application" : { "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity" : { "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG" } } } ``` ### Unsuccessful Microdeposit verification errors Unsuccessful Microdeposit verification requests return a `422` status with a message explaining the failure. ```json Example error response { "total": 1, "_embedded": { "errors": [ { "logref": "d4ee0b6cdb67686f0c1ec0780e5b4296", "message": "The microdeposit verification code provided is incorrect. 2 tries remaining.", "code": "INCORRECT_MICRODEPOSIT_VERIFICATION_CODE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ" } } } ] } } ``` One of the following errors are possible: | Scenario | Error Code | Message | | --- | --- | --- | | The code is incorrect and there are tries remaining. | `INCORRECT_MICRODEPOSIT_VERIFICATION_CODE` | The microdeposit verification code provided is incorrect. 2 tries remaining. | | The code is incorrect and there are no tries remaining. | `MICRODEPOSIT_VERIFICATION_ATTEMPTS_EXCEEDED` | Microdeposit verification has failed for this bank account. Please create a new bank account to try again. | | The 30-day verification window has passed. | `MICRODEPOSIT_VERIFICATION_EXPIRED` | The microdeposit verification window for this bank account has passed. Please create a new bank account to verify it again. | | The bank account is already verified. | `UNPROCESSABLE_ENTITY` | This payment instrument does not have a pending microdeposit verification. | | The Payment Instrument has no pending microdeposit. | `UNPROCESSABLE_ENTITY` | This payment instrument does not have a pending microdeposit verification. | | The `verification_code` is missing. | `INVALID_FIELD` | A microdeposit verification code is required. | A bank account pending Microdeposit verification can only be enabled by completing verification. Requests that set `enabled: true` will also return a `422` status code. ## Payment Instrument disabled code states The Payment Instrument's `disabled_code` explains the different verification states. | Disabled Code | Description | Next Step | | --- | --- | --- | | `MICRODEPOSIT_VERIFICATION_REQUIRED` | The bank account is pending microdeposit verification. | Submit the correct verification code to enable the bank account. | | `INVALID_BANK_ACCOUNT_ROUTING_NUMBER` | Bank account routing number was invalid. | Create a new bank account to start a new verification. | | `MICRODEPOSIT_VERIFICATION_ATTEMPTS_EXCEEDED` | Microdeposit verification has failed for this bank account. Please create a new bank account to try again. | Create a new bank account to start a new verification. | | `MICRODEPOSIT_VERIFICATION_EXPIRED` | The microdeposit verification window for this bank account has passed. Please create a new bank account to verify it again. | Create a new bank account to start a new verification. | | `MICRODEPOSIT_RETURNED` | A microdeposit for this bank account was returned and the account has been disabled. | Create a new bank account to start a new verification. | | `TOTAL_MICRODEPOSIT_ATTEMPTS_EXCEEDED_ACCOUNT_LOCKED` | This bank account has reached the maximum number of microdeposit verification attempts and cannot be re-verified. This account is now locked. | Please use a different bank account or payment method. | ### Attempt limits - **3 code submissions per Microdeposit:** After 3 incorrect submissions, the verification fails and a new bank account must be created. - **30 days per Microdeposit:** A Microdeposit that is not verified within 30 days expires. - **3 failed verifications per bank account:** After 3 failed verifications for the same bank account, the bank account is permanently blocked with `disabled_code: TOTAL_MICRODEPOSIT_ATTEMPTS_EXCEEDED_ACCOUNT_LOCKED` and cannot be verified again. ## Retrieving Microdeposits Retrieve a Microdeposit by sending a GET /microdeposits/{id} request to check its state, remaining tries, and expiration: ```json Microdeposit { "id" : "microdeposit_4ek6YXRKJ1fqvs5E4oHNcY", "created_at" : "2026-09-08T04:32:02.061298Z", "updated_at" : "2026-09-08T04:32:02.316872Z", "application" : "APc9vhYcPsRuTSpKD9KpMtPe", "currency" : "USD", "expires_at" : "2026-10-08T04:32:02.061306Z", "instrument" : "PItziwjPnE77zu1oWRKTzTdk", "rail" : "RTP", "state" : "PENDING", "verification_attempts" : 0, "verification_attempts_remaining" : 3, "_links" : { "self" : { "href" : "https://finix.sandbox-payments-api.com/microdeposits/microdeposit_4ek6YXRKJ1fqvs5E4oHNcY" }, "instrument" : { "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PItziwjPnE77zu1oWRKTzTdk" } } } ``` | Field | Description | | --- | --- | | `verification_attempts_remaining` | The number of Microdeposit verification attempts left. | | `expires_at` | When the 30-day verification window expires. | | `state` | The state of the Microdeposit. Starts as `PENDING`. Moves to `VERIFIED` when the buyer submits the correct code, or `FAILED` when all attempts are exhausted or the 30-day window expires. | | `verification_attempts` | The number of verification attempts made. | To check why the Microdeposit verification failed (`state: FAILED`): 1. Save the Payment Instrument ID from `_links.instrument`. 2. Send a GET /pament_instruments/{id} request, providing the ID in the path. 3. View the [Payment Instrument disabled_code and disabled_message](#payment-instrument-disabled-code-states). ## Testing in Sandbox To test Microdeposit verification in Sandbox, see [Testing microdeposit verifications](/additional-resources/developers/implementation-and-testing/testing-your-integration#testing-microdeposit-verifications).