Microdeposit verification
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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 (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 are already verified and do not require Microdeposit verification.

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.
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).
The buyer finds the code on their bank statement and submits it as the verification_code.
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:

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:

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:

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.

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:

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):

Save the Payment Instrument ID from _links.instrument.
Send a GET /pament_instruments/{id} request, providing the ID in the path.
View the Payment Instrument disabled_code and disabled_message.

Testing in Sandbox

To test Microdeposit verification in Sandbox, see Testing microdeposit verifications.

Microdeposit verificationCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code