Docs
EN
POSThttps://api.veriko.mx/v1/beneficiaries

Crear un beneficiario

Audiencia
public
Autenticación
API key
Permiso
beneficiaries:create
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_code es opcional, se deriva del prefijo.
  • Tarjeta (16 dígitos): bank_code es opcional, se deriva del BIN.
  • Celular/DiMo (10 dígitos): bank_code es 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 200.

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).

Parámetros
ParámetroTipoObligatorioDescripción
account_numberstring (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_codestring (patrón)opcional

Código SPEI de 5 dígitos. Obligatorio cuando el tipo detectado es phone; ignorado para CLABE y tarjeta.

p. ej. 40012
labelstring (?–100)opcional

Etiqueta opcional libre.

p. ej. Proveedor ABC
Petición
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.

Probar en el playground →
Respuesta 2xxCreateBeneficiaryResponse
CampoTipoDescripción
dataobject

Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con type, id, attributes).

type*string

Tipo de recurso JSON:API. Siempre beneficiary.

p. ej. beneficiary
id*string

Identificador numérico del beneficiario en el sistema.

p. ej. 42
attributes*object

Atributos canónicos del beneficiario (datos de la cuenta y metadatos 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 account_type para desambiguar el tipo exacto.

p. ej. 012180004412345678
account_type*string

Tipo de cuenta: clabe (18 dígitos), card (16 dígitos) o phone (10 dígitos).

p. ej. clabe
bank_code*string

Código SPEI (5 dígitos) del banco resuelto.

p. ej. 40012
bank_name*string

Nombre oficial del banco resuelto, derivado de su bank_code.

p. ej. BBVA MEXICO
labelstring | nullanulable

Etiqueta descriptiva libre del usuario. null si no fue asignada.

p. ej. Proveedor ABC
status*string

Estado del beneficiario. inactive si el beneficiario fue archivado o dado de baja. active si está en uso.

p. ej. active
created_at*string (date-time)

Marca temporal UTC de creación.

p. ej. 2026-01-15T10:00:00Z
metaobject

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.

versionstring

Versión de la API que procesó la petición.

p. ej. 1.47.0
api_versionstring

Versión del prefijo de ruta de la API (ej. v1).

p. ej. v1
request_idstring

Identificador único de la petición (hex).

p. ej. a1b2c3d4e5f6
datetimeobject

Descriptor compañero presente en el bloque meta de cada respuesta (y en el meta del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec.

p. ej. {"timezone":"UTC","format":"ISO 8601"}
timezone*string

Siempre UTC — la zona canónica para cada campo datetime del cuerpo.

p. ej. UTC
format*string

Siempre ISO 8601 — sufijo Z explícito en cada datetime.

p. ej. ISO 8601
linksobject

Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

Códigos de respuestaPOST /v1/beneficiaries
CódigoClaseDescripciónCuerpo
2002xxBeneficiario reactivado (existía en estado archivado para el mismo account_number). Incluye meta.reactivated=true.CreateBeneficiaryResponse
2012xxBeneficiario creado.CreateBeneficiaryResponse
4004xxEl cuerpo de la petición está vacío o no es JSON válido.ErrorResponse
4014xxSe requiere autenticación o las credenciales son inválidasErrorResponse
4034xxPermisos insuficientesErrorResponse
4134xxEl cuerpo de la petición supera el tamaño máximo admitido (body_too_large).ErrorResponse
4224xxLa cuenta no pasó la validación, o el alta chocó con un tope. Los códigos posibles son account_number_required, invalid_account_length, clabe_prefix_not_recognized, bank_code_required_for_phone, beneficiary_already_registered y plan_cap_exceeded.ErrorResponse
Errores de POST /v1/beneficiaries
CódigoClaveEjemplo
400body_empty

El cuerpo de la petición está vacío.

Envelope
meta.request_id
c1d2e3f4a5b6
400invalid_json

El cuerpo no es JSON válido.

Envelope
meta.request_id
d2e3f4a5b6c7
401unauthorized

Credenciales de autenticación ausentes o inválidas.

Envelope
meta.request_id
c4d5e6f7a8b9
403forbidden

No tienes permiso para acceder a este recurso.

Envelope
meta.request_id
d5e6f7a8b9c0
413body_too_large

El cuerpo de la petición es demasiado grande.

Envelope
meta.request_id
1a2b3c4d5e6f
422bank_code_required_for_phone

Hace falta un `bank_code` para registrar un beneficiario de tipo celular.

Envelope
meta.request_id
f6a7b8c9d0e1
422beneficiary_already_registered

Ya existe un beneficiario con ese número de cuenta.

Envelope
meta.request_id
b8c9d0e1f2a3
422clabe_prefix_not_recognized

El prefijo de la CLABE no corresponde a ningún participante del SPEI.

Envelope
meta.request_id
a7b8c9d0e1f2
422plan_cap_exceeded

El plan de la cuenta no admite más beneficiarios.

Envelope
meta.request_id
f4a5b6c7d8e9