# Bank Account Validation Endpoint

<mark style="color:green;">`POST`</mark> `https://api-stg.onekeypayments.com/v5/account/validate`

This endpoint allows you to validate if a bank account is valid, if it exists and if it can receive funds

#### Headers

| Name                                            | Type   | Description                                              |
| ----------------------------------------------- | ------ | -------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json`                                       |
| X-Date<mark style="color:red;">\*</mark>        | string | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` |
| X-Login<mark style="color:red;">\*</mark>       | string | Merchant X-Login Cashouts API Key                        |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization control hash                               |

#### Request Body

| Name                                                          | Type      | Description                                                   |
| ------------------------------------------------------------- | --------- | ------------------------------------------------------------- |
| country<mark style="color:red;">\*</mark>                     | String    | Country of the bank account to validate                       |
| document<mark style="color:red;">\*</mark>                    | String    | Document of identity of the beneficiary                       |
| document\_type\*                                              | String    | Type of the document specified                                |
| first\_name                                                   | String    | First name of the beneficiary                                 |
| last\_name                                                    | String    | Last name of the beneficiary                                  |
| bank\_account.bank\_code                                      | Numeric   | Code of the bank of the beneficiary                           |
| bank\_account.account<mark style="color:red;">\*</mark>       | String    | Bank account of the beneficiary                               |
| bank\_account.branch                                          | String    | Bank branch of the beneficiary                                |
| bank\_account.account\_type<mark style="color:red;">\*</mark> | String    | Bank account type of the beneficiary                          |
| bank\_account<mark style="color:red;">\*</mark>               | Object\[] | Object containing the details of the bank account to validate |
| amount                                                        | Numeric   | Amount of the withdrawal                                      |
| currency                                                      | String    | Currency of the amount specified                              |

{% tabs %}
{% tab title="204: No Content Success" %}

```java
{
    "description": "Valid account"
}
```

{% endtab %}

{% tab title="400: Bad Request Validation error" %}

```java
{
    "code": 300,
    "description": "Invalid document number",
    "type": "INVALID_DOCUMENT"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid Credentials" %}

```java
{
    "code": 100,
    "description": "Invalid Credentials",
    "type": "INVALID_CREDENTIALS"
}
```

{% endtab %}
{% endtabs %}

## Description

This endpoint allows you to validate not only if the details of the beneficiary are correct according to the validations performed by the banks, but also to validate if the account exists in the bank and if it can receive funds.

Validations performed:

1. The bank account, branch and type are valid
2. The account exists in the bank
3. The bank account belongs to the beneficiary details indicated (Document, name, etc)
4. The amount specified is within the minimum and maximum limits (optional, only performed if `amount` is sent)
5. The account can receive funds (it's not blocked, closed, etc)

If all these checks pass, we can be sure that the account is valid and that a Withdrawal created with those details will be fulfilled successfully.

In order to start using this API, you need to:

1. Send the request with **POST** method.
2. Use the headers described [here](https://apidocs.onekeypayments.com/api-documentation/bank-account-validation/technical-and-security-aspects).
3. Specify the details required to validate the account in the body as JSON

{% hint style="success" %}
This API must be activated on your account. Check with your Account Manager regarding the activation
{% endhint %}

## Example Request

{% tabs %}
{% tab title="cURL" %}

```java
curl --location --request POST 'https://api-stg.directa24.com/v5/account/validate' \
--header 'X-Login: cashouts_api_key' \
--header 'X-Date: 2022-01-01T19:00:06Z' \
--header 'Authorization: D24 520ec3e5e2d8f8c2fc66948bc87984a2ff8dec0fe25d13781272f0ae94665c3c' \
--header 'Content-Type: application/json' \
--data-raw '{
    "country": "BR",
    "document": "84932568207",
    "document_type": "CPF",
    "first_name": "Ricardo",
    "last_name": "Carlos",
    "amount": 100,
    "currency": "BRL",
    "bank_account": {
        "bank_code": 100,
        "account": "123456-7",
        "branch": "6789-X",
        "account_type": "S" 
    }
}'

```

{% endtab %}
{% endtabs %}

### Request fields description

| Field                       | Format                    | Description                                                                                                                                                                     |                                                                                  Validations                                                                                  |
| --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `country`                   | string (length: 2)        | Country code of the deposit in *ISO 3166-1 alpha-2 code* format                                                                                                                 |                              [Country codes](https://apidocs.onekeypayments.com/knowledge-base/countries-specifications#countries-and-currencies)                             |
| `document`                  | string (max length: 30)   | Document of identity of the beneficiary                                                                                                                                         |    <p>Valid document for the country of the deposit.</p><p><a href="../../../../knowledge-base/countries-specifications#documents-validations">See validations here</a></p>   |
| `document_type`             | string (max length: 10)   | Type of the document specified                                                                                                                                                  | <p>Valid document type for the country of the deposit.</p><p><a href="../../../../knowledge-base/countries-specifications#documents-validations">See validations here</a></p> |
| `first_name`                | String (max length: 255)  | First name of the beneficiary                                                                                                                                                   |                                                                         String of up to 255 characters                                                                        |
| `last_name`                 | String (max length: 255)  | Last name of the beneficiary                                                                                                                                                    |                                                                         String of up to 255 characters                                                                        |
| `amount`                    | decimal (max decimals: 2) | Amount to validate                                                                                                                                                              |                                                                                                                                                                               |
| `currency`                  | string (length: 3)        | Currency code of the amount in *ISO 4217* format. Default is `USD`                                                                                                              |                             Valid [currency](https://apidocs.onekeypayments.com/knowledge-base/countries-specifications#countries-and-currencies)                             |
| `bank_account.bank_code`    | String (max length: 10)   | Beneficiary's valid `bank_code` for the country. Use the [Bank Codes Endpoint.](https://apidocs.onekeypayments.com/api-documentation/cashouts-api/endpoints/cashout-bank-codes) |                               Valid [bank code](https://apidocs.onekeypayments.com/api-documentation/cashouts-api/endpoints/cashout-bank-codes)                               |
| `bank_account.account`      | String (max length: 45)   | Bank account of the beneficiary                                                                                                                                                 |                                                                         String of up to 45 characters                                                                         |
| `bank_account.branch`       | String (max length: 45)   | Bank branch of the beneficiary                                                                                                                                                  |                                                                         String of up to 45 characters                                                                         |
| `bank_account.account_type` | Array                     | Beneficiary's account type                                                                                                                                                      |                                                                                                                                                                               |

## Example Responses

### Success Example&#x20;

In case the bank account passed all the validations, an HTTP 204 status code will be returned.

### Error Responses Example

```java
// The document informed didn't pass our validations
{
    "code": 300,
    "description": "Invalid document number",
    "type": "INVALID_DOCUMENT"
}

// The API Key used is incorrect
{
    "code": 100,
    "description": "Invalid Credentials",
    "type": "INVALID_CREDENTIALS"
}

// The bank account is invalid
{
    "code": 302,
    "description": "Invalid bank account",
    "type": "INVALID_BANK_ACCOUNT"
}

```

### Error Responses Fields

<table><thead><tr><th>Field</th><th width="239.33333333333331">Format</th><th>Description</th></tr></thead><tbody><tr><td><code>code</code></td><td>Integer</td><td>Error code. <a href="broken-reference">Click here to check all the possible error codes</a></td></tr><tr><td><code>type</code></td><td>String</td><td>Type of the error. <a href="broken-reference">Click here to check all the possible error types for refund</a></td></tr><tr><td><code>description</code></td><td>String</td><td>Human readable description of the error</td></tr></tbody></table>

�