https://api.veriko.mx/v1/beneficiariesCrear un beneficiario
Guía de uso →Registra una cuenta beneficiaria nueva. El tipo de cuenta se autodetecta por la longitud, y de eso depende qué campos se envían en la petición:
- CLABE (18 dígitos):
bank_codees opcional, se deriva del prefijo. - Tarjeta (16 dígitos):
bank_codees opcional, se deriva del BIN. - Celular/DiMo (10 dígitos):
bank_codees obligatorio en el cuerpo, ya que el número por sí solo no identifica a la institución bancaria.
Si la cuenta a registrar no existe previamente, se registra y responde con un estado HTTP 201.
Si se intenta registrar una cuenta activa, responde con un estado HTTP 422 (con beneficiary_already_registered en el cuerpo).
Si existe pero está archivada, el alta la reactiva y responde con un estado HTTP 200 (con meta.reactivated=true en el cuerpo). Si la petición no trae label, la reactivación conserva el alias que la cuenta ya tenía; si lo trae, lo reemplaza.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
account_number | string (patrón) | obligatorio | Número de cuenta. Se aceptan: CLABE (18 dígitos), tarjeta (16 dígitos) o celular/DiMo (10 dígitos). Los separadores, espacios y guiones se eliminan. p. ej.012180004412345678 |
bank_code | string (patrón) | opcional | Código SPEI (4 o 5 dígitos). Obligatorio cuando el tipo detectado es 40012 |
label | string (?–100) | opcional | Etiqueta opcional con la que la cuenta se identifica en la lista de beneficiarios. p. ej.Proveedor ABC |
curl -X POST 'https://api.veriko.mx/v1/beneficiaries' \
-H 'Authorization: Bearer veriko_••••' \
-H 'Content-Type: application/json' \
-d '{
"account_number": "4111111111111111",
"label": "Tarjeta BBVA nómina"
}'Ejemplo en Python — próximamente.
Ejemplo en JavaScript — próximamente.
Ejemplo en PHP — próximamente.
| Campo | Tipo | Descripción |
|---|---|---|
data | object | Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con |
type* | string | Tipo de recurso JSON:API. Siempre beneficiary |
id* | string | Identificador numérico del beneficiario en el sistema. p. ej.42 |
attributes* | object | Datos canónicos del beneficiario: los de la cuenta y los del registro. |
account_number* | string | Número de cuenta almacenado: CLABE (18 dígitos), tarjeta (16 dígitos) o celular/DiMo (10 dígitos). Use 012180004412345678 |
account_type* | string | Tipo de cuenta: clabe |
bank_code* | string | Código SPEI (5 dígitos) del banco resuelto. Es la cadena vacía ( 40012 |
bank_name* | string | Nombre oficial del banco, resuelto a partir de su BBVA MEXICO |
label | string | nullanulable | Etiqueta descriptiva libre del usuario. Proveedor ABC |
status* | string | Estado del beneficiario. active |
created_at* | string (date-time) | Fecha y hora, en ISO 8601 UTC, de creación. p. ej.2026-01-15T10:00:00Z |
meta | object | Metadatos de la respuesta, incluyendo versión de la API, prefijo de ruta, identificador único de la petición y marca temporal del servidor en UTC. |
version | string | Versión de la API que procesó la petición. p. ej.1.47.0 |
api_version | string | Versión del prefijo de ruta de la API (ej. v1 |
request_id | string | Identificador único de la petición (hex). p. ej.a1b2c3d4e5f66f5e4d3c2b1a |
datetime | object | Descriptor compañero presente en el bloque {"timezone":"UTC","format":"ISO 8601"} |
timezone* | string | Siempre UTC |
format* | string | Siempre ISO 8601 |
links | object | Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada. |
| Código | Clase | Descripción | Cuerpo |
|---|---|---|---|
| 200 | 2xx | Beneficiario reactivado (existía en estado archivado para el mismo account_number). Incluye meta.reactivated=true. | CreateBeneficiaryResponse |
| 201 | 2xx | Beneficiario creado. | CreateBeneficiaryResponse |
| 400 | 4xx | El cuerpo de la petición está vacío o no es JSON válido. | ErrorResponse |
| 401 | 4xx | Se requiere autenticación o las credenciales son inválidas | ErrorResponse |
| 403 | 4xx | Permisos insuficientes | ErrorResponse |
| 413 | 4xx | El cuerpo de la petición supera el tamaño máximo admitido (body_too_large). | ErrorResponse |
| 422 | 4xx | La cuenta no pasó la validación, o el alta chocó con un tope. Los códigos posibles son account_number_required, account_number_invalid_type, label_invalid_type, invalid_account_format, invalid_account_length, invalid_clabe_checksum, invalid_card_luhn, clabe_prefix_not_recognized, bank_code_required_for_phone, invalid_bank_code, max_length_exceeded, beneficiary_already_registered y plan_cap_exceeded. account_number_invalid_type y label_invalid_type aparecen cuando el campo llega con un tipo distinto de cadena de texto. Todo error de campo trae source.pointer. | ErrorResponse |
| Código | Clave | Ejemplo |
|---|---|---|
| 400 | body_empty | El cuerpo de la petición está vacío. Envelope
|
| 400 | invalid_json | El cuerpo no es JSON válido. Envelope
|
| 401 | unauthorized | Credenciales de autenticación ausentes o inválidas. Envelope
|
| 403 | permission_denied | No tienes permiso para acceder a este recurso. Envelope
|
| 413 | body_too_large | El cuerpo de la petición es demasiado grande. Envelope
|
| 422 | account_number_invalid_type | El campo account_number debe ser una cadena de texto. Envelope
|
| 422 | bank_code_required_for_phone | Hace falta un `bank_code` para registrar un beneficiario de tipo celular. Envelope
|
| 422 | beneficiary_already_registered | Ya existe un beneficiario con ese número de cuenta. Envelope
|
| 422 | clabe_prefix_not_recognized | El prefijo de la CLABE no corresponde a ningún participante del SPEI. Envelope
|
| 422 | plan_cap_exceeded | El plan de la cuenta de usuario no admite más beneficiarios. Envelope
|