https://api.veriko.mx/v1/beneficiaries/lookup Buscar cuenta en lista blanca propia
Busca el número de cuenta exacto en la lista de beneficiarios del usuario autenticado. Si existe, devuelve los metadatos del banco para autocompletar formularios sin búsqueda manual. Devuelve 404 cuando la cuenta no está en la lista del usuario. Nunca revela si la cuenta existe en listas de otros usuarios. Si solo necesitas validar la estructura del número (CLABE checksum o Luhn de tarjeta) sin requerir que esté registrado, usa GET /v1/beneficiaries/validate-account; como fallback global por sufijo (no expone el número completo) GET /v1/account-directory/lookup.
| Parámetro | Ubicación | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
account * | query | string | obligatorio | Número de cuenta completo: 10 dígitos (celular), 13–19 (tarjeta) o 18 (CLABE). Los separadores se eliminan antes de buscar. |
curl -X GET 'https://api.veriko.mx/v1/beneficiaries/lookup' \
-H 'Authorization: Bearer mxcep_••••'
Ejemplo en Python — próximamente.
Ejemplo en JavaScript — próximamente.
Ejemplo en PHP — próximamente.
| Campo | Tipo | Descripción |
|---|---|---|
type * | string | Tipo del recurso JSON:API. |
attributes * | object | Metadatos de la cuenta resuelta. |
account_number * | string | Número de cuenta consultado (CLABE, tarjeta o celular). |
account_type * | string | Tipo de cuenta autodetectado al alta. |
bank_code * | string | Código Banxico SPEI de 5 dígitos del banco receptor. |
bank_name * | string | Nombre del banco resuelto. |
label | string | null anulable | Etiqueta libre del beneficiario, `null` si no fue asignada. |
| Código | Clase | Descripción | Cuerpo |
|---|---|---|---|
| 200 | 2xx | Cuenta encontrada en la lista del usuario; devuelve metadatos del banco. | LookupBeneficiaryAccountResponse |
| 400 | 4xx | Parámetro `account` ausente (`query_param_account_required`) o formato inválido (`invalid_account_format`). | ErrorResponse |
| 401 | 4xx | Se requiere autenticación o las credenciales son inválidas | ErrorResponse |
| 403 | 4xx | Permisos insuficientes | ErrorResponse |
| 404 | 4xx | Cuenta no encontrada en la lista de beneficiarios del usuario. | ErrorResponse |
| Código | Clave | Detalle |
|---|---|---|
| 400 | invalid_account_format | The account format is not recognized. Envelope
|
| 400 | query_param_account_required | The `account` query parameter is required. Envelope
|
| 401 | unauthorized | Invalid or missing authentication credentials. Envelope
|
| 403 | forbidden | You do not have permission to access this resource. Envelope
|
| 404 | beneficiary_not_found_for_account | No beneficiary found for this account. Envelope
|