Validar Llave

Visión General

Este endpoint valida una Llave Bre-B y, opcionalmente, compara información adicional como datos del participante, cuenta u propietario.

Puedes enviar una llave Bre-B (haya sido creada por tu entidad o no), junto con información adicional opcional. La API devolverá una respuesta tipo booleano (por ejemplo, MATCH / NO_MATCH) para indicar si la llave corresponde al individuo esperado.

Si la información enviada no coincide con el titular real de la llave, no se entregará información personal identificable (PII) del titular correcto. Esto permite validar la información sin exponer datos confidenciales.

Comportamiento del Endpoint

El objeto key es obligatorio.
Los objetos participant, account y owner son opcionales; si se incluyen, cada uno será validado de forma independiente.
Cada campo retorna un indicador de coincidencia (MATCH / NO_MATCH).
Si la llave enviada no existe o no está en estado ACTIVE, la API devolverá HTTP 404.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/validate-key
Método	POST
Encabezados	Content-Type: application/json, Authorization
Autenticación	Token de Acceso (Bearer Token)

Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
key	Objeto	Sí	Llave a validar
key.key_type	String	Sí	Tipo de llave (ej.: `PHONE`, `BCODE`, `EMAIL`, `ID`, `ALPHA`)
key.key_value	String	Sí	Valor de la llave
participant	Objeto	No	Información del participante a validar
participant.identification_number	String	No	NIT del participante
participant.name	String	No	Nombre del participante
account	Objeto	No	Información de la cuenta a validar
account.account_type	String	No	Tipo de cuenta (ej.: `ORDINARY` o `LOW_VALUE`)
account.account_number	String	No	Número de cuenta
owner	Objeto	No	Información del titular
owner.first_name	String	No	Primer nombre
owner.second_name	String	No	Segundo nombre
owner.first_last_name	String	No	Primer apellido
owner.second_last_name	String	No	Segundo apellido
owner.first_last_name	String	No	Primer apellido
owner.second_last_name	String	No	Segundo apellido
owner.type	String	No	Tipo de titular (ej.: `INDIVIDUAL` o `BUSINESS`)
owner.identification_type	String	No	Tipo de documento (ej.: `CC`)
owner.identification_number	String	No	Número de documento

Ejemplo de Solicitud

JSON
    
 
curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.com/v1/validate-key' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "key": {
        "key_type": "PHONE",
        "key_value": "3975999158"
    },
    "participant": {
        "identification_number": "123456789",
        "name": "Bancolombia"
    },
    "account": {
        "account_type": "ORDINARY",
        "account_number": "88758829529"
    },
    "owner": {
        "first_name": "Ligia",
        "second_name": "Abril",
        "first_last_name": "Flores",
        "second_last_name": "Benhumea",
        "type": "INDIVIDUAL",
        "identification_type": "CC",
        "identification_number": "642349532"
    }
}'
Copy

Cuerpo de la Respuesta

Código HTTP: 200 OK
El cuerpo de la respuesta contendrá los detalles de validación de la llave.

Ejemplo de Respuesta

JSON
    
 
{
    "key": {
        "key_type": "PHONE",
        "key_value": "3975999158"
    },
    "participant": {
        "identification_number": "MATCH",
        "name": "MATCH"
    },
    "account": {
        "account_type": "MATCH",
        "account_number": "NO MATCH"
    },
    "owner": {
        "first_name": "MATCH",
        "second_name": "MATCH",
        "first_last_name": "NO MATCH",
        "second_last_name": "MATCH",
        "type": "MATCH",
        "identification_type": "MATCH",
        "identification_number": "MATCH"
    }
}
Copy

Errores Comunes y Manejo

Código HTTP	Significado	Descripción
400 Bad Request	Bad Request	JSON mal formado o campos inválidos
401 Unauthorized	Unauthorized	Falta/expiró token; Bearer inválido
403 Forbidden	Forbidden	El llamador no está autorizado
404 Not Found	Not Found	La llave no existe o no está `ACTIVE`
500 Internal Server Error	Internal Server Error	Error inesperado en el sistema

Buenas Prácticas

Incluye siempre el objeto key , todos los demás campos son opcionales.
Usa los bloques opcionales (account, participant, owner) solo si necesitas validar esa información.

Última actualización el