---
title: "Validate a bank account"
method: POST
path: "/payout/account/validate/{user_token}"
tags: ["Account"]
---

# Validate a bank account

`POST /payout/account/validate/{user_token}`

## Request

- Base URL: `https://api.masspay.io/v1.0.0`
- URL: `https://api.masspay.io/v1.0.0/payout/account/validate/{user_token}`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/masspay/apis/masspay-api/docs/payout/account/validate/:user_token/post.ts> (a function with typed inputs; its response is checked against the schema)

This **POST** endpoint is used to validate a bank account against MassPay's account verification providers, independently of a payout. <br>
The bank account is validated for the user identified by `user_token` in the path, and the account holder name on record for that user is used for name matching. <br>
If a finalized result is available within ~5 seconds (including cached results), it is returned synchronously with HTTP `200`. Otherwise HTTP `202` is returned with a status of `PROCESSING` and the finalized result is delivered asynchronously through the `avs.completed` webhook event. <br>
Validations are charged per validation based on your client pricing configuration; validations that cannot be verified by any provider (`UNSUPPORTED`) are not charged.

## Path parameters

- `user_token` string, required

## Request body

- ValidateBankAccountRequest: Bank account details to validate. The user is identified by the `user_token` path parameter.
  - `country_code` string: ISO alpha-2 country code of the bank account.
  - `attrs` AccountValidationAttribute[], required: Bank account attributes to validate. `BankAccountNumber` is required.
    - `type` 'BankAccountNumber' | 'BankRoutingNumber' | 'SWIFT' | 'BankAccountType' | 'IdentificationNumber' | 'IdentificationType', required: Attribute type.
    - `value` string, required: Value of the attribute.

## Response `200`

Finalized validation result.

- ValidationResult: Finalized account validation result.
  - `status` 'MATCH' | 'CLOSE_MATCH' | 'NO_MATCH' | 'UNSUPPORTED': Finalized validation status. - `MATCH`: the account exists and the account holder name matches the user on record. - `CLOSE_MATCH`: the account exists and the account holder name is a partial match. - `NO_MATCH`: the account holder name does not match the user on record. - `UNSUPPORTED`: no provider was able to verify this account. Not charged.
  - `ownership_verified` boolean: Whether account ownership was verified by the provider.
  - `first_name_match` string, nullable: First name match outcome, when returned by the validating provider.
  - `last_name_match` string, nullable: Last name match outcome, when returned by the validating provider.
  - `match_score` integer, nullable: Name match score (0-100) when provided by the validating provider.
  - `score_value` integer, nullable: Provider-specific risk score, when returned.
  - `score_rag` string, nullable: Provider-specific red/amber/green rating for the score, when returned.
  - `score_description` string, nullable: Human readable explanation of the provider score, when returned.

## Other responses

- `202`: Validation is still processing. The finalized result will be delivered via the `avs.completed` webhook event.
- `400`: Invalid request. Returned when `attrs` is missing, the `BankAccountNumber` attribute is not supplied, or `user_token` does not reference an existing user.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not found.
- `405`: Method Not Allowed.
- `500`: Internal server error.
- `504`: Gateway Time-out.

## Changes

- **2026-11-03** `f9fa41b7c45c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/payout/account/validate/:user_token/post.md)

---

[API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)