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":
- Elimina los espacios y caracteres especiales →
TechColombiaSAS - Toma los primeros 10 caracteres alfanuméricos →
TechColomb - Combina →
@+LP+TechColomb+0001=@LPTechColomb0001(16 caracteres)
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
- Crear una cuenta virtual: tu sistema llama al endpoint Crear cuenta virtual con los detalles del beneficiario.
- 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. - Comparte la clave con el pagador: el pagador introduce la clave en su aplicación bancaria para iniciar la transferencia.
- 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:- Credenciales API válidas (token de acceso).
- Una cuenta de Localpayment configurada para Colombia (
COP).
Paso 1. Crea una cuenta virtual
Envía una solicitudPOST 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:- Abre tu aplicación bancaria y selecciona la opción Bre-B o Transferencia por clave.
- Introduce la clave Bre-B (p. ej.,
@LPTechColomb0001) como destino. - Introduce el importe y confirma la transferencia.
- El pago se completa en menos de 20 segundos.
Paso 4. Gestionar los webhooks
Localpayment envía una solicitudPOST 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.
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 pago0062. El destinatario debe tener una clave Bre-B registrada en su banco. Tú proporcionas esa clave mediante beneficiary.bank.account.alias.
Cómo funciona
- 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).
- Envía el payout: llama al endpoint Crear Payout con el código
0062y la clave enbeneficiary.bank.account.alias. - 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 solicitudPOST al endpoint Crear un Payout. Ten en cuenta que el cuerpo de la solicitud es un array.
Parámetros clave de la solicitud
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.Lista completa de bancos
Lista completa de bancos
- A
- B
- C
- D
- F
- G
- J
- K
- L
- M
- N
- P
- R
- S
- T
- U
- V
- A&C COLANTA
- ACCIONES Y VALORES
- AFROAMERICANA
- ALCALICOOP
- AMAR
- AVANCOP
Preguntas frecuentes
¿Cuánto tiempo tarda en activarse mi cuenta virtual de Bre-B?
¿Cuánto tiempo tarda en activarse mi cuenta virtual de Bre-B?
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.¿Puedo usar la misma clave Bre-B para varios pagos?
¿Puedo usar la misma clave Bre-B para varios pagos?
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.
¿Qué sucede si un pagador envía una cantidad superior al máximo permitido?
¿Qué sucede si un pagador envía una cantidad superior al máximo permitido?
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.
¿Puedo recibir pagos de Bre-B fuera del horario comercial?
¿Puedo recibir pagos de Bre-B fuera del horario comercial?
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.
¿Cuál es la diferencia entre account.number y account.alias?
¿Cuál es la diferencia entre account.number y account.alias?
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.
account.type ni account.number, solo account.alias.¿Por qué se rechaza mi solicitud de Payout con el mensaje 'Invalid param + [paymentMethod.code]'?
¿Por qué se rechaza mi solicitud de Payout con el mensaje 'Invalid param + [paymentMethod.code]'?
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 [...]).¿Cómo genera Localpayment la clave Bre-B para mi cuenta virtual?
¿Cómo genera Localpayment la clave Bre-B para mi cuenta virtual?
La clave se genera de forma determinista a partir del nombre del beneficiario que tú proporcionas al crear el VA:
- Elimina todos los espacios y caracteres especiales del nombre del beneficiario.
- Toma los primeros 10 caracteres alfanuméricos de la cadena resultante.
- Combina:
@+LP+ segmento del nombre + contador secuencial de 4 dígitos.
"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:- Creación de la VA: crea una cuenta virtual para Colombia y confirma la respuesta
100 INPROGRESS. - Recuperación de la clave: consulta el endpoint de estado hasta que
status.code: "200"y luego verifica quebeneficiary.bank.account.numbercontenga una clave Bre-B válida. - 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. - Envío de payout: envía un payout con el código
0062y unbeneficiary.bank.account.aliasválido. - Manejo de notificaciones duplicadas: verifica que tu sistema gestione los reintentos de webhook de forma idempotente usando
internalIdoexternalId. - 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.

