Bank Account Verification API

With Veem Bank Account Verification API you can confirm that a user has access to a bank account linked to their Veem account using Micro-Deposits and that the account is whitelisted for debits using Micro-Debit.

Use the following headers on all API endpoints.

📘

Headers

Three headers are required to use this endpoint.

Required Headers

     <th style={{ textAlign: "left" }}>
       Type
     </th>

     <th style={{ textAlign: "left" }}>
       Required
     </th>

     <th style={{ textAlign: "left" }}>
       Description
     </th>
   </tr>
 </thead>

 <tbody>
   <tr>
     <td style={{ textAlign: "left" }}>
       `Authorization`
     </td>

     <td style={{ textAlign: "left" }}>
       `string`
     </td>

     <td style={{ textAlign: "left" }}>
       Yes
     </td>

     <td style={{ textAlign: "left" }}>
       Bearer token (OAuth 2.0)
       This header holds the bearer token required to use Veem's public API, and **belongs to the owner account**. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows:
       `Bearer c047594b-082c-4da1-be89-08fe3770f4b3`

       See [Get Access Token section](https://developer.veem.com/docs/oauth#1---get-access-token)  to generate your Bearer token
     </td>
   </tr>

   <tr>
     <td style={{ textAlign: "left" }}>
       `X-Request-Id`
     </td>

     <td style={{ textAlign: "left" }}>
       `string`
     </td>

     <td style={{ textAlign: "left" }}>
       Yes
     </td>

     <td style={{ textAlign: "left" }}>
       This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows:\
       `48855846-628d-4177-b071-80332a116f0a`
     </td>
   </tr>

   <tr>
     <td style={{ textAlign: "left" }}>
       `Content-Type`
     </td>

     <td style={{ textAlign: "left" }}>
       `string`
     </td>

     <td style={{ textAlign: "left" }}>
       Yes
     </td>

     <td style={{ textAlign: "left" }}>
       The content type of the request. Must be `application/json`
     </td>
   </tr>
 </tbody>

Create Bank Account Verification: Trigger Micro-Deposit

POST /veem/v1.2/bank-account-verification

Starts a new bank-account verification lifecycle for the specified customer bank funding method.

This endpoint:

Creates the bank verification resource
Starts the micro-deposit process

Request Example

{
  "onBehalfAccountId": 456, // see Partner Notes
  "fundingMethod": {
    "id": 2393,
    "type": "Bank"
  }
}

Request Parameters

Field	Type	Required	Description
fundingMethod.id	integer	Yes	Funding method ID
fundingMethod.type	string	Yes	Funding method type

Response Example

{
  "verificationId": 98765,
  "fundingMethodId": 2393,
  "fundingMethodType": "BANK",
  "microDepositStatus": "REQUESTED",
  "microDepositReasons": [
    "test 4",
    "test 4"
  ],
  "microDebitStatus": null,
  "microDebitReasons": null,
  "verificationAttemptsCount": 1,
  "microDepositConfirmationAttemptsCount": 0,
  "microDebitAttemptsCount": 0,
  "microDepositExpiresAt": 1781277814000
}

👍
Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional parameter, this needs to be included on the request body in case of partner making an API request on behalf of their customer. This is the customer Veem account ID.

Get Bank Account Verification

GET /veem/v1.2/bank-account-verification/{verificationId}?onBehalfAccountId=456

Use this endpoint to determine whether micro-deposit or micro-debit steps are pending, passed, or failed. Returns the current state of a single verification resource.

Response Example

{
  "verificationId": 98765,
  "fundingMethodId": 2393,
  "fundingMethodType": "BANK",
  "microDepositStatus": "PASSED",
  "microDepositReasons": null,
  "microDebitStatus": "REQUESTED",
  "microDebitReasons": null,
  "verificationAttemptsCount": 1,
  "microDepositConfirmationAttemptsCount": 0,
  "microDebitAttemptsCount": 0,
  "microDepositExpiresAt": 1781277814000
}

👍
Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional query string parameter, this needs to be included in the request URL in case of partner making an API request on behalf of their customer. This is the customer Veem accountId.

List Bank Account Verifications

GET /veem/v1.2/bank-account-verification?onBehalfAccountId=456&fundingMethodId=2393

Returns all verification resources associated with a specific customer and funding method pairing.

Query Parameters

Parameter	Required	Description
onBehalfAccountId	No	Customer identifier
fundingMethodId	Yes	Funding method identifier

👍
Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional query string parameter, this needs to be included in the request URL in case of partner making an API request on behalf of their customer. This is the customer Veem accountId.

Response Example

[
  {
    "verificationId": 98765,
    "fundingMethodId": 2393,
    "fundingMethodType": "BANK",
    "microDepositStatus": "PASSED",
    "microDepositReasons": null,
    "microDebitStatus": "SENT",
    "microDebitReasons": null,
    "verificationAttemptsCount": 2,
    "microDepositConfirmationAttemptsCount": 1,
    "microDebitAttemptsCount": 0,
    "microDepositExpiresAt": 1781277814000,
    "timeCreated": 1781277814000
  }
]

Confirm Micro-Deposit Amounts

POST /veem/v1.2/bank-account-verification/{verificationId}/confirm-deposit

Submits the two micro-deposit amounts provided by the customer.

This endpoint:

Validates previously sent micro-deposits
Records failed attempts
Advances the verification lifecycle

Validation Rules

Amount order does not matter
On mismatch:
- microDepositStatus = FAILED
- Attempt count increments
On fifth mismatch:
- microDepositStatus = LOCKED
If expired:
- microDepositStatus = EXPIRED

Request Example

{
  "amounts": [
    {
      "number": 0.17,
      "currency": "USD"
    },
    {
      "number": 0.14,
      "currency": "USD"
    }
  ],
	"onBehalfAccountId": 456 // see Partner Notes
}

👍
Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional parameter, this needs to be included on the request body in case of partner making an API request on behalf of their customer. This is the customer Veem account ID.

Response Example

{
  "verificationId": 158,
  "fundingMethodId": 2393,
  "microDepositStatus": "PASSED",
  "microDepositReason": null,
  "microDebitStatus": null,
  "microDebitReason": null,
  "verificationAttemptNumber": 1,
  "microDepositConfirmationAttemptCount": 1,
  "microDebitAttemptsCount": 0,
  "expiresAt": 1781277814000
}

Trigger Micro-Debit

POST /veem/v1.2/bank-account-verification/{verificationId}/micro-debit

Starts the optional micro-debit verification step after successful micro-deposit confirmation.

{
  "onBehalfAccountId": 456 // see Partner Notes
}

👍
Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional parameter, this needs to be included on the request body in case of partner making an API request on behalf of their customer. This is the customer Veem account ID.

Response Example

{
  "verificationId": 158,
  "fundingMethodId": 2393,
  "microDepositStatus": "PASSED",
  "microDepositReason": null,
  "microDebitStatus": "REQUESTED",
  "microDebitReason": null,
  "verificationAttemptNumber": 1,
  "microDepositConfirmationAttemptCount": 1,
  "microDebitAttemptsCount": 1,
  "microDepositExpiresAt": 1781277814000
}

Override Negative Result

POST /veem/v1.2/bank-account-verification/{verificationId}/override

Applies a manual override to a failed or blocked verification result.

This endpoint is intended for exception handling after external review.

Request Example

{
  "note": "test 4",
  "targetStatus": "PASSED",
  "type": "DEPOSIT",
	"onBehalfAccountId": 456 // see Partner Notes
}

👍
Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional parameter, this needs to be included on the request body in case of partner making an API request on behalf of their customer. This is the customer Veem account ID.

Response Example

{
  "verificationId": 98765,
  "fundingMethodId": 2393,
  "microDepositStatus": "PASSED",
  "microDepositReasons": null,
  "microDebitStatus": null,
  "microDebitReasons": null,
  "verificationAttemptsCount": 1,
  "microDepositConfirmationAttemptsCount": 5,
  "microDebitAttemptsCount": 0,
  "microDepositExpiresAt": 1781277814000
}

Supported Type Values

DEPOSIT
DEBIT

Status Values

microDepositStatus and microDebitStatus are returned as strings.

Possible Statuses

REQUESTED
SENT
PASSED
FAILED
LOCKED
EXPIRED

Reason Fields

Field	Description
`microDepositReason`	List of plain text reasons
`microDebitReason`	List of plain text reasons

Limits

Maximum 5 bank account verification attempts per funding method
Maximum 5 micro-deposit confirmation attempts per verification
Maximum 5 micro-debit attempts per verification

Webhooks

Verification updates use the BANK_ACCOUNT_VERIFICATION_UPDATED event.

Partners should subscribe to this event.

Example Payload

{
  "eventType": "BANK_ACCOUNT_VERIFICATION_UPDATED",
  "bankAccountVerificationId": 98765,
  "fundingMethodId": 2393,
  "microDepositStatus": "FAILED",
  "microDepositReason": "Amounts do not match",
  "microDebitStatus": null,
  "microDebitReason": null,
  "verificationAttemptNumber": 1,
  "microDepositConfirmationAttemptCount": 3,
  "microDebitAttemptsCount": 0,
  "expiresAt": 1781277814000
}