Bank Account Validation Endpoint

Validate bank accounts in real time by using the Bank Account Validation Endpoint

POST 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*	string	application/json
X-Date*	string	ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*	string	Merchant X-Login Cashouts API Key
Authorization*	string	Authorization control hash

Request Body

Name	Type	Description
country*	String	Country of the bank account to validate
document*	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*	String	Bank account of the beneficiary
bank_account.branch	String	Bank branch of the beneficiary
bank_account.account_type	String	Bank account type of the beneficiary
bank_account*	Object[]	Object containing the details of the bank account to validate
amount	Numeric	Amount of the withdrawal
currency	String	Currency of the amount specified

204: No Content Success

{
    "description": "Valid account"
}

400: Bad Request Validation error

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

401: Unauthorized Invalid Credentials

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

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.

3. Specify the details required to validate the account in the body as JSON

This API must be activated on your account. Check with your Account Manager regarding the activation

Example Request

cURL

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" 
    }
}'

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
document	string (max length: 30)	Document of identity of the beneficiary	Valid document for the country of the deposit. See validations here
document_type	string (max length: 10)	Type of the document specified	Valid document type for the country of the deposit. See validations here
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
bank_account.bank_code	String (max length: 10)	Beneficiary's valid bank_code for the country. Use the Bank Codes Endpoint.	Valid bank code
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

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

Error Responses Example

// 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

Field	Format	Description
code	Integer	Error code. Click here to check all the possible error codes
type	String	Type of the error. Click here to check all the possible error types for refund
description	String	Human readable description of the error