Cómo integrar pagos Bre-B en tu software por API y confirmar cada pago

Si tienes una tienda en línea, un sistema de pedidos, un POS o un ERP, seguramente ya te hicieron la pregunta: "¿puedo pagar por Bre-B?". Y detrás viene la difícil: "¿y cómo sabe el sistema que ya pagué?". Muchos negocios resuelven lo primero publicando una llave o un QR fijo, y lo segundo con alguien que revisa el banco y marca los pedidos a mano. Funciona con diez pedidos al día. Con cien, se rompe.

En esta guía te explicamos cómo integrar cobros Bre-B en tu software de forma que cada pago llegue confirmado a tu sistema, sin revisar extractos ni leer correos del banco. Está pensada para quien desarrolla o decide la tecnología de una plataforma: ecommerce, POS, software de gestión, sistemas de reservas o de cartera.

El problema de conciliar pagos a mano

Cuando el cliente paga a una llave o a un QR fijo, tu sistema no se entera. El pago llega a una cuenta bancaria y alguien tiene que:

• Revisar el banco o el correo de notificaciones.

• Adivinar a qué pedido corresponde cada pago, porque el cliente no siempre escribe la referencia y dos pedidos pueden tener el mismo valor.

• Marcar el pedido como pagado, con el retraso y los errores que eso trae.

Algunas plataformas intentan automatizarlo leyendo los correos del banco. Es frágil: un correo se puede imitar, cambia de formato, llega tarde y no trae tu referencia. Lo explicamos en detalle en un aviso no es un pago. La forma robusta es otra: que el cobro nazca en tu sistema, con tu referencia, y que la confirmación llegue a tu sistema cuando la plata entra.

Cómo funciona la integración, en tres pasos

1. Tu sistema crea el cobro con el valor y tu referencia (el número de pedido, de factura o de cuenta).

2. Tu cliente paga escaneando el QR o abriendo el link, desde cualquier banco o billetera que esté en Bre-B.

3. Tu sistema recibe un webhook firmado cuando la plata se acredita, con tu misma referencia. Marcas el pedido como pagado y listo.

Eso es lo que hace la API de cobros Bre-B de Firux Pay. Veamos cada paso con ejemplos reales.

Paso 1: crear el cobro

La API es REST y responde en https://api.firux.co/v1. Te autenticas con tu llave de API en el encabezado Authorization. Para crear un cobro haces un POST a /v1/charges:

POST https://api.firux.co/v1/charges
Authorization: Bearer TU_LLAVE_DE_API
Idempotency-Key: pedido-10482-intento-1
Content-Type: application/json

{
  "amount": 185000,
  "external_reference": "pedido-10482",
  "description": "Pedido 10482, tienda en línea"
}

Tres detalles importantes:

• El monto va en pesos enteros, sin decimales: 185000 son $185.000.

• external_reference es tu referencia y es obligatoria. Con ella vas a reconocer el pago cuando llegue. Si pides de nuevo un cobro con la misma referencia y el mismo valor, y el anterior sigue pendiente, la API te devuelve el mismo cobro en vez de crear uno duplicado.

• El encabezado Idempotency-Key es obligatorio. Si tu servidor reintenta la llamada por un error de red, la API reconoce la llave y no crea dos cobros.

La respuesta trae todo lo que necesitas para cobrar:

{
  "id": "chg_8f2c1d9e-...",
  "object": "charge",
  "status": "PENDING",
  "amount": 185000,
  "currency": "COP",
  "external_reference": "pedido-10482",
  "payment_url": "https://...",
  "qr_emv": "000201...",
  "payment_method": "BRE_B",
  "expires_at": "2026-09-25T15:04:00-05:00"
}

Con qr_emv dibujas el QR en tu pantalla o tu POS, y con payment_url mandas el link por WhatsApp o correo. Si no le pones vencimiento, el cobro dura 24 horas; si quieres otro, lo mandas en expires_at.

Paso 2: el cliente paga

El cliente escanea el QR o abre el link y paga desde la aplicación de su banco o billetera, por Bre-B. La plata llega en segundos, a cualquier hora, también fines de semana y festivos. El máximo por transacción en Bre-B es de 1.000 UVB, que en 2026 son $12.110.000, y cada entidad puede tener un tope menor.

Paso 3: recibir la confirmación por webhook

Cuando el pago se acredita, Firux le hace un POST a la dirección de tu servidor con el evento charge.paid:

{
  "id": "evt_...",
  "type": "charge.paid",
  "livemode": true,
  "data": {
    "charge_id": "chg_8f2c1d9e-...",
    "status": "PAID",
    "amount": 185000,
    "amount_paid": 185000,
    "currency": "COP",
    "external_reference": "pedido-10482",
    "paid_at": "2026-09-24T15:06:12-05:00",
    "payment_method": "BRE_B"
  }
}

Buscas el pedido por external_reference, lo marcas como pagado y respondes con un código 200. Así de simple.

Verifica siempre la firma

Cualquiera podría mandarle un POST a tu servidor diciendo que un pedido se pagó. Por eso cada webhook va firmado, y tu servidor debe comprobarlo antes de creerle. Cada envío trae dos encabezados:

• Firux-Timestamp: el momento del envío.

• Firux-Signature: la firma, con la forma v1=....

La firma es un HMAC-SHA256 de la cadena timestamp + "." + cuerpo, calculado con el secreto de tu integración. Lo verificas así en PHP:

$cuerpo = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_FIRUX_TIMESTAMP'] ?? '';
$firmas = explode(',', $_SERVER['HTTP_FIRUX_SIGNATURE'] ?? '');

$esperada = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $cuerpo, $secreto);

$valida = false;
foreach ($firmas as $firma) {
    if (hash_equals($esperada, trim($firma))) { $valida = true; }
}

// Rechaza firmas inválidas y envíos viejos (protege contra repeticiones).
if (! $valida || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit;
}

Y en Node.js:

const crypto = require('crypto');

function firmaValida(cuerpo, timestamp, encabezado, secreto) {
  const esperada = 'v1=' + crypto
    .createHmac('sha256', secreto)
    .update(`${timestamp}.${cuerpo}`)
    .digest('hex');

  return encabezado.split(',').some((firma) => {
    const a = Buffer.from(firma.trim());
    const b = Buffer.from(esperada);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

El encabezado puede traer más de una firma separada por comas: pasa cuando se está cambiando el secreto, para que no haya un momento en que tus webhooks fallen. Si cualquiera cuadra, es válida.

Qué pasa si tu servidor se cae

Si tu servidor no responde con un 2xx, el webhook se reintenta: al minuto, a los 5 minutos, a los 30 minutos, a las 2 horas y a las 6 horas. Por eso tu manejo debe ser idempotente: usa el id del evento para no procesar dos veces el mismo pago. Y si en algún momento quieres confirmar el estado de un cobro, lo consultas cuando quieras con GET /v1/charges/{id}.

Cómo probar sin mover plata real

Con las credenciales de prueba creas cobros igual que en producción, y con POST /v1/charges/{id}/simulate_payment disparas un charge.paid simulado. Así pruebas tu webhook de punta a punta sin que nadie pague. El evento simulado llega marcado con "simulated": true y "livemode": false.

Buenas prácticas para que la integración no falle

• Responde rápido y procesa después. Cuando llegue el webhook, verifica la firma, guarda el evento y responde 200. Si marcar el pedido toma tiempo, hazlo en una cola.

• No confíes en que el cliente vuelva a tu página. Muchos pagan desde el celular y nunca regresan al navegador. La fuente de verdad es el webhook, no el regreso del cliente.

• Usa una referencia por pedido y no la reutilices. Si una external_reference ya se pagó, la API responde con un conflicto en vez de crear otro cobro; así evitas cobrar dos veces lo mismo.

• Ponle vencimiento a los cobros que lo necesiten. Si un pedido reserva inventario por una hora, manda expires_at para que el QR no quede vivo un día entero.

• Guarda el cuerpo de cada webhook. Si algún día hay que revisar un caso, tendrás el evento exacto que llegó, con su hora.

Por qué esto es distinto a una pasarela por porcentaje

• La API no tiene costo. Lo que se paga es una tarifa fija por venta confirmada, según el monto, no un porcentaje. En ticket alto esa diferencia es grande; puedes ver la tabla en precios.

• El dinero es del comercio. Cada comercio tiene su cuenta y retira su plata a su banco. Tu plataforma automatiza la experiencia.

• La confirmación viene del sistema de pagos, no de un correo o un mensaje: llega server-to-server desde el riel cuando la plata se liquida, y amarrada a tu referencia.

• Tus clientes pagan desde el banco que ya tienen, sin tarjeta y sin registrarse en nada.

Casos en los que encaja muy bien

• Tiendas en línea que hoy piden "manda el pantallazo por WhatsApp" para confirmar pedidos.

• POS y software de restaurantes que quieren cobrar en mesa con un QR por cuenta.

• Distribuidores y mayoristas con pedidos de ticket alto y conciliación manual.

• Plataformas de cartera, colegios, clubes y conjuntos que cobran mensualidades con una referencia por deudor.

Cómo empezar

1. Revisa la documentación completa en developers.firux.co.

2. Pide tus credenciales de prueba e integra el cobro y el webhook.

3. Cuando esté listo, pasas a producción con las credenciales reales.

Si prefieres hablarlo primero, en la página de la API tienes un botón para escribirnos por WhatsApp, o puedes registrar tu negocio directamente.

Fuentes

• Documentación de la API de Firux Pay

• Banco de la República: conozca Bre-B