Validate beneficiaries

curl --request POST \
  --url https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-date: <api-key>' \
  --header 'x-login: <api-key>' \
  --header 'x-trans-key: <api-key>' \
  --data '
{
  "country": "US",
  "type": "aba",
  "value": "026003780"
}
'

import requests

url = "https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary"

payload = {
    "country": "US",
    "type": "aba",
    "value": "026003780"
}
headers = {
    "x-login": "<api-key>",
    "x-trans-key": "<api-key>",
    "x-date": "<api-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-login': '<api-key>',
    'x-trans-key': '<api-key>',
    'x-date': '<api-key>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({country: 'US', type: 'aba', value: '026003780'})
};

fetch('https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country' => 'US',
    'type' => 'aba',
    'value' => '026003780'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "x-date: <api-key>",
    "x-login: <api-key>",
    "x-trans-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary"

	payload := strings.NewReader("{\n  \"country\": \"US\",\n  \"type\": \"aba\",\n  \"value\": \"026003780\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-login", "<api-key>")
	req.Header.Add("x-trans-key", "<api-key>")
	req.Header.Add("x-date", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary")
  .header("x-login", "<api-key>")
  .header("x-trans-key", "<api-key>")
  .header("x-date", "<api-key>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"US\",\n  \"type\": \"aba\",\n  \"value\": \"026003780\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-login"] = '<api-key>'
request["x-trans-key"] = '<api-key>'
request["x-date"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country\": \"US\",\n  \"type\": \"aba\",\n  \"value\": \"026003780\"\n}"

response = http.request(request)
puts response.read_body

{
  "exists": true,
  "owner_name": "Pedro Perez",
  "tax_id": 1030660402,
  "bank": "test@test.com"
}

Bank Payouts

Validate beneficiaries

Validate Beneficiary

This endpoint allows you to validate whether a beneficiary identifier is valid and eligible to receive a bank transfer through a specific country’s payment network.

Unlike the Get Beneficiary endpoint — which checks if a beneficiary exists in Vita — validate_beneficiary validates the identifier directly against the destination country’s banking or payment network.

The type parameter must correspond to a payment method supported in the specified country. The table below shows the valid combinations:

Country (`country`)	Identifier Type (`type`)	Description
Colombia (`CO`)	Bre-B Key (`breb`)	Identifier from Colombia’s Bre-B instant payment network (email, phone, ID, or alias).
Brazil (`BR`)	PIX (`pix`)	Brazilian PIX key (CPF, CNPJ, email, phone, or random key).
Argentina (`AR`)	CBU / CVU / Alias (`cvu_alias`)	Argentine CVU (22-digit account) or human-readable alias.
Mexico (`MX`)	CLABE (`clabe`)	Mexican standardized 18-digit interbank account number (CLABE).
European Union (`EU`)	IBAN (`iban`)	International Bank Account Number used across the EU and SEPA zone.
United States (`US`)	ABA Routing (`aba`)	US bank routing number (ABA) combined with account information.

Note: More countries and identifier types will be added over time. Always verify the current list before implementing new payout flows.

When to use it: Call this endpoint before creating a withdrawal whenever you’re using an identifier-based payment method (PIX, Bre-B, CVU, CLABE, IBAN, ABA).

Why Use This Endpoint

Prevent failed payouts: Validate the identifier before submitting the transaction.
Improve user experience: Catch typos and invalid identifiers at form-entry time, not after the payout fails.
Retrieve beneficiary information: When supported by the network, the response includes the recipient’s registered name and other details, useful for confirmation screens.

Request Body

The request must be sent as JSON (application/json).

Parameter	Type	Description
`country`	string (required)	ISO country code of the destination country (e.g., `CO`, `BR`, `MX`).
`type`	string (required)	Identifier type to validate (e.g., `pix`, `clabe`, `iban`). Must match a payment method supported in the specified country.
`value`	string (required)	The actual identifier to validate (e.g., an email address, CLABE number, IBAN, etc.).

Request Example

Validate a PIX key in Brazil

{"country":"BR","type":"pix","value":"user@example.com"}

Note: Brazilian PIX key (CPF, CNPJ, email, phone, or random key).

Validate a CLABE in Mexico

{"country":"MX","type":"clabe","value":"012345678901234567"}

Validate a Bre-B key in Colombia

{"country":"CO","type":"breb","value":"+573001234567"}

Response

Successful Validation

When the identifier is valid and the beneficiary can receive funds, the response returns the beneficiary’s details as retrieved from the destination network. The exact fields returned depend on the country and identifier type, but typically include:

Field	Description
`valid`	Boolean indicating whether the identifier is valid and active.
`beneficiary_name`	Registered name of the beneficiary at the destination network (when available).
`document_type`	Type of identification document linked to the identifier (when available).
`document_number`	Identification document number linked to the identifier (when available, often masked).
`bank_name`	Name of the financial institution holding the account (when available).
`account_type`	Type of account (e.g., checking, savings) when applicable.

Privacy notice: Some networks return masked or partial information (e.g., J*** D***, ***1234) for privacy and compliance reasons. The level of detail returned is determined by each country’s payment network, not by Vita Business.

Validation Failure

When the identifier is invalid, inactive, or cannot be found in the destination network, the API returns an error response describing the issue. The validation is informational only — it does not create any transaction or change state in Vita Business.

Common scenarios include:

Code	Scenario
`404`	Identifier not found in the destination network.
`400`	Invalid request — incorrect country/type combination or malformed `value`.
`422`	The identifier exists but is inactive or blocked at the destination network.

POST

api

businesses

beneficiaries

validate_beneficiary

Validate beneficiaries

curl --request POST \
  --url https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-date: <api-key>' \
  --header 'x-login: <api-key>' \
  --header 'x-trans-key: <api-key>' \
  --data '
{
  "country": "US",
  "type": "aba",
  "value": "026003780"
}
'

import requests

url = "https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary"

payload = {
    "country": "US",
    "type": "aba",
    "value": "026003780"
}
headers = {
    "x-login": "<api-key>",
    "x-trans-key": "<api-key>",
    "x-date": "<api-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-login': '<api-key>',
    'x-trans-key': '<api-key>',
    'x-date': '<api-key>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({country: 'US', type: 'aba', value: '026003780'})
};

fetch('https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country' => 'US',
    'type' => 'aba',
    'value' => '026003780'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "x-date: <api-key>",
    "x-login: <api-key>",
    "x-trans-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary"

	payload := strings.NewReader("{\n  \"country\": \"US\",\n  \"type\": \"aba\",\n  \"value\": \"026003780\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-login", "<api-key>")
	req.Header.Add("x-trans-key", "<api-key>")
	req.Header.Add("x-date", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary")
  .header("x-login", "<api-key>")
  .header("x-trans-key", "<api-key>")
  .header("x-date", "<api-key>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"US\",\n  \"type\": \"aba\",\n  \"value\": \"026003780\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/beneficiaries/validate_beneficiary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-login"] = '<api-key>'
request["x-trans-key"] = '<api-key>'
request["x-date"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country\": \"US\",\n  \"type\": \"aba\",\n  \"value\": \"026003780\"\n}"

response = http.request(request)
puts response.read_body

{
  "exists": true,
  "owner_name": "Pedro Perez",
  "tax_id": 1030660402,
  "bank": "test@test.com"
}

Authorizations

Business xLogin

x-trans-key

string

header

required

Business xTransKey

x-date

string

header

required

ISO8601 datetime

Authorization

string

header

required

V2-HMAC-SHA256 signature. Example: V2-HMAC-SHA256, Signature: <hash>

Body

application/json

The body is of type object.

Response

200 - application/json

Successful response.

Payins

Exchange

Payouts

Transactions

Users

Webhooks

Validate beneficiaries

Validate Beneficiary

Why Use This Endpoint

Request Body

Request Example

Validate a PIX key in Brazil

Validate a CLABE in Mexico

Validate a Bre-B key in Colombia

Response

Successful Validation

Validation Failure

Authorizations

Body

Response