Todo lo que necesitas saber sobre los pagos inmediatos a través del Sistema de Pago de Bajo Valor Inmediato (SPBVI) de Colombia

(Próximamente 🚧)

‍

Bre-B es la iniciativa del Banco de la República de Colombia que habilita la interoperabilidad entre entidades financieras y otros actores del ecosistema, permitiendo transferencias en tiempo real todos los días, sin depender de horarios bancarios.

En Cobre, esta funcionalidad se integra como un medio de pago inmediato, lo que te permite:

• Enviar y recibir dinero en segundos, con confirmación instantánea de la operación.

• Ofrecer una mejor experiencia a tus clientes y usuarios finales, quienes no tendrán que esperar horarios de compensación ni procesos diferidos.

• Asegurar interoperabilidad, ya que los pagos pueden fluir entre todos los bancos, billeteras digitales y fintechs conectadas a la red.

Cómo usarlo en Cobre:

• Para utilizar Pagos Inmediatos, deberás tener configurada tu cuenta Cobre Balance y acceder a los endpoints de money movements habilitados para este rail.

• Al generar la instrucción de pago, recibirás la confirmación de la transacción en tiempo real.

• Puedes monitorear el resultado a través de webhooks, que notifican automáticamente el estado de cada movimiento.

‍

En este documento conocerás en detalle el ecosistema que permite operar funcionalidades específicas relacionadas con Pagos Inmediatos a través de Bre-B como:

• Administración de Llaves: Aprende todo lo relacionado con la creación, gestión y uso de llaves Cobre. ‍

• Administración de Contrapartes: Conoce los tipos de contrapartes que puedes crear, sus casos de uso y cómo interactúan dentro del flujo de pagos.‍

• Payouts: Aprende cómo crear tu primer movimiento de dinero tipo payout.‍

• Payins: Descubre los diferentes tipos de recaudos o cobros (collections) que ofrece Cobre y cómo generarlos según tus necesidades. 

‍

‍Términos clave

Cobre key (Llave Cobre): Son las credenciales asociadas a una cuenta de Balance de Cobre, habilitadas para recibir pagos.

Cobre Dynamic key (Llave Dinámica de Cobre): Llaves de un solo uso generadas a través de Cobre, con un tiempo de expiración determinado, asociadas a un movimiento de dinero tipo r2p_breb.

Cobre Dynamic QR (QR Dinámico de Cobre): Códigos QR de un solo uso generados mediante Cobre, con un tiempo de expiración específico, asociados a un movimiento de dinero tipo r2p_breb.

key_value: Valor alfanumérico que identifica una clave y puede ser compartido con terceros para recibir pagos.

‍

Administración de Llaves

La administración de llaves es un componente crítico dentro de la plataforma, ya que estas funcionan como identificadores únicos de cada cuenta y están directamente asociadas a la información del titular. En Cobre, las llaves son códigos alfanuméricos que representan una cuenta de Cobre Balance y permiten realizar operaciones de manera segura dentro de la red.

Para simplificar este proceso de administración, en Cobre ponemos a disposición de nuestros clientes un conjunto de APIs diseñadas específicamente para la creación, gestión y validación de llaves. Esto garantiza que cada empresa pueda manejar sus accesos y operaciones de forma sencilla, confiable y escalable.

‍

Acciones disponibles sobre las llaves:

1. Crear una llave: Permite generar una nueva llave alfanumérica asociada a tu cuenta. Al crearla, la llave queda en estado processing hasta que se habilita su uso. Es útil cuando necesitas generar nuevas llaves para tus Cobre Balance.

2. Cancelar una llave: Elimina una llave existente para evitar que siga siendo utilizada para recibir pagos. Una vez cancelada, pasa al estado unregistered. Es útil si una llave ya no es necesaria para tu operación o por políticas de rotación de seguridad.

3. Consultar llaves: Conoce todas las llaves que has creado o una en particular, junto con su estado actual. Es útil para mantener un control actualizado y verificar qué llaves tienes activas.

4. Administrar llaves: Te da la posibilidad de habilitar o deshabilitar una llave ya existente. Según la acción, la llave quedará en estado registered (habilitada) o disabled (deshabilitada). Es útil Cuando quieras pausar temporalmente el uso de una llave o volver a activarla según tus necesidades operativas.

Estas acciones no son independientes: forman parte del ciclo de vida de la llave:

‍

Estados de las llaves

Cada llave puede encontrarse en distintos estados a lo largo de su ciclo:

• En proceso (processing): la creación de la llave fue solicitada, pero aún no ha finalizado.

• Registrada (registered): la llave fue creada y activada correctamente; ya está lista para usarse.

• No registrada (unregistered): la llave fue cancelada a solicitud del cliente mediante la API de cancelación de llaves. Una vez cancelada, no puede reactivarse.

• Deshabilitada (disabled): la llave fue desactivada temporalmente, ya sea por el cliente o por Cobre. Puede volver a activarse si es necesario.

• Fallida (failed): la acción solicitada sobre la llave no se completó con éxito. Es necesario volver a enviar la solicitud de creación.

‍

Estructura y personalización de llaves

Las llaves Cobre se componen de 3 segmentos de texto juntos:

• Parte 1 - @CB: Son los tres primeros caracteres que identifican las llaves creadas por Cobre. Ten en cuenta que incluye el @ (arroba) al comienzo.

• Parte 2 - Cadena aleatoria: Garantiza que el key_value sea único dentro del sistema.

• Parte 3 - Cadena personalizable: Permite al cliente personalizar el key_value según su nombre, número de identificación u otra cadena aleatoria.

‍

Tipos de personalización de llaves

Cobre permite tres tipos de personalización al momento de generar una llave:

‍

Administración de Contrapartes

La creación de contrapartes es necesaria para ejecutar movimientos de dinero tipo push (payouts) o pull (payins), ya que permiten vincular la información requerida para realizar cada tipo de operación.

Cobre ofrece múltiples APIs que permiten administrar contrapartes de forma flexible:

• Creación de una contraparte: Crea una breb_key para payouts o una contraparte r2p_breb para payins. (Ver más)

• Cancelación de una contraparte para restringir su uso: Proceso para que la breb_key o r2p_breb deje de estar disponible y no sea retornada en queries. (Ver más)

• Consulta de contrapartes: Retorno de la lista de todas las contrapartes creadas por el cliente. (Ver más)

‍

Tipos de contrapartes según el flujo de dinero

Dependiendo del tipo de flujo a ejecutar (push para payouts o pull para payins) es necesario crear contrapartes distintas.

Contrapartes para Payouts:

‍

Contrapartes para Payins:
‍

‍

Enviar fondos a una llave registrada

(Próximamente 🚧)

Términos clave

• Llave Cobre: Llaves asociadas a una cuenta de Balance Cobre que permiten recibir pagos.

• Los movimientos de dinero tipo [breb] permiten realizar payouts a contrapartes tipo breb_key, que contienen una llave previamente registrada.

Estos movimientos se procesan a través del sistema de pagos del Banco de la República de Colombia, por lo que su ejecución y compensación dependen directamente de esta infraestructura.

Antes de utilizar esta funcionalidad:

1. Crear un Cobre Balance: La cuenta debe utilizar el proveedor pr_col_cobre y contar con fondos suficientes para ejecutar el movimiento. (Ver más)

2. Crear una contraparte tipo breb_key: Esta debe vincular el key_value correspondiente a la llave de destino. (Ver más)

3. Suscribirse a los eventos necesarios: Esto permitirá recibir notificaciones del estado del movimiento. (Ver más)

‍

⚠️ Importante: Si el monto del movimiento supera los $11.552.000 COP, el pago será procesado automáticamente a través de los rieles Fast_pay o ACH, y estará sujeto a sus respectivos tiempos de compensación.

¿Qué esperar después de usar esta funcionalidad?

1. Se creará un movimiento tipo breb y se enviará a la contraparte breb_key. (Ver más)

2. Movimiento completado: se vinculará una transacción de tipo breb_debit a la cuenta Cobre Balance. (Ver más)

3. Si el débito es devuelto: Se registrará una transacción tipo breb_rejected en la misma cuenta. (Ver más)

4. Si tienes suscripciones activas, recibirás notificaciones según el evento al que estés suscrito. (Ver más)

‍

Se recomienda revisar los distintos estados de los movimientos de dinero y su correcta interpretación.

‍

Combinaciones permitidas para movimientos tipo breb

‍

Recaudar fondos

(Próximamente 🚧)

Términos clave

• Llave Cobre: Llaves asociadas a una cuenta Cobre Balance que permiten recibir pagos.

Cobre ofrece diferentes experiencias para recibir payins en cuentas Cobre Balance, habilitando distintos casos de uso. Estos movimientos de dinero se procesan a través del sistema de pagos del Banco de la República de Colombia, por lo que su ejecución y compensación dependen de dicha infraestructura.

‍

1. A través de una Llave Cobre

Durante la creación de una llave, esta debe vincularse a un Cobre Balance. Una vez generada, la llave podrá recibir fondos provenientes de otras llaves registradas.

Con Cobre, tú decides cómo usar esta funcionalidad:

• Personaliza tu Llave: Posibilidad de personalizar la llave con id, name o random.

• Uso de varias Llaves: Las llaves Cobre no tienen fecha de expiración, por lo que pueden utilizarse múltiples veces para recibir payins. Pueden administrarse según las acciones disponibles.

• Características específicas de creación: Consulta la API de Llaves para ver el listado completo de atributos disponibles.

Antes de usar esta API debes tener en cuenta:

1. Es necesario que crees una cuenta de Balance Cobre con el proveedor pr_col_cobre, que será el destino de los fondos. (Ver más)
2. También hay que crear una llave Cobre (Ver más) 
3. Finalmente, es importante suscribirse a eventos como accounts.balance.credit (Ver más)

Paso a paso para la Creación de una Llave Cobre:

1. Crea la llave a través del endpoint de Llaves con el tipo de personalización definido.
2. Comparte la llave (key_value) con el tercero que enviará los fondos desde su entidad financiera.
3. Recibe tus fondos. Podrás identificar la transacción tipo breb_credit acreditada en la cuenta de Balance Cobre vinculada a la llave.

¿Qué esperar después de usar esta API?

1. La solicitud de creación de llave devolverá estado processing (Ver más)
2. Podrás verificar su estado hasta que esté en registered (Ver más)
3. Cuando el tercero envíe fondos a la llave creada, se registrará una transacción tipo breb_credit en la cuenta de Balance Cobre. (Ver más)
4. Si tienes suscripciones activas, recibirás las notificaciones correspondientes al evento al que estás suscrito. (Ver más)

Ejemplo de caso de uso

Un cliente desea recibir pagos recurrentes de varios usuarios. Como los montos varían poco, decide crear una llave Cobre única para cada cliente, la cual usarán para enviar pagos desde sus instituciones financieras.

Notas:

• Las llaves creadas vía API pueden usarse para recibir múltiples payins.

• Pueden ser consultadas mediante el endpoint get all keys.

• También se reflejan en la metadata del Cobre Balance.

• Esta funcionalidad no representa un movimiento de dinero, ya que solo se registra la transacción de crédito en la cuenta.

‍

2. A través de la experiencia Cobre Checkout

Utilizando la API de Checkouts, es posible ofrecer pagos usando el riel Bre-B, junto con PSE, Nequi y Bancolombia.

Esta funcionalidad es recomendada para usuarios de portal o API que no desean construir una experiencia completa de pago.

Con Cobre, tú decides cómo usar esta funcionalidad:

• Expiración de Llave Dinámica / QR: Validez por defecto: 5 minutos desde su creación. 

• Compatibilidad de Contrapartes: Puedes usar contrapartes r2p o r2p_breb como origen del pago.

• Características específicas de Checkout: Consulta la API de Checkout para más detalles.

Antes de usar esta API debes tener en cuenta:

1. Es necesario que crees una cuenta de Balance Cobre con el proveedor pr_col_cobre, que será el destino de los fondos. (Ver más)
2. También hay que crear una contraparte r2p o r2p_breb como originador del pago. (Ver más)
3. Finalmente, es importante suscribirse a eventos como accounts.balance.credit o money_movements.status.completed. (Ver más)

Experiencia de recaudo a través de Cobre Checkout con Llave Dinámica

1. Crea el enlace de pago: Selecciona el riel Bre-B (u otros rieles si es necesario) a través de nuestra API de Checkout. 
   Una vez creado, puede compartirse con la contraparte o utilizarse para acceder directamente a la página de pago.
   Si se proporcionó un source_id, algunos campos podrán estar prellenados; de lo contrario, la contraparte deberá ingresar la información requerida.
2. La contraparte hace clic en “pagar”, lo que genera una llave dinámica Cobre o un QR dinámico Cobre que podrá ser utilizado para procesar el movimiento de dinero.
3. El cliente completa el pago desde su entidad financiera hacia la llave dinámica generada.
4. Al completarse el pago, el estado del Checkout se actualiza y el usuario es redirigido a la redirect_url especificada.

¿Qué esperar luego de usar esta API?

1. Se generará un enlace de checkout para que el cliente confirme la información necesaria y así crear el movimiento de dinero.(Ver más)
2. Se creará un movimiento de dinero tipo r2p_breb, y se devolverá una llave dinámica Cobre o un QR dinámico Cobre, según lo especificado en la solicitud. (Ver más)‍
3. Cuando el movimiento de dinero sea pagado y el monto sea correcto, se registrará una transacción tipo r2p_breb_credit en el Cobre Balance (Ver más)
4. Si el pago realizado por el usuario no coincide con el monto del movimiento de dinero, la transacción será rechazada, el movimiento cambiará a estado failed y la llave también será cancelada.
5. Si hay suscripciones activas, se enviarán las notificaciones correspondientes según el evento al que estés suscrito. (Ver más) 

Ejemplo de caso de uso

Un cliente necesita cobrar montos fijos a usuarios desconocidos y no cuenta con un equipo técnico para crear pantallas del flujo de Checkout. Utiliza la funcionalidad de Checkout Cobre para generar un link personalizado que sus clientes usan para generar llaves dinámicas y realizar sus pagos.

Notas:

• El QR dinámico de Cobre es un mecanismo que el cliente puede utilizar para representar gráficamente una llave dinámica Cobre.
• Las llaves dinámicas Cobre y los QRs dinámicos son de uso único y no pueden ser consultados mediante el endpoint obtain all keys.
• Estas llaves no se incluyen en el metadata de las cuentas Cobre Balance, ya que están asociadas a un movimiento de dinero.
• Ten en cuenta que el monto máximo permitido para el movimiento de dinero es de $11.552.000 COP, según las condiciones establecidas por la red en tiempo real.
  
  

3. A través de un Movimiento de Dinero (Money Movement API)

Mediante la API de Money Movements, es posible crear directamente un movimiento r2p_breb que devuelva una llave dinámica o QR dinámico de uso único. A diferencia de Checkout, el cliente debe construir su propia experiencia de pago y pantalla de confirmación.

Esta opción es recomendada para integraciones API que requieren personalización completa.

Con Cobre, tú decides cómo usar esta funcionalidad:

• Personaliza tu llave o QR: Tienes la posibilidad de personalizar la llave dinámica Cobre con id, name o random. En el caso de los QRs dinámicos de Cobre, la llave asociada será siempre aleatoria (random).
• Ajusta el tiempo de validez: Es posible configurar la expiración de la llave o QR dinámico por hasta 3 días. Si no se especifica, la validez por defecto será de 5 minutos. 
• Compatibilidad de Contrapartes: Utiliza contrapartes r2p o r2p_breb como origen del pago.
• Revisa la API de Money Movements para ver la lista completa de funcionalidades disponibles.

‍

Flujo de creación del Movimiento de Dinero

1. Creas una experiencia para se recopilar toda la información del usuario final para crear la contraparte correspondiente (r2p o r2p_breb), así como los detalles necesarios para el pago, como el monto, el riel de pago y las descripciones.
2. Con la información recopilada, se crea el movimiento de dinero y se devuelve una llave dinámica Cobre o un QR dinámico Cobre, que podrá ser utilizado para realizar el pago del movimiento.
3. El cliente realiza el pago desde su entidad financiera.
4. Una vez completado el pago, el cliente debe redirigir al usuario a su propia pantalla de confirmación, donde se mostrará el estado del pago y los detalles relacionados.

Antes de usar esta API

1. Es necesario que crees una cuenta de Balance Cobre con el proveedor pr_col_cobre, que será el destino de los fondos. (Ver más)
2. También hay que crear una contraparte r2p o r2p_breb como originador del pago. (Ver más)
3. Verifica que tengas una combinación válida de origen y destino (Ver más)
4. Finalmente, es importante suscribirse a eventos necesarios para recibir notificaciones sobre transacciones de crédito o el estado de movimientos de dinero, como por ejemplo accounts.balance.credit  (Ver más)

‍

Combinaciones permitidas para las llaves dinámicas: 

‍Geografía: COL

Moneda: COP

Origen: Contraparte r2p

Destino: Cobre Balance

‍

Geografía: COL

Moneda: COP

Origen: Contraparte r2p_breb

Destino: Cobre Balance

‍

¿Qué esperar?

1. Se creará un movimiento de dinero tipo r2p_breb, y se devolverá una llave dinámica Cobre o un QR dinámico Cobre según la personalización solicitada. Ten en cuenta que la llave o el QR solo se devolverán si el movimiento está en estado processing. (Ver más)‍
2. Cuando el movimiento de dinero sea pagado y el monto sea correcto, se registrará una transacción tipo r2p_breb_credit en la cuenta de Balance Cobre. (Ver más)‍
3. Si el pago realizado por el usuario no coincide con el monto del movimiento de dinero, la transacción será rechazada, el movimiento cambiará a estado failed, y la llave también será cancelada.
4. Se enviarán notificaciones si hay suscripciones activas (Ver más)

Ejemplo de caso de uso

Un cliente necesita integrar llaves dinámicas de un solo uso dentro de su experiencia de checkout, incluyendo personalización y control de expiración. Por eso prefiere generar las llaves directamente vía la API de Money Movements.

Notas:

• El QR dinámico de Cobre es un mecanismo que el cliente puede usar para representar gráficamente una llave dinámica Cobre.

• Las llaves dinámicas Cobre y los QRs dinámicos son de uso único y no pueden ser consultados mediante el endpoint obtain all keys.

• Ten en cuenta que el monto máximo permitido para el movimiento de dinero es de $11.552.000 COP, según las condiciones establecidas por la red en tiempo real.

Recomendaciones

• Nuestro objetivo es que, durante la creación del movimiento de dinero, la llave dinámica Cobre sea devuelta de forma inmediata. Sin embargo, según nuestra experiencia con otros rieles de pago, si el proceso tarda más de 10 segundos, el movimiento se generará en estado initiated y se actualizará a processing una vez que la llave dinámica o el QR hayan sido creados.

• Revisa los diferentes estados de movimientos de dinero y su interpretación correcta.

‍

Recuerda que si tienes dudas o comentarios sobre el uso del Sistema de Pago de Bajo Valor Inmediato (SPBVI) de Colombia a través de Cobre, puedes contactar a tu Gerente de Cuenta, quien está disponible para acompañarte en cada paso de este proceso de implementación.