Previsualizar beneficiario BRE-B

El endpoint de previsualización permite resolver una llave BRE-B y obtener la información del titular asociado antes de ejecutar un pago. Es una operación de solo lectura que no genera ninguna transacción ni movimiento de fondos.

URL Base

Producción:

https://api.payouts.wompi.co/v2

Endpoint Previsualizar beneficiario BRE-B

GET /v2/breb/keys/resolve/{keyValue}

Cabeceras (Headers)

Header	Requerido	Descripción
x-api-key	Sí	API Key del comercio para autenticación
user-principal-id	Sí	Identificador único del usuario (UUID)
business-application-id	No	Identificador de la aplicación de negocio. Valor: WOMPI_PAYOUTS

x-api-key: exMsrSQwTL2vgrIQ2RdNL5MOlmNfOt7taSyMgzlJ
user-principal-id: 63416484-e3e2-48ff-8f0d-20877cd0d161

Parámetros

Path

Parámetro	Tipo	Requerido	Descripción
keyValue	string	Sí	Valor de la llave BRE-B a resolver

Query

Parámetro	Tipo	Requerido	Descripción
keyType	string	No	Tipo de llave BRE-B. Si se envía, se valida el formato del valor contra el tipo especificado.

Valores posibles de keyType:

Tipo	Formato esperado	Ejemplo
ALPHANUMERIC	@ + 5 a 20 caracteres alfanuméricos	@JUANPEREZ
MAIL	Email válido	juan@email.com
PHONE	10 dígitos, inicia con 3	3001234567
IDENTIFICATION	1 a 18 caracteres alfanuméricos	1234567890
ESTABLISHMENT_CODE	8 dígitos	12345678

Respuesta exitosa

HTTP 200 OK

{
  "status": 200,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "JUA*** PER*** GAR***",
    "financialEntity": {
      "name": "BANCOLOMBIA",
      "code": "001"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@JUA***"
  }
}

Campo	Descripción
holderName	Nombre del titular de la llave (enmascarado por seguridad)
financialEntity.name	Nombre de la entidad financiera asociada
financialEntity.code	Código de la entidad financiera
keyType	Tipo de llave resuelta
keyValue	Valor de la llave (enmascarado)

Datos enmascarados

Por seguridad, los datos del titular se retornan parcialmente enmascarados. Esto es suficiente para que tu usuario confirme visualmente al beneficiario antes de proceder con el pago.

Ejemplos por tipo de llave

Llave alfanumérica

GET /v2/breb/keys/resolve/@JUANPEREZ?keyType=ALPHANUMERIC

Respuesta:

{
  "status": 200,
  "meta": {
    "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "JUA*** PER*** GAR***",
    "financialEntity": {
      "name": "BANCOLOMBIA",
      "code": "001"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@JUA***"
  }
}

Llave tipo email

GET /v2/breb/keys/resolve/juan@email.com?keyType=MAIL

Respuesta:

{
  "status": 200,
  "meta": {
    "trace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "JUA*** PER*** LON***",
    "financialEntity": {
      "name": "DAVIVIENDA",
      "code": "051"
    },
    "keyType": "MAIL",
    "keyValue": "jua***@ema***.com"
  }
}

Llave tipo teléfono

GET /v2/breb/keys/resolve/3001234567?keyType=PHONE

Respuesta:

{
  "status": 200,
  "meta": {
    "trace_id": "c3d4e5f6-a7b8-9012-cdef-345678901234"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "MAR*** GOM*** RUI***",
    "financialEntity": {
      "name": "NEQUI",
      "code": "507"
    },
    "keyType": "PHONE",
    "keyValue": "300***4567"
  }
}

Llave tipo documento de identidad

GET /v2/breb/keys/resolve/1234567890?keyType=IDENTIFICATION

Respuesta:

{
  "status": 200,
  "meta": {
    "trace_id": "d4e5f6a7-b8c9-0123-def4-567890123456"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "CAR*** MEN*** SAL***",
    "financialEntity": {
      "name": "BANCO DE BOGOTA",
      "code": "001"
    },
    "keyType": "IDENTIFICATION",
    "keyValue": "123***7890"
  }
}

Llave tipo código de establecimiento

GET /v2/breb/keys/resolve/12345678?keyType=ESTABLISHMENT_CODE

Respuesta:

{
  "status": 200,
  "meta": {
    "trace_id": "e5f6a7b8-c9d0-1234-ef56-789012345678"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "EMP*** TEC*** SAS***",
    "financialEntity": {
      "name": "BBVA COLOMBIA",
      "code": "013"
    },
    "keyType": "ESTABLISHMENT_CODE",
    "keyValue": "1234***8"
  }
}

Respuestas de error

400 — Formato de llave inválido

Se retorna cuando el valor de la llave no cumple con el formato esperado para el tipo indicado.

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_033",
  "message": "El valor de la llave BRE-B no tiene un formato válido.",
  "type": "Business"
}

Acción recomendada: Verificar que el valor de la llave cumpla el formato esperado según su tipo. Consulta la tabla de tipos de llave más arriba.

401 — No autorizado

Se retorna cuando la x-api-key es inválida o no fue proporcionada.

{
  "message": "Unauthorized"
}

Acción recomendada: Verificar que estás enviando la x-api-key correcta en los headers.

403 — Prohibido

Se retorna cuando el payer no se encuentra registrado o no tiene permisos.

{
  "status": 403,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "403",
  "message": "Payer not found",
  "data": {
    "message": "Payer not found",
    "error": "Forbidden",
    "statusCode": 403
  }
}

Acción recomendada: Verificar que el user-principal-id corresponde a un payer activo con producto de Pagos a Terceros habilitado.

404 — Llave no encontrada

Se retorna cuando la llave BRE-B no existe o no está activa en el directorio.

{
  "status": 404,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_034",
  "message": "La llave BRE-B no se encuentra activa o no está registrada.",
  "type": "Business"
}

Acción recomendada: Confirmar con el beneficiario que la llave está registrada y activa en su entidad financiera.

503 — Servicio no disponible

Se retorna cuando el servicio de resolución BRE-B presenta problemas de conectividad.

{
  "status": 503,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_036",
  "message": "El servicio de resolución BRE-B no está disponible.",
  "type": "Technical"
}

503 — Timeout

Se retorna cuando la resolución de la llave excede el tiempo máximo de espera.

{
  "status": 503,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_037",
  "message": "Tiempo de espera agotado al resolver la llave BRE-B.",
  "type": "Technical"
}

Acción recomendada para errores 503: Reintentar la solicitud después de unos segundos. Si el problema persiste, contactar a soporte.

Consideraciones

• Sin keyType: Si no envías el parámetro keyType, el sistema intentará determinar el tipo automáticamente basándose en el formato del valor. Sin embargo, se recomienda enviarlo siempre para evitar ambigüedades (por ejemplo, un número de 10 dígitos podría ser un teléfono o un documento).
• Enmascaramiento: Los datos retornados están parcialmente ocultos por seguridad. No es posible obtener los datos completos del titular a través de este endpoint.
• Rate limiting: Este endpoint está sujeto a los mismos límites de tasa que el resto del API.
• Idempotencia: Al ser una operación GET de solo lectura, no requiere header de idempotencia.