Get beneficiary

curl --request POST \
  --url https://api.vitawallet.io/api/businesses/beneficiaries/get_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 '
{
  "document_number": "1111111111",
  "document_type": "RUT",
  "country_iso_code": "CL"
}
'

import requests

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

payload = {
    "document_number": "1111111111",
    "document_type": "RUT",
    "country_iso_code": "CL"
}
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({document_number: '1111111111', document_type: 'RUT', country_iso_code: 'CL'})
};

fetch('https://api.vitawallet.io/api/businesses/beneficiaries/get_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/get_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([
    'document_number' => '1111111111',
    'document_type' => 'RUT',
    'country_iso_code' => 'CL'
  ]),
  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/get_beneficiary"

	payload := strings.NewReader("{\n  \"document_number\": \"1111111111\",\n  \"document_type\": \"RUT\",\n  \"country_iso_code\": \"CL\"\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/get_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  \"document_number\": \"1111111111\",\n  \"document_type\": \"RUT\",\n  \"country_iso_code\": \"CL\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/beneficiaries/get_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  \"document_number\": \"1111111111\",\n  \"document_type\": \"RUT\",\n  \"country_iso_code\": \"CL\"\n}"

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

{
  "beneficiary": {
    "id": 1,
    "type": "beneficiary",
    "attributes": {
      "first_name": "Jhon",
      "last_name": "Doe",
      "company_name": null,
      "beneficiary_type": null,
      "document_type": "RUT",
      "document_number": 1111111111,
      "country_iso_code": "CL",
      "status": "active",
      "is_received": true
    }
  }
}

Bank Payouts

Get beneficiary

This endpoint allows you to check whether a beneficiary is registered in Vita and able to receive funds through a withdrawal in a specific country. It’s typically used as a pre-flight check before creating a withdrawal — letting you verify the recipient’s eligibility, retrieve their existing information, and improve the user experience by avoiding failed transactions.

If the beneficiary exists, the endpoint returns their full profile (name, document, status). If they don’t exist yet, you can still proceed with the withdrawal — Vita will automatically create the beneficiary using the information provided in the withdrawal request.

Note: Don’t worry if the beneficiary is not found. Submit the withdrawal directly and the beneficiary will be created on the fly from the data you provide.

Why Use This Endpoint

Validate recipient eligibility before initiating a withdrawal.
Retrieve known beneficiary data to pre-fill fields and reduce user input errors.
Confirm the beneficiary’s status (e.g., active vs. blocked) before sending funds.

Request Structure

Key	Description	Required
`document_number`	Beneficiary’s identification document number.	Required
`country_iso_code`	ISO country code of the beneficiary’s country (e.g., `CL`, `CO`, `US`).	Required
`document_type`	Type of identification document (e.g., `RUT`, `CC`, `CURP`, `SSN, CPF`).	Conditional — is required when the country does not require `beneficiary_type`, or the `beneficiary_type` is set to `Individual`.
`beneficiary_type`	Type of beneficiary, e.g., `Individual` or `Business`.	Conditional — Is required only when the destination country mandates it (e.g., the United States).

Request Example

{
  "document_number": "1111111111",
  "document_type": "RUT",
  "country_iso_code": "CL"
}

Response Structure

When the beneficiary is found, the API returns the beneficiary’s full profile inside a beneficiary object.

Response Example

{
  "beneficiary": {
    "id": 1,
    "type": "beneficiary",
    "attributes": {
      "first_name": "Jhon",
      "last_name": "Doe",
      "company_name": null,
      "beneficiary_type": null,
      "document_type": "RUT",
      "document_number": "1111111111",
      "country_iso_code": "CL",
      "status": "active",
      "is_received": true
    }
  }
}

Response Fields

Field	Description
`id`	Unique identifier of the beneficiary in Vita Business.
`type`	Resource type — always `"beneficiary"`.
`attributes.first_name`	First name of the beneficiary (for individuals).
`attributes.last_name`	Last name of the beneficiary (for individuals).
`attributes.company_name`	Legal name of the beneficiary (for businesses). `null` for individuals.
`attributes.beneficiary_type`	Beneficiary classification (`Individual`, `Business`, or `null` if not applicable to the country).
`attributes.document_type`	Type of identification document on file.
`attributes.document_number`	Identification document number on file.
`attributes.country_iso_code`	ISO country code of the beneficiary’s country.
`attributes.status`	Current status of the beneficiary (e.g., `active`, `banned`).
`attributes.is_received`	Indicates whether the beneficiary has previously received funds through your account. Useful for distinguishing recurring vs. first-time recipients.

Important Considerations

Beneficiary Not Found Is Not an Error

If the beneficiary doesn’t exist in Vita, this is not a failure condition. You can still proceed with the withdrawal, and Vita will create the beneficiary automatically using the information sent in the withdrawal request.

Country-Specific Field Requirements

Always verify which fields are required for the destination country. Calling GET /api/businesses/withdrawal_rules is the recommended way to confirm country-specific requirements before submitting this request.

Status Validation

Even if a beneficiary exists, check the `status` field. A beneficiary marked as `blocked` or `inactive` will not be able to receive funds, and the withdrawal will fail.

Recurring Beneficiaries

The `is_received` field indicates whether this beneficiary has previously received funds from your account. Use it to differentiate between new and recurring recipients in your UI or reporting.

POST

api

businesses

beneficiaries

get_beneficiary

Get beneficiary

curl --request POST \
  --url https://api.vitawallet.io/api/businesses/beneficiaries/get_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 '
{
  "document_number": "1111111111",
  "document_type": "RUT",
  "country_iso_code": "CL"
}
'

import requests

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

payload = {
    "document_number": "1111111111",
    "document_type": "RUT",
    "country_iso_code": "CL"
}
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({document_number: '1111111111', document_type: 'RUT', country_iso_code: 'CL'})
};

fetch('https://api.vitawallet.io/api/businesses/beneficiaries/get_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/get_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([
    'document_number' => '1111111111',
    'document_type' => 'RUT',
    'country_iso_code' => 'CL'
  ]),
  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/get_beneficiary"

	payload := strings.NewReader("{\n  \"document_number\": \"1111111111\",\n  \"document_type\": \"RUT\",\n  \"country_iso_code\": \"CL\"\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/get_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  \"document_number\": \"1111111111\",\n  \"document_type\": \"RUT\",\n  \"country_iso_code\": \"CL\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/beneficiaries/get_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  \"document_number\": \"1111111111\",\n  \"document_type\": \"RUT\",\n  \"country_iso_code\": \"CL\"\n}"

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

{
  "beneficiary": {
    "id": 1,
    "type": "beneficiary",
    "attributes": {
      "first_name": "Jhon",
      "last_name": "Doe",
      "company_name": null,
      "beneficiary_type": null,
      "document_type": "RUT",
      "document_number": 1111111111,
      "country_iso_code": "CL",
      "status": "active",
      "is_received": true
    }
  }
}

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

Get beneficiary

Why Use This Endpoint

Request Structure

Request Example

Response Structure

Response Example

Response Fields

Important Considerations

Beneficiary Not Found Is Not an Error

Country-Specific Field Requirements

Status Validation

Recurring Beneficiaries

Authorizations

Body

Response