> ## Documentation Index > Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json {"country":"BR","type":"pix","value":"user@example.com"} ``` > **Note:** Brazilian PIX key (CPF, CNPJ, email, phone, or random key). ##### Validate a CLABE in Mexico ```json {"country":"MX","type":"clabe","value":"012345678901234567"} ``` ##### Validate a Bre-B key in Colombia ```json {"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. | ## OpenAPI ````yaml /openapi.yaml post /api/businesses/beneficiaries/validate_beneficiary openapi: 3.0.0 info: title: Vita Business API description: >- Vita Wallet Business API — integra payins, payouts, exchange, transactions, users y webhooks para operar pagos en LatAm y el mundo. version: 1.0.0 contact: name: Vita Wallet Support url: https://vitawallet.io email: empresas@vitawallet.io servers: - url: https://api.vitawallet.io description: Production - url: https://api.stage.vitawallet.io description: Sandbox security: - xLogin: [] xTransKey: [] xDate: [] hmacSignature: [] tags: - name: Create Payin - name: Direct Payment - name: Exchange - name: Vita Sent - name: Bank Payouts - name: External Crypto Payouts - name: Transactions - name: Users Creation - name: User Information - name: Webhooks externalDocs: url: https://vitawallet.io description: Vita Wallet paths: /api/businesses/beneficiaries/validate_beneficiary: post: tags: - Bank Payouts summary: Validate beneficiaries description: >- #### 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 ```json {"country":"BR","type":"pix","value":"user@example.com"} ``` > **Note:** Brazilian PIX key (CPF, CNPJ, email, phone, or random key). ##### Validate a CLABE in Mexico ```json {"country":"MX","type":"clabe","value":"012345678901234567"} ``` ##### Validate a Bre-B key in Colombia ```json {"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. | operationId: validate-beneficiaries requestBody: content: application/json: schema: type: object example: country: US type: aba value: '026003780' responses: '200': description: Successful response. content: application/json: examples: CoBreb: summary: CO - BreB value: exists: true owner_name: Pedro Perez tax_id: 1030660402 bank: test@test.com ArCbuCvuAlias: summary: AR - CBU/CVU/Alias value: exists: true owner_name: Pedro Perez tax_id: 1030660402 bank: test@test.com BrPix: summary: BR - PIX value: exists: true owner_name: Pedro Perez tax_id: 1030660402 bank: test@test.com UsAba: summary: US - ABA value: exists: true owner_name: null tax_id: null bank: DEUTSCHE BANK, A.G. MxClabe: summary: MX - CLABE value: exists: true owner_name: null tax_id: null bank: HSBC México EuIban: summary: EU - IBAN value: exists: true owner_name: null tax_id: null bank: NATIONAL WESTMINSTER BANK PLC ErrorNotFound: summary: 'ERROR: not found' value: exists: false components: securitySchemes: xLogin: type: apiKey in: header name: x-login description: Business xLogin xTransKey: type: apiKey in: header name: x-trans-key description: Business xTransKey xDate: type: apiKey in: header name: x-date description: ISO8601 datetime hmacSignature: type: apiKey in: header name: Authorization description: 'V2-HMAC-SHA256 signature. Example: `V2-HMAC-SHA256, Signature: `' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.