Saltar al contenido principal
Bre-B es la plataforma nacional de pagos en tiempo real de Colombia, operada por Banco de la República. Acepta pagos instantáneos entre particulares las 24 horas del día, los 7 días de la semana, mediante claves de cuentas virtuales (pagos entrantes) y envía fondos directamente a cualquier clave Bre-B (pagos salientes), todo a través de una única integración. Bre-B es la primera plataforma de pagos en tiempo real de Colombia, impulsada por el gobierno y lanzada el 6 de octubre de 2025 por el Banco de la República. Por primera vez, todos los bancos, monederos electrónicos y proveedores de servicios de pago autorizados en el país comparten una única infraestructura instantánea e interoperable, de forma similar a como Pix transformó Brasil. Bre-B introduce transferencias instantáneas entre cuentas (A2A) en menos de 20 segundos, disponibilidad las 24 horas, los 7 días de la semana, los 365 días del año, y pagos basados en alias (llamados llaves) que eliminan la necesidad de compartir números de cuenta completos. La participación es obligatoria para todas las instituciones financieras reguladas, lo que convierte a Bre-B en la plataforma de pagos de mayor crecimiento en la historia de Colombia. Localpayment admite Bre-B tanto para recibir como para enviar pagos:

Descripción general

Bre-B vs. PSE: ¿Cuándo usar cada uno?

Colombia ya cuenta con el PSE como opción de pago A2A establecida. Bre-B no lo reemplaza, sino que añade una alternativa más rápida y siempre disponible. Utiliza esta tabla para elegir el método adecuado para tu caso de uso:

Llave Bre-B

La llave es un alias alfanumérico corto que reemplaza el número completo de cuenta bancaria para las transferencias Bre-B. Los pagadores solo tienen que ingresar la llave en su aplicación bancaria; no se requieren los datos completos de la cuenta. Cómo genera Localpayment tu clave Al crear una cuenta virtual para Colombia, Localpayment genera automáticamente una clave alfanumérica; no es necesario elegir ni configurar un tipo de clave. La clave se genera de forma determinista a partir del nombre del beneficiario que tú proporcionas. Longitud total de la clave: entre 10 y 16 caracteres alfanuméricos (el símbolo de prefijo @ no se cuenta). Ejemplo: nombre del beneficiario "TechColombia SAS":
  1. Elimina los espacios y caracteres especiales → TechColombiaSAS
  2. Toma los primeros 10 caracteres alfanuméricos → TechColomb
  3. Combina → @ + LP + TechColomb + 0001 = @LPTechColomb0001 (16 caracteres)
La clave generada se devuelve en beneficiary.bank.account.number una vez que la cuenta virtual se activa (status.code: "200").

Límites y disponibilidad

Demo

Mira cómo interactúa un pagador con una cuenta virtual de Bre-B en la práctica:

Recepción de pagos de Bre-B (Pago entrante)

Payin a través de Bre-B utiliza la infraestructura de Cuenta Virtual. Localpayment genera una clave alfanumérica única de Bre-B para cada cuenta que crees. Los pagadores envían fondos a esa clave desde cualquier aplicación bancaria compatible con Bre-B. La liquidación es instantánea y totalmente automatizada.

Cómo funciona

  1. Crear una cuenta virtual: tu sistema llama al endpoint Crear cuenta virtual con los detalles del beneficiario.
  2. Recuperar la clave Bre-B: una vez que la cuenta se active (~6 segundos), consulta tu estado para obtener la clave generada por el sistema desde beneficiary.bank.account.number.
  3. Comparte la clave con el pagador: el pagador introduce la clave en su aplicación bancaria para iniciar la transferencia.
  4. Recepción de fondos y webhook: Localpayment recibe la transferencia y envía un webhook en tiempo real al endpoint configurado.

Antes de comenzar

Asegúrate de tener:

Paso 1. Crea una cuenta virtual

Envía una solicitud POST al endpoint Crear cuenta virtual.

Parámetros clave de la solicitud

Consulta todos los parámetros disponibles en la referencia de la API.

Ejemplo de solicitud

curl

Respuesta exitosa

Respuesta de error

Tiempo de activación: Las cuentas virtuales de Colombia suelen activarse en 6 segundos. Consulta el estado en el endpoint o espera brevemente antes de recuperar la clave Bre-B.
Beneficiarios no localesSi tu beneficiario es residente extranjero (no reside en Colombia), la cuenta virtual debe estar registrada en Localpayment a nombre del titular. Esto garantiza el cumplimiento de la normativa bancaria local y, al mismo tiempo, te permite recibir pagos en nombre de entidades extranjeras.

Paso 2. Recupera tu llave Bre-B

Una vez que la cuenta virtual esté activa (status.code: "200"), envía una solicitud GET al endpoint Obtener estado de la cuenta virtual.

Ejemplo de solicitud

curl

Respuesta exitosa

Campos de respuesta clave

Comparte el valor de beneficiary.bank.account.number con el pagador. No se requieren datos adicionales de la cuenta bancaria.

Paso 3. El pagador inicia la transferencia

El pagador utiliza la clave Bre-B en cualquier aplicación bancaria o billetera digital colombiana participante:
  1. Abre tu aplicación bancaria y selecciona la opción Bre-B o Transferencia por clave.
  2. Introduce la clave Bre-B (p. ej., @LPTechColomb0001) como destino.
  3. Introduce el importe y confirma la transferencia.
  4. El pago se completa en menos de 20 segundos.
Localpayment asocia automáticamente el pago entrante con tu cuenta virtual y envía un webhook.

Paso 4. Gestionar los webhooks

Localpayment envía una solicitud POST al endpoint configurado una vez que el pago se acredita. Tu servidor debe responder con HTTP 200 OK para confirmar la recepción. Consulta la guía de Webhooks para ver las instrucciones de configuración.

Ejemplo de payload del webhook

Campos clave del webhook


Paso 5. Seguimiento del estado de los pagos

Webhooks (recomendado)

Recibe notificaciones en tiempo real cuando se abone un pago. Ideal para entornos de producción.

Endpoint de la API de estado

Consulta el estado de las transacciones mediante programación. Útil para conciliar las notificaciones de webhook perdidas.

Vista del Business Portal

Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado.
Bre-B es una plataforma de pagos directos en tiempo real: las transacciones se liquidan al instante. El webhook se activa solo cuando el pago se ha acreditado por completo.
Referencia completaConsulta todos los códigos de estado en nuestra documentación sobre el estado de las transacciones.

Envío de pagos de Bre-B (desembolso)

Para enviar fondos a la clave Bre-B de un destinatario, utiliza el flujo de Payout por transferencia bancaria con el código de método de pago 0062. El destinatario debe tener una clave Bre-B registrada en su banco. Tú proporcionas esa clave mediante beneficiary.bank.account.alias.

Cómo funciona

  1. Recopila la clave Bre-B del destinatario: obtén la llave registrada del destinatario (cualquier tipo de clave compatible: alfanumérica, teléfono, correo electrónico, documento o código de comerciante).
  2. Envía el payout: llama al endpoint Crear Payout con el código 0062 y la clave en beneficiary.bank.account.alias.
  3. Realiza el seguimiento de la transferencia: supervisa el estado a través de webhooks o la API de estado hasta 200 Completed.

Paso 1. Iniciar el pago

Envía una solicitud POST al endpoint Crear un Payout. Ten en cuenta que el cuerpo de la solicitud es un array.

Parámetros clave de la solicitud

Importante: Al enviar a una clave Bre-B, los campos beneficiary.bank.account.type y beneficiary.bank.account.number deben excluirse de la solicitud. Utiliza solo beneficiary.bank.account.alias.

Ejemplo de solicitud

curl

Respuesta exitosa

Respuesta de error


Paso 2. Seguimiento del estado del pago

Webhooks (recomendado)

Recibe notificaciones en tiempo real cuando se realice el cargo a la transferencia. Ideal para entornos de producción.

Endpoint de la API de estado

Consulta programáticamente el estado de los pagos. Útil para la conciliación y el manejo de excepciones.

Vista del Business Portal

Interfaz visual para supervisar y aprobar manualmente los pagos.
Referencia completaConsulta todos los códigos de estado en nuestra documentación sobre el estado de las transacciones.

Bancos admitidos

Los pagos con Bre-B se pueden enviar y recibir a través de todas las instituciones financieras colombianas participantes: más de 200 bancos, monederos digitales y cooperativas conectadas a la red del Banco de la República.
  • A&C COLANTA
  • ACCIONES Y VALORES
  • AFROAMERICANA
  • ALCALICOOP
  • AMAR
  • AVANCOP

Preguntas frecuentes

Las cuentas virtuales de Colombia suelen activarse en 6 segundos. La respuesta de creación de la VA devuelve status.code: "100" INPROGRESS. Consulta el endpoint Obtener estado de la cuenta virtual hasta recibir status.code: "200" COMPLETED antes de compartir la clave con los pagadores.
Sí. Una cuenta virtual y su clave Bre-B asociada permanecen activas hasta que las desactives o elimines explícitamente. Puedes recibir un número ilimitado de pagos a la misma clave a lo largo del tiempo.
Las transferencias que superen el límite máximo (COP 12.110.000 para depósitos y COP 11.552.000 para pagos) serán rechazadas por la red Bre-B. El pagador verá un error en su aplicación bancaria. Para transferencias de alto valor, divídelas en varias transacciones.
Sí, Bre-B opera las 24 horas del día, los 7 días de la semana, los 365 días del año, por mandato del Banco de la República. No hay horarios restringidos, ni fines de semana, ni días festivos.
Estos campos cumplen diferentes funciones según el flujo:
  • beneficiary.bank.account.number: Se usa en la respuesta de Obtener estado de la cuenta virtual — aquí es donde Localpayment devuelve la clave Bre-B generada automáticamente para tu cuenta virtual de payin. Es un campo de salida de solo lectura.
  • beneficiary.bank.account.alias: Se usa en la solicitud de Crear Payout — aquí es donde tú proporcionas la clave Bre-B del destinatario al iniciar un payout. Es un campo de entrada.
Para los payouts, nunca incluyas account.type ni account.number, solo account.alias.
Este error normalmente significa que paymentMethod.code no es "0062" o que paymentMethod.type no es "BankTransfer". Verifica ambos campos y asegúrate de que paymentMethod.flow esté configurado como "DIRECT". Confirma también que estás enviando el cuerpo de la solicitud como un array JSON (envuelto en [...]).
La clave se genera de forma determinista a partir del nombre del beneficiario que tú proporcionas al crear el VA:
  1. Elimina todos los espacios y caracteres especiales del nombre del beneficiario.
  2. Toma los primeros 10 caracteres alfanuméricos de la cadena resultante.
  3. Combina: @ + LP + segmento del nombre + contador secuencial de 4 dígitos.
Ejemplo: "TechColombia SAS" → elimina los espacios → TechColombiaSAS → primeros 10 → TechColomb → clave = @LPTechColomb0001.El contador (0001, 0002, etc.) se incrementa con cada clave emitida. La longitud final de la clave está entre 10 y 16 caracteres alfanuméricos, excluyendo el símbolo @.

Probando tu integración

Entorno de pruebas

Utiliza el entorno de prueba para todas las pruebas:

Escenarios de prueba

Verifica que tu integración gestione estos escenarios:
  1. Creación de la VA: crea una cuenta virtual para Colombia y confirma la respuesta 100 INPROGRESS.
  2. Recuperación de la clave: consulta el endpoint de estado hasta que status.code: "200" y luego verifica que beneficiary.bank.account.number contenga una clave Bre-B válida.
  3. Recepción de pago (Payin): simula un pago Bre-B entrante y valida que tu controlador de webhook devuelva HTTP 200. Consulta Recibir notificaciones de pago para la configuración de webhooks.
  4. Envío de payout: envía un payout con el código 0062 y un beneficiary.bank.account.alias válido.
  5. Manejo de notificaciones duplicadas: verifica que tu sistema gestione los reintentos de webhook de forma idempotente usando internalId o externalId.
  6. Ciclo de vida de la cuenta: Prueba a habilitar, deshabilitar y eliminar cuentas virtuales.

Próximos pasos

Gestionar el ciclo de vida de las cuentas virtuales

Habilita o deshabilita las claves Bre-B para pausar o reanudar temporalmente el cobro de pagos sin eliminar la cuenta virtual.

Reembolsar un Payin

Emitir un reembolso por un pago Bre-B recibido a través de la API de Localpayment o el Business Portal.

Instrucciones de pago

Consulta exactamente qué información debes compartir con tus pagadores para los pagos a cuentas virtuales en Colombia.

Revisar los detalles de la transacción

Recupera la información completa de la transacción utilizando la API de Localpayment para fines de auditoría y conciliación.
Última modificación el 10 de noviembre de 2026