Creando Llaves Bre-B
Visión General
Bre-B es el sistema de pagos inmediatos de Colombia (SPI – Sistema de Pagos Inmediatos), que permite transferencias en tiempo real entre personas, empresas y entidades financieras. La gestión de llaves es el núcleo de este sistema: se basa en el uso de identificadores únicos que simplifican los pagos.
Conceptos Clave
En Bre-B, una Llave (o alias) es un identificador único, legible por humanos, que se asocia a una cuenta bancaria. En lugar de compartir números largos de cuenta, los usuarios pueden registrar una llave para enviar o recibir pagos al instante.
Cada llave se asocia a una cuenta específica y debe ser única a nivel nacional dentro del ecosistema Bre-B.
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 de usuario y la adopción a través de procesos más simples.
- Aumenta la eficiencia operativa al reducir errores manuales.
Para los Usuarios
- Permite pagos inmediatos usando identificadores fáciles de recordar.
- Evita errores al ingresar números de cuenta largos.
- Facilita experiencias de pago intuitivas, especialmente en entornos móviles.
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_valuea una cuenta usando el endpoint Create Keys. - Actualizar Llave: Cambiar la cuenta asociada a la llave.
- Suspender Llave: Bloquear temporalmente una llave por seguridad.
- Eliminar Llave: Desvincular la llave de la cuenta asociada.
- Resolver Llave: Resolver una llave en la cuenta correspondiente.
Crear una Llave
Para más detalles del endpoint, consulta la sección: Crear Llave.
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) |
|---|---|---|
| NRIC | Número de documento | 7922089 |
| M | Número de celular | +573001234567 |
| E | Correo electrónico | user@example.com |
| O | Alias personalizado | @client_alias_123 |
| B | Código comercial entidad | 0012345678 |
La combinación de key_type + key_value debe ser única en toda la infraestructura Bre-B.
Ejemplo de Solicitud
| Parámetro | Descripción |
|---|---|
| account_id | ID de la cuenta que quieres asociar a la llave. |
| key_type | Tipo de llave. Ver sección anterior para valores válidos. |
| key_value | Identificador único de la llave. Debe cumplir con el formato correspondiente al tipo. |
El account_id corresponde al ID obtenido tras Link Account en el proceso de Onboarding de Clientes
Cuerpo de la Solicitud
curl --location 'https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/accounts/keys' \--header 'Content-Type: application/json' \--header 'Authorization: TU_TOKEN_DE_ACCESO' \--data-raw '{ "account_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "key_type": "E", "key_value": "jimmyjohns22000@passportfintech.com"}'Ejemplo de Respuesta
| Parámetro | Descripción |
|---|---|
| id | ID único asignado a la llave. |
| key_value | Valor registrado de la llave. |
| account_id | ID de la cuenta vinculada a esta llave. |
| key_type | Tipo de llave creada (por ejemplo, E para correo electrónico). |
Cuerpo de la Respuesta
{ "key_value": "jimmyjohns22000@passportfintech.com", "account_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "id": "56188354-18be-412d-9e0b-64c8e0f54541", "key_type": "E"}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.