Docs
ES

What is a beneficiary?

In Veriko, we call a "beneficiary" any bank account that receives SPEI transfers. Beneficiaries may or may not be saved in Veriko. Although saving them is very useful, it has three concrete effects:

  1. Auto-fills the bank on future validations.
  2. Helps image-based validations (OCR) identify the cuenta_beneficiaria when it is masked or incomplete (common on some receipts).
  3. Enables the account statements in Finance and improves organization.

The three beneficiary types

The account_type (beneficiary account type) is detected from the number of digits:

  • clabe — 18 digits. The bank is detected and derived automatically. Does not require bank_code in the body.
  • card — 16 digits. The bank is detected and derived automatically. Does not require bank_code.
  • phone — exactly 10 digits. A mobile number linked to a bank account. It does require bank_code, and it is mandatory in the body because no public phone→bank mapping exists; the endpoint responds 422 bank_code_required_for_phone when bank_code is missing.

Beneficiaries and image-based validations (OCR)

When you call POST /v1/validate-ocr, the "beneficiary account" in the image may come incomplete or in the shape "••••5678" or "4111 •••• •••• 1111" (common on receipts from some banks); Veriko's lookup system uses the last visible digits and runs a search in this order:

  1. The request's cuenta_beneficiaria parameter (not recommended): Provide the full receiving account of the transfer; the account extracted from the image will be ignored and the validation will use the one you specified.
  2. User allow-list: Filters the user's active beneficiaries based on the digits obtained from the image in relation to the receiving (beneficiary) account.

Without registered beneficiaries a masked receipt may stay ambiguous and fail to resolve. That is why it is advisable to register the accounts in which you frequently receive payments.

Create and manage beneficiaries