Firux Partner API
Crea cobros Bre-B por API y recibe la confirmación por webhook firmado.
- El dinero es del comercio. Cada cobro entra a una cuenta recaudadora de nuestro proveedor de pagos y Firux lo anota en el saldo del comercio; Firux no es titular de esa cuenta. La API crea y consulta cobros: no mueve dinero ni permite retiros.
- Montos en pesos COP enteros. El peso no tiene centavos:
amountva y vuelve como entero (50000= $50.000). Mínimo $2.000, máximo $12.000.000 por cobro. El máximo efectivo puede ser menor mientras el comercio no verifica su identidad; si se supera, la API responde422conerror.type = charge_not_allowed. - URL base:
https://api.firux.co/v1
Inicio rápido
- Crea una conexión de prueba en el panel (Ajustes → Conexiones API). Copia la llave
firux_test_...y el secreto de firmawhsec_...: se muestran una sola vez. - Crea un cobro con
POST /charges, tuIdempotency-Keyy tuexternal_reference(ver Crear un cobro). - Simula el pago con
POST /charges/{id}/simulate_paymenty recibe el webhook firmado en tu URL. - Verifica la firma y marca la venta como pagada en tu sistema.
- Pasa a producción con una conexión
firux_live_...cuando cumplas la lista para salir a producción.
Autenticación
Cada llamada lleva la API key del comercio en el header Authorization:
Authorization: Bearer firux_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- Se genera y se muestra una sola vez desde el panel del comercio (Ajustes → Conexiones API).
- Prefijos:
firux_live_(producción) yfirux_test_(pruebas). - Es una credencial de servidor: nunca la pongas en el navegador ni en apps de cliente.
firux_oat_... en los mismos endpoints, sin pedirle que copie su llave.Crear un cobro
POST/charges · requiere el header Idempotency-Key.
curl -X POST https://api.firux.co/v1/charges \
-H "Authorization: Bearer firux_test_..." \
-H "Idempotency-Key: 5f3c9b2a-1e77-4a10-9a1c-abc123" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"external_reference": "FACT-2026-00123",
"description": "Mensualidad julio - Club Deportivo"
}'
Respuesta 201
{
"id": "chg_9f8c1d2e...",
"object": "charge",
"status": "PENDING",
"amount": 50000,
"currency": "COP",
"external_reference": "FACT-2026-00123",
"reference": "API-8F3K2M1Q",
"payment_url": "https://firux.co/pay/API-8F3K2M1Q",
"qr_emv": "000201...",
"payment_method": "BRE_B",
"breb_method": "qr",
"breb_key": null,
"created_at": "2026-07-25T14:03:00-05:00"
}
Muéstrale al pagador el qr_emv (como QR Bre-B) o el payment_url. La confirmación llega por webhook; no hace falta poletear.
expires_at (fecha UTC, ej. 2026-08-18T04:59:59Z) al crear el cobro.Idempotencia y external_reference
Idempotency-Keyprotege contra reintentos de red del mismo request: la misma clave con el mismo cuerpo devuelve el mismo cobro (nunca duplica). Reusarla con otro cuerpo devuelve422.external_referencees tu llave de negocio (tu id de factura o pedido). Si vuelves a crear un cobro con la misma referencia: si sigue pendiente y con el mismo monto se devuelve ese cobro (200); si ya está pagado,409. Así puedes emitir el cobro hoy y tu cliente lo paga cuando quiera (el pago por Bre-B es instantáneo y Firux no da crédito), sin que se dupliquen los cobros de la misma factura.
Consultar cobros
# Por id curl https://api.firux.co/v1/charges/chg_9f8c1d2e... \ -H "Authorization: Bearer firux_test_..." # Por tu referencia curl "https://api.firux.co/v1/charges?external_reference=FACT-2026-00123" \ -H "Authorization: Bearer firux_test_..."
Una key solo ve los cobros que esa conexión creó (aislamiento por integración).
Estados del cobro
| Estado | Qué significa |
|---|---|
PENDING | Creado, esperando el pago. Vence a las 24 horas o en tu expires_at. |
PAID | El riel confirmó el pago y salió charge.paid. Si después hay una devolución, sigue en PAID: amount_refunded y refunded_at dicen cuánto y cuándo se devolvió. |
EXPIRED | Venció sin pago. Con la misma external_reference puedes crear otro. |
FAILED | No se pudo completar. |
Webhooks
Cuando un cobro se paga, Firux hace POST a la URL de webhook del comercio con el evento charge.paid. Debe ser https y pública. Headers de cada envío:
| Header | Descripción |
|---|---|
Firux-Event-Id | Id del evento (estable; úsalo para deduplicar). |
Firux-Event-Type | El evento: charge.paid, charge.expired, payment.notified, payment_order.paid, payment_order.review_required, account.updated, connection.revoked o webhook.test. |
Firux-Timestamp | Unix timestamp del envío. |
Firux-Signature | Una o más firmas v1=<hex> separadas por coma. |
Cuerpo (data)
{
"id": "evt_...",
"type": "charge.paid",
"livemode": true,
"account_id": "0a1b2c3d-1111-7222-8333-444455556666",
"connection_id": "0a1b2c3d-9999-7888-8777-666655554444",
"data": {
"charge_id": "chg_...",
"status": "PAID",
"amount": 50000,
"amount_paid": 50000,
"currency": "COP",
"external_reference": "FACT-2026-00123",
"paid_at": "2026-07-25T14:05:11-05:00",
"detected_at": "2026-07-25T14:05:14-05:00",
"payment_method": "BRE_B",
"payer_name": "LAURA GOMEZ",
"payer_bank": "Bancolombia",
"payer_document": "CC ****5678",
"payer_mismatch": false,
"receipt_url": "https://firux.co/pay/API-8F3K2M1Q?cobro=9f8c1d2e...",
"receipt_image_url": "https://firux.co/comprobante/9f8c1d2e-....jpg",
"point_of_sale": null,
"source": "api"
}
}
paid_at = cuándo se movió la plata en el banco; detected_at = cuándo lo vio Firux.
payer_name, payer_bank y payer_document dicen quién pagó, desde qué banco y con qué documento, enmascarado: el documento nunca llega completo. Pueden llegar en null si el riel todavía no los entregó; el cobro los trae cuando llegan (GET /v1/charges/{id}). receipt_url abre el comprobante de Firux de ese pago, para verlo, descargarlo o compartirlo, y receipt_image_url es la imagen del comprobante (JPEG) para mandarla tal cual, por ejemplo por WhatsApp. La imagen se hace unos segundos después del pago: si la pides antes, responde 404 con Retry-After; reintenta después de esos segundos. Los mismos campos están en el cobro cuando su estado es PAID. En una simulación llegan datos de ejemplo y sin comprobante.
point_of_sale y source dicen de qué caja y de dónde salió el cobro, para conciliar por caja. source es api (lo creó tu sistema), qr_estatico (le pagaron al QR fijo del negocio o de una caja) o panel (el panel, la app, los links, la agenda o el menú). point_of_sale trae {"id", "name"} de la caja, o null si el cobro no es de una caja: los que crea la API no tienen caja. Los pagos al QR fijo llegan por charge.paid a las conexiones con la cobertura "Todos los pagos" (all_payments); en GET /v1/charges solo están los cobros de tu conexión, así que ahí source siempre es api. El id de la caja es el mismo point_of_sale_id de payment.notified.
account_id (el comercio) y connection_id (la conexión que recibe el aviso) vienen arriba en todos los eventos.
Avisos opcionales
Además de charge.paid, una conexión puede pedir en Ajustes, Conexiones API:
| Evento | Cuándo llega |
|---|---|
charge.expired | Un cobro venció sin pago (una vez por cobro, sin datos de quien paga). |
account.updated | Cambió lo que devuelve GET /v1/account: la verificación, el tope, si cobra, la llave dinámica, el plan o el nombre. data es la cuenta completa. |
connection.revoked | La conexión dejó de servir; data.reason dice por qué. Llega aunque ya esté desconectada. |
Responde 2xx para confirmar; si respondes error o hay timeout, Firux reintenta con backoff (aprox. 1m, 5m, 30m, 2h, 6h).
payment.notified. Mira la pestaña Verificador de Pagos.Verificar la firma (obligatorio)
Reconstruye HMAC-SHA256(secreto, "{timestamp}.{cuerpo_crudo}") y compáralo en tiempo constante con alguna de las firmas del header. El secreto de firma (whsec_...) se muestra al crear o rotar la conexión y es distinto de la API key. La firma va en hexadecimal minúscula con el prefijo v1=. Rechaza timestamps de más de 300 segundos (5 minutos).
Node.js
const crypto = require("crypto");
function verify(rawBody, headers, secret) {
const ts = headers["firux-timestamp"];
const expected = crypto.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`).digest("hex");
const sigs = (headers["firux-signature"] || "")
.split(",").map(s => s.trim().replace(/^v1=/, ""));
const ok = sigs.some(s => s.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
return ok && Math.abs(Date.now()/1000 - Number(ts)) < 300;
}
PHP
function firux_verify(string $rawBody, array $headers, string $secret): bool {
$ts = $headers['Firux-Timestamp'] ?? '';
$expected = hash_hmac('sha256', $ts.'.'.$rawBody, $secret);
foreach (explode(',', $headers['Firux-Signature'] ?? '') as $s) {
if (hash_equals($expected, trim(str_replace('v1=', '', $s)))) {
return abs(time() - (int) $ts) < 300;
}
}
return false;
}
Firux-Signature puede traer dos firmas durante una rotación de secreto (v1=A,v1=B). Acepta si cualquiera cuadra: así el comercio rota su secreto sin cortarte los webhooks. En el OpenAPI está también el ejemplo en Python.Vector de prueba
Para comprobar tu código antes del primer evento real: con estos datos tu función debe dar exactamente esta firma. Prueba solo la firma: el timestamp es fijo y ya no pasa la ventana de 300 segundos.
| Dato | Valor |
|---|---|
| Secreto | whsec_ejemplo_123 |
| Timestamp | 1791400000 |
| Cuerpo | {"id":"evt_test_ejemplo","type":"webhook.test","livemode":false,"data":{"message":"hola"}} |
| Firma esperada | v1=e703ad33b45496ea12cb57643fdb783bce339b0550f7cd95ce3f661a47056159 |
Para probar tu endpoint sin esperar un pago: en Ajustes, Conexiones API, el botón Enviar prueba manda un webhook.test firmado igual que los demás eventos (con simulated: true). Con credenciales de prueba también puedes usar POST /charges/{id}/simulate_payment. Los eventos, sus headers y esta firma también están en la sección webhooks del OpenAPI.
Errores
Formato uniforme: {"error":{"type":"...","message":"..."}}
| HTTP | Cuándo |
|---|---|
400 | Falta Idempotency-Key. |
401 | Credenciales inválidas o revocadas. Con Conectar con Firux Pay, token_expired (renueva el acceso) o token_revoked. |
403 | Con Conectar con Firux Pay: el acceso no tiene el permiso del endpoint (insufficient_scope, con el permiso en error.scope). |
409 | external_reference pagada/en conflicto, o solicitud en proceso. |
422 | Validación (monto, reglas de negocio). |
503 | Bre-B no disponible momentáneamente; reintenta. |
Probar con Postman
No necesitas escribir código para probar la API. Con el OpenAPI, Postman arma la colección completa (todos los endpoints listos):
- Descarga el archivo con el botón Descargar OpenAPI (arriba) o desde /openapi.yaml.
- En Postman: Import → suelta el
openapi.yaml. Se crea la colección con Crear cobro, Consultar cobro, etc. - Genera tu API key de prueba (
firux_test_...) desde tu panel: Ajustes → Conexiones API. Se muestra una sola vez. - En
POST /charges: pon la key en Authorization → Bearer, agrega un headerIdempotency-Keyúnico, y en el cuerpo unamounty tuexternal_reference. Dale Send. - Para ver llegar tu webhook sin mover dinero real, usa Modo prueba (
simulate_payment).
api.firux.co/v1/charges en el navegador siempre da 401 (y /v1 a secas da 404): al navegador le falta el header Authorization y el método POST. Es lo esperado: por eso se prueba con Postman o cURL, no con la barra de direcciones.Modo prueba
Con una key firux_test_... y una URL de webhook configurada puedes simular el pago sin mover dinero real y ver llegar tu webhook firmado:
curl -X POST https://api.firux.co/v1/charges/chg_.../simulate_payment \ -H "Authorization: Bearer firux_test_..."
simulate_payment no funciona con keys live.
Salir a producción
- Tu servidor verifica la firma de cada webhook y rechaza los timestamps de más de 300 segundos.
- Responde
2xxrápido y procesa después; un mismoFirux-Event-Idno se procesa dos veces. - Cada
POST /chargeslleva su propiaIdempotency-Keyy tuexternal_reference. - Ante un
503, reintenta con una espera que crece; ante un422, corrige la solicitud. - Respeta los montos: de $2.000 a $12.000.000 por cobro, y un tope menor mientras la empresa no verifica su identidad.
- La llave
firux_live_...y el secreto viven solo en tu servidor, en variables de entorno. - Si un webhook no llega, consulta el cobro con
GET /charges/{id}antes de suponer que no se pagó. - Sigue el estado del servicio (también en JSON).
Cambios de la API
Los cambios que solo agregan campos o eventos llegan sin aviso: tu integración debe ignorar lo que no conoce. Los que pueden romper una integración se avisan con al menos 30 días (ver los términos de uso de la API).
| Fecha | Cambio |
|---|---|
| 2026-11-11 | receipt_image_url en el cobro pagado y en charge.paid: la imagen del comprobante, en una dirección estable. |
| 2026-10-30 | Conectar con Firux Pay para plataformas: OAuth 2.0 con PKCE (/oauth/authorize, POST /v1/oauth/token y POST /v1/oauth/revoke), los permisos por endpoint y GET /v1/account. Todos los eventos traen account_id y connection_id. Avisos nuevos: charge.expired, account.updated y connection.revoked. |
| 2026-10-25 | La caja y el origen del cobro, en el cobro y en charge.paid: point_of_sale ({"id", "name"} o null) y source (api, qr_estatico o panel). |
| 2026-10-22 | Órdenes de pago: si pagó otra persona, la orden queda NEEDS_REVIEW y llega payment_order.review_required; se resuelve con confirm o reject. En producción, desde el plan Verificador Plus. payment.notified trae el status de la orden. |
| 2026-10-21 | Órdenes de pago del Verificador: POST /v1/payment_orders, su consulta, cancel y simulate_payment. Evento payment_order.paid; payment.notified trae payment_order cuando el pago cruzó con una orden de la conexión. |
| 2026-10-20 | Quién pagó, en el cobro pagado y en charge.paid: payer_name, payer_bank, payer_document (enmascarado) y receipt_url. charge.paid también trae payer_mismatch. |
| 2026-10-15 | amount_refunded y refunded_at en el cobro; un cobro devuelto sigue en PAID. Llave dinámica: payment_method, breb_method, breb_key, expected_payer_document y payer_mismatch. |
| 2026-10-03 | Evento payment.notified con los pagos del Verificador de Pagos. |
| 2026-07-25 | Primera versión: cobros, consulta, idempotencia, webhooks firmados y modo prueba. |
Soporte
¿Dudas con la integración? Escríbenos a soporte@firux.co. La especificación completa (con el ejemplo en Python y todos los esquemas) está en el OpenAPI, listo para importar en Postman o Insomnia.