Creando Llaves Bre-B

Visión General

Bre-B es el sistema de pagos inmediatos de Colombia (Sistema de Pagos Inmediatos - SPI) que habilita transferencias en tiempo real entre personas, comercios, entidades gubernamentales y entidades financieras. En el centro de este sistema está la Gestión de Llaves (Key Management): un identificador único y legible que simplifica el flujo de pago.

Conceptos Clave

En Bre-B, una Llave (o alias) es un identificador legible por humanos para una Cuenta bancaria. En lugar de compartir números de cuenta extensos, los usuarios registran una llave para recibir pagos al instante (no se necesita llave para enviar un pago).

Cada llave se mapea a una cuenta específica y debe ser única globalmente dentro del ecosistema Bre-B.

Nota

La relación entre una cuenta y sus llaves es de tipo 1:N, lo que significa que una cuenta puede tener una o más llaves asociadas.

Valor para el Negocio

Para las Entidades

Mejora la experiencia y adopción del cliente con onboarding más simple y transferencias más fáciles.
Aumenta la eficiencia operativa con menos errores.

Para los Usuarios

Habilita pagos en tiempo real usando identificadores simples.
Evita errores al ingresar números de cuenta y datos personales.
Experiencia más intuitiva, ideal para escenarios mobile-first.

Para los Reguladores

Promueve la inclusión financiera y el acceso a pagos digitales.
Brinda trazabilidad centralizada de la propiedad y uso de llaves.
Se alinea con los objetivos de interoperabilidad regional en América Latina.

Beneficios de los Pagos Basados en Llaves

Beneficio	Descripción
Experiencia Simplificada	Los clientes inician transferencias con una llave, no con un número de cuenta.
Velocidad y Confiabilidad	Los pagos se realizan en tiempo real y con confirmación instantánea.
Interoperabilidad	Las llaves funcionan entre bancos y entidades participantes.
Seguridad y Privacidad	Reduce la exposición de datos sensibles.
Múltiples Llaves por Cuenta	Una cuenta puede tener más de una llave asociada.

Ejemplos de Casos de Uso

Transferencias entre Personas (P2P)

Un cliente envía dinero a un amigo usando su correo electrónico o número celular. No necesita conocer ni almacenar los datos de la cuenta.

Pagos de Persona a Comercio (P2M)

Un comercio registra una llave como tiendaelalcalde@correo.com y recibe pagos instantáneos directamente en su cuenta empresarial.

Ciclo de Vida de una Llave

Crear una Llave: Asocia un key_value a una cuenta usando el endpoint Crear Llave Bre-B.
**Actualizar Llave:**Cambiar la cuenta asociada (p. ej., si el usuario cambia de entidad financiera).
Suspender Llave: Bloquear temporalmente una llave por seguridad.
Activar Llave: Reactivar una llave previamente bloqueada.
Eliminar Llave: Desvincular la llave de la cuenta asociada.
Resolver Llave: Consultar el registro para convertir llaves en cuentas.

Crear una Llave

Para más detalles del endpoint, consulta la sección: Crear Llave Bre-B.

Tipos de Llave y Valor de la Llave

El campo key_type define el formato y propósito de la llave dentro del sistema Bre-B mientras key_value contiene el valor de la llave. Estas llaves permiten pagos rápidos y seguros entre personas y empresas, sin necesidad de compartir información bancaria tradicional.

Tipo de Llave (key_value)	Descripción	Ejemplo de Valor (key_value)
ID	Número de documento	7922089
MOBILE	Número de celular	+573001234567
EMAIL	Correo electrónico	user@example.com
ALPHA	Alias personalizado	@clientalias123
BCODE	Código comercial entidad	0012345678

Nota

La combinación de key_type + key_value debe ser única en toda la infraestructura Bre-B. La plataforma valida esta unicidad.

Ejemplo de Solicitud

Parámetro	Descripción
account_id	ID de la cuenta que quieres asociar a la llave.
key.key_type	Tipo de llave. Ver sección anterior para valores válidos.
key.key_value	Identificador único de la llave. Debe cumplir con el formato correspondiente al tipo.

Nota

El account_id corresponde al ID obtenido tras Vincular Cuenta en el proceso de Vinculación de Clientes.

Cuerpo de la Solicitud

curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/keys' \ --header 'Content-Type: application/json' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --data-raw '{ "account_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "key": { "key_type": "EMAIL", "key_value": "jimmyjohns22000@passportfintech.com" } }'

Ejemplo de Respuesta

Parámetro	Descripción
id	ID único asignado a la llave.
account_id	ID de la cuenta vinculada a esta llave.
key.key_value	Valor registrado de la llave.
key.key_type	Tipo de llave creada (por ejemplo, `E` para correo electrónico).
status	El Estado de la llave.
created_at	Marca de tiempo ISO-8601 (UTC) cuando se creó el recurso en la plataforma Passport.
updated_at	Marca de tiempo ISO-8601 (UTC) de la última actualización del recurso en la plataforma Passport.

Cuerpo de la Respuesta

{ "customer_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "account_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "id": "56188354-18be-412d-9e0b-64c8e0f54541", "key": { "key_value": "jimmyjohns22000@passportfintech.com", "key_type": "EMAIL" }, "status": "ACTIVE", "created_at": "2025-03-12T14:55:00.00000Z", "updated_at": "2025-03-12T14:55:00.00000Z" }

Soporte y Recursos

Explora la Colección de Postman para ver ejemplos prácticos.
Contacta a tu representante de Passport o al equipo técnico si necesitas ayuda adicional.

Última actualización el