Firux Pay Partner API v2026-10-30 Estado del servicio Para empresas Descargar OpenAPI

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: amount va 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 responde 422 con error.type = charge_not_allowed.
  • URL base: https://api.firux.co/v1

Inicio rápido

  1. Crea una conexión de prueba en el panel (Ajustes → Conexiones API). Copia la llave firux_test_... y el secreto de firma whsec_...: se muestran una sola vez.
  2. Crea un cobro con POST /charges, tu Idempotency-Key y tu external_reference (ver Crear un cobro).
  3. Simula el pago con POST /charges/{id}/simulate_payment y recibe el webhook firmado en tu URL.
  4. Verifica la firma y marca la venta como pagada en tu sistema.
  5. 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) y firux_test_ (pruebas).
  • Es una credencial de servidor: nunca la pongas en el navegador ni en apps de cliente.
¿Tu plataforma atiende muchos comercios? Con Conectar con Firux Pay cada comercio se conecta con un botón y tú usas un acceso 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.

El QR vence en 24 horas por defecto. Si necesitas otro vencimiento, envía expires_at (fecha UTC, ej. 2026-08-18T04:59:59Z) al crear el cobro.

Idempotencia y external_reference

  • Idempotency-Key protege contra reintentos de red del mismo request: la misma clave con el mismo cuerpo devuelve el mismo cobro (nunca duplica). Reusarla con otro cuerpo devuelve 422.
  • external_reference es 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

EstadoQué significa
PENDINGCreado, esperando el pago. Vence a las 24 horas o en tu expires_at.
PAIDEl 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ó.
EXPIREDVenció sin pago. Con la misma external_reference puedes crear otro.
FAILEDNo se pudo completar.
Hoy las Dispersiones (pagos a terceros), los cobros recurrentes y las devoluciones se manejan desde el panel. Si necesitas hacerlo por API, escríbenos a soporte@firux.co.

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:

HeaderDescripción
Firux-Event-IdId del evento (estable; úsalo para deduplicar).
Firux-Event-TypeEl evento: charge.paid, charge.expired, payment.notified, payment_order.paid, payment_order.review_required, account.updated, connection.revoked o webhook.test.
Firux-TimestampUnix timestamp del envío.
Firux-SignatureUna 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:

EventoCuándo llega
charge.expiredUn cobro venció sin pago (una vez por cobro, sin datos de quien paga).
account.updatedCambió 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.revokedLa 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).

¿El comercio usa el Verificador de Pagos? Tu sistema también puede recibir cada pago que Firux le verifica, con el evento 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;
}
El header 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.

DatoValor
Secretowhsec_ejemplo_123
Timestamp1791400000
Cuerpo{"id":"evt_test_ejemplo","type":"webhook.test","livemode":false,"data":{"message":"hola"}}
Firma esperadav1=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":"..."}}

HTTPCuándo
400Falta Idempotency-Key.
401Credenciales inválidas o revocadas. Con Conectar con Firux Pay, token_expired (renueva el acceso) o token_revoked.
403Con Conectar con Firux Pay: el acceso no tiene el permiso del endpoint (insufficient_scope, con el permiso en error.scope).
409external_reference pagada/en conflicto, o solicitud en proceso.
422Validación (monto, reglas de negocio).
503Bre-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):

  1. Descarga el archivo con el botón Descargar OpenAPI (arriba) o desde /openapi.yaml.
  2. En Postman: Import → suelta el openapi.yaml. Se crea la colección con Crear cobro, Consultar cobro, etc.
  3. Genera tu API key de prueba (firux_test_...) desde tu panel: Ajustes → Conexiones API. Se muestra una sola vez.
  4. En POST /charges: pon la key en Authorization → Bearer, agrega un header Idempotency-Key único, y en el cuerpo un amount y tu external_reference. Dale Send.
  5. Para ver llegar tu webhook sin mover dinero real, usa Modo prueba (simulate_payment).
Abrir 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

  1. Tu servidor verifica la firma de cada webhook y rechaza los timestamps de más de 300 segundos.
  2. Responde 2xx rápido y procesa después; un mismo Firux-Event-Id no se procesa dos veces.
  3. Cada POST /charges lleva su propia Idempotency-Key y tu external_reference.
  4. Ante un 503, reintenta con una espera que crece; ante un 422, corrige la solicitud.
  5. Respeta los montos: de $2.000 a $12.000.000 por cobro, y un tope menor mientras la empresa no verifica su identidad.
  6. La llave firux_live_... y el secreto viven solo en tu servidor, en variables de entorno.
  7. Si un webhook no llega, consulta el cobro con GET /charges/{id} antes de suponer que no se pagó.
  8. 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).

FechaCambio
2026-11-11receipt_image_url en el cobro pagado y en charge.paid: la imagen del comprobante, en una dirección estable.
2026-10-30Conectar 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-25La 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-20Quié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-15amount_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-03Evento payment.notified con los pagos del Verificador de Pagos.
2026-07-25Primera 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.

Verificador de Pagos por API

Recibe en tu sistema, al instante, cada pago que el Verificador le avisa al comercio.

  • No es un cobro. No se crean QR ni links: el comercio sigue recibiendo en su cuenta de siempre y Firux le avisa cada pago que su banco le notifica. Tu sistema lo recibe por webhook firmado, con el evento payment.notified.
  • Sin límites de monto. Llega el pago que le hagan al comercio, del valor que sea. Los montos mínimo y máximo son solo de los cobros Bre-B.
  • No es una confirmación en el riel. Es el aviso del banco del comercio (el correo del banco o la notificación de su celular) que Firux verificó; por eso verified_on_rail siempre es false. Para cobros con confirmación en el riel, usa los cobros Bre-B y charge.paid.
  • Solo de salida. Firux le hace POST a tu webhook: no tienes que llamar a la API para recibirlos.
  • Con tu referencia, si la necesitas. Si tu sistema sabe qué pago espera (una cuota, una factura, una mensualidad), crea una orden de pago: cuando llega el aviso con ese valor, te avisamos con tu referencia.

Cómo activarlo

  1. El comercio necesita un plan del Verificador de Pagos (o su prueba gratis).
  2. En su panel: Ajustes → Conexiones API → Nueva conexión. La de producción es para tu sistema real; si el comercio todavía no cobra por Bre-B, nace solo con los pagos verificados.
  3. Pon la URL https de tu webhook y marca También los pagos verificados. Por defecto una conexión recibe solo charge.paid.
  4. Guarda el secreto de firma: se muestra una sola vez (lo puedes rotar).
  5. Toca Enviar aviso de prueba y mira llegar el evento a tu servidor.
Una conexión de prueba también recibe los pagos verificados reales del comercio, con livemode: false. Úsala solo mientras integras.

El evento payment.notified

{
  "id": "evt_...",
  "type": "payment.notified",
  "api_version": "2026-07-25",
  "created_at": "2026-10-03T15:50:01-05:00",
  "livemode": true,
  "simulated": false,
  "data": {
    "notification_id": "ntf_...",
    "merchant_id": "...",
    "status": "NOTIFIED",
    "amount": 85000,
    "currency": "COP",
    "payer_name": "Laura Gómez",
    "bank": "Nequi",
    "channel": "email",
    "point_of_sale_id": null,
    "occurred_at": "2026-10-03T15:49:58-05:00",
    "received_at": "2026-10-03T15:50:01-05:00",
    "verified_on_rail": false
  }
}
CampoQué es
idId del evento, estable: úsalo para no procesar el mismo pago dos veces.
livemodetrue en una conexión de producción.
simulatedtrue solo en el aviso de prueba.
data.notification_idId del aviso en Firux.
data.amountPesos COP enteros (85000 = $85.000).
data.payer_nameQuién pagó, como lo escribe el banco.
data.bankEl banco del comercio que avisó el pago.
data.channelemail (correo del banco) o phone_notification (notificación del celular).
data.point_of_sale_idLa caja, si el comercio separa sus cajas; si no, null.
data.occurred_atLa hora del pago según el banco.
data.received_atCuándo lo recibió Firux.
data.verified_on_railSiempre false: es un aviso verificado, no un cobro confirmado en el riel.
data.payment_orderSi el pago cruzó con una orden de pago de esta conexión: {"id", "external_reference", "status", "payer_mismatch"}. Si no, null.

Órdenes de pago

Para cuando tu sistema sabe qué pago espera: la cuota de un préstamo, una factura, la mensualidad de un colegio o la cuenta de un cliente. Creas la orden con el valor, tu referencia y quién debe pagar. Quien paga le transfiere a la cuenta de quien recibe, como siempre. Cuando el Verificador recibe el aviso del banco con ese valor, la orden queda pagada y te llega payment_order.paid con tu external_reference.

En producción, desde el plan Verificador Plus o uno superior. Con una conexión de prueba, en cualquier plan del Verificador: puedes integrar antes de pagar.
curl -X POST https://api.firux.co/v1/payment_orders \
  -H "Authorization: Bearer firux_live_..." \
  -H "Idempotency-Key: cuota-123-3" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "external_reference": "CUOTA-123-3",
    "expected_payer_name": "Laura Gómez",
    "description": "Cuota 3 de 6",
    "unique_amount": true
  }'

Respuesta 201

{
  "id": "ord_...",
  "object": "payment_order",
  "status": "OPEN",
  "amount": 250000,
  "amount_to_pay": 250000,
  "currency": "COP",
  "external_reference": "CUOTA-123-3",
  "description": "Cuota 3 de 6",
  "metadata": null,
  "expected_payer_name": "Laura Gómez",
  "expected_payer_document": null,
  "expires_at": "2026-11-20T10:00:00-05:00",
  "paid_at": null,
  "payment": null,
  "livemode": true,
  "created_at": "2026-10-21T10:00:00-05:00"
}
CampoQué es
amountPesos COP enteros, de $1.000 a $100.000.000. Obligatorio.
external_referenceTu referencia: la cuota, la factura, el pedido. Obligatoria.
expected_payer_nameQuién debe pagar. Se compara con el nombre que trae el aviso del banco.
expected_payer_documentSolo para tu referencia: el aviso del banco no trae el documento de quien paga. Se guarda cifrado y sale enmascarado (****5678).
descriptionTexto libre, hasta 255 caracteres.
expires_atHasta cuándo esperas el pago. 30 días por defecto, hasta un año.
unique_amounttrue para que cada orden abierta tenga un valor distinto: si ya esperas otro pago por el mismo valor, esta se paga de 1 a 99 pesos más. Dile a quien paga el amount_to_pay.
metadataHasta 20 valores simples (texto, número o booleano), máximo 4 KB.

Cómo se cruza

El aviso del banco no trae tu referencia: trae el valor, el nombre de quien pagó y la hora. Por eso Firux cruza así:

  1. Busca las órdenes abiertas de esa cuenta con el valor exacto (amount_to_pay), sin vencer a la hora del pago.
  2. Si una espera ese nombre, queda pagada. Si varias lo esperan, la más vieja.
  3. Si hay una sola orden con ese valor y esperaba otro nombre, no queda pagada sola: queda por revisar (NEEDS_REVIEW) y te llega payment_order.review_required. Tú decides con confirm o reject.
  4. Si hay varias con ese valor y ninguna espera ese nombre, no se cruza ninguna. El pago le llega igual al comercio y se marca a mano. Con unique_amount no pasa.
  5. Un aviso paga una sola orden, y una orden se paga una sola vez.

Consultar, cancelar y probar

EndpointQué hace
GET/v1/payment_orders/{id}Una orden.
GET/v1/payment_orders?external_reference=...Las órdenes con tu referencia, de la más nueva a la más vieja.
POST/v1/payment_orders/{id}/cancelCancela una orden abierta. Una pagada no se cancela (409).
POST/v1/payment_orders/{id}/confirmEl pago de otra persona sí es de esta orden: queda PAID y te llega payment_order.paid. Solo para una orden NEEDS_REVIEW.
POST/v1/payment_orders/{id}/rejectEl pago no es de esta orden: vuelve a OPEN y el pago queda sin orden, para asignarlo a mano. Solo para una orden NEEDS_REVIEW.
POST/v1/payment_orders/{id}/simulate_paymentSolo con una conexión de prueba: la orden queda pagada y te llega payment_order.paid con "simulated": true. Con {"payer_mismatch": true}, simula que pagó otra persona: queda NEEDS_REVIEW.

Estados: OPEN, PAID, NEEDS_REVIEW (pagó otra persona), EXPIRED (pasó su expires_at) y CANCELLED. Si reenvías la misma external_reference y la orden sigue abierta con el mismo valor, te devolvemos la misma (200). Si ya está pagada o tiene otro valor, responde 409 con la orden en error.payment_order.

Lo que hay que saber
  • Quien recibe necesita el plan Verificador Plus o uno superior (para producción) y deja listo, una sola vez, el reenvío de los correos de su banco o la app en su celular.
  • Si el aviso llega sin el nombre y la orden era la única con ese valor, queda pagada. Si después llega el nombre y es de otra persona, pasa a NEEDS_REVIEW y te llega payment_order.review_required.
  • No es una confirmación en el riel: verified_on_rail siempre es false.
  • En una conexión de prueba las órdenes no se cruzan con pagos reales: usa simulate_payment.
  • Cada orden pagada cuenta una vez en el cupo de la API, junto con su payment.notified. Sin cupo el evento no sale, pero la orden queda pagada: consúltala con GET.
  • Si trabajas con varias personas o negocios que reciben (por ejemplo, prestamistas), cada uno tiene su cuenta de Firux y crea su conexión. Tu sistema guarda una llave por cuenta.

Los eventos de la orden

Llegan a la conexión que creó la orden, con los mismos headers, la misma firma y los mismos reintentos. data es la orden, como en GET, con el pago en payment.

payment_order.paid

{
  "id": "evt_...",
  "type": "payment_order.paid",
  "api_version": "2026-07-25",
  "created_at": "2026-10-25T09:12:04-05:00",
  "livemode": true,
  "simulated": false,
  "data": {
    "id": "ord_...",
    "object": "payment_order",
    "status": "PAID",
    "amount": 250000,
    "amount_to_pay": 250000,
    "currency": "COP",
    "external_reference": "CUOTA-123-3",
    "expected_payer_name": "Laura Gómez",
    "paid_at": "2026-10-25T09:12:03-05:00",
    "payment": {
      "notification_id": "ntf_...",
      "payer_name": "LAURA GOMEZ",
      "bank": "Nequi",
      "channel": "email",
      "occurred_at": "2026-10-25T09:11:58-05:00",
      "received_at": "2026-10-25T09:12:02-05:00",
      "payer_mismatch": false,
      "simulated": false,
      "verified_on_rail": false
    },
    "livemode": true
  }
}
  • data.payment.payer_mismatch en true: pagó alguien con otro nombre que el esperado y tú confirmaste la orden.
  • Para marcar la orden, usa este evento. Si la conexión también recibe los pagos verificados, el mismo pago llega como payment.notified, que puede salir antes del cruce y traer payment_order en null.
  • El id del evento es estable: úsalo para no procesar dos veces la misma orden.

payment_order.review_required

Llegó un pago con el valor de una de tus órdenes, pero de otra persona. data es la orden con "status": "NEEDS_REVIEW", el pago en payment y payment.payer_mismatch en true. Revisa quién pagó y responde con POST /v1/payment_orders/{id}/confirm o /reject. Si quieres aceptar siempre el pago de otra persona, confírmala apenas llegue el evento.

Firma y reintentos

Mismos headers y misma firma que charge.paid: Firux-Event-Type llega con payment.notified y Firux-Signature con HMAC-SHA256(secreto, "{timestamp}.{cuerpo_crudo}"). Tienes el código en Node.js y PHP en Verificar la firma.

Responde 2xx para confirmar. Si respondes error o hay timeout, Firux reintenta con backoff (aprox. 1m, 5m, 30m, 2h, 6h). Cada pago sale una sola vez por conexión.

Cupo por plan

Cada pago verificado cuenta una vez en el cupo mensual de la API del plan, aunque salga a varias conexiones:

PlanPagos verificados por API al mes
Verificador500
Verificador Plus1.500
Verificador Pro4.000
Verificador Empresa10.000

Al 80% y al 100% el comercio recibe un aviso. Sin cupo, el evento no sale hasta el mes siguiente o hasta que suba de plan.

Cómo cruzarlo con tus ventas

  • Guarda el id del evento o el notification_id: así el mismo pago nunca marca dos ventas.
  • Busca la venta pendiente con el mismo amount en una ventana corta alrededor de occurred_at (por ejemplo, 15 minutos).
  • Si hay varias del mismo valor, usa point_of_sale_id (la caja) y payer_name. Si aún hay duda, no marques ninguna sola: pídele a tu cajero que escoja.
  • Si no encuentras la venta, déjalo como "pago sin venta registrada" para revisarlo.
  • Para ventas grandes o despachos, mejor un cobro Bre-B con tu external_reference: se cruza solo y se confirma en el riel.

Aviso de prueba

En Ajustes → Conexiones API, el botón Enviar aviso de prueba manda a tu webhook un payment.notified de ejemplo, firmado como uno real, con "simulated": true y un notification_id que empieza por ntf_test_. No gasta cupo.

Uso aceptable para plataformas

Si conectas el Verificador a tu plataforma para ofrecerlo a tus propios clientes:

  • No lo ofreces para usos prohibidos: actividades ilícitas, préstamos por encima de la tasa de usura o "gota a gota", captar dinero del público sin autorización, cobranza que incumpla la Ley 2300 de 2023 o con amenazas, lavado de activos, financiación del terrorismo, fraude o suplantación.
  • Nos informas qué tipo de clientes atiendes y respondes nuestras solicitudes de información sobre ellos.
  • Podemos suspender tu conexión y las cuentas vinculadas ante indicios de un uso prohibido o por orden de una autoridad.
  • En las órdenes de pago, el nombre y el documento esperados los aporta tu plataforma o tu cliente, que responde por tener la autorización para tratarlos; Firux actúa como encargado.

El detalle está en las secciones 8A y 8B de los términos del Verificador de Pagos.

Soporte

¿Dudas con la integración? Escríbenos a soporte@firux.co.

Conectar con Firux Pay

Para plataformas que atienden muchos comercios: cada comercio conecta su cuenta con un botón, sin copiar llaves ni configurar avisos.

  • El comercio decide. Entra a Firux (o crea su cuenta ahí mismo), ve qué permisos pides y elige Permitir. Te puede desconectar cuando quiera desde Ajustes.
  • No retira ni mueve dinero. Ningún permiso permite retirar, dispersar ni mover saldo. La plata de cada cobro queda en el saldo del comercio; Firux no es titular de la cuenta recaudadora. Si cobras una comisión por venta, Firux la pasa a tu cuenta, hasta el máximo que el comercio autorizó.
  • Los endpoints de siempre. Con el acceso creas cobros y órdenes de pago en la misma API (https://api.firux.co/v1) y recibes los avisos firmados en una sola URL para todos tus comercios.
  • El estándar. Es OAuth 2.0 con código de autorización y PKCE (S256) obligatorio: cualquier librería de OAuth 2.0 sirve.

Cuándo usarlo

Si eresUsa
Una plataforma con muchos comercios: tienda en línea, POS, software de reservas, de facturación o de cobranzaConectar con Firux Pay
Un negocio que integra su propio sistemaLa llave de API de Ajustes, Conexiones API
Una plataforma que ya conecta comercios con su llave de APISiguen funcionando igual. Cuando quieras, cada comercio se pasa al botón con un clic.

Tu aplicación

Cada plataforma tiene una aplicación que Firux crea y aprueba: no se crean solas. Escríbenos a soporte@firux.co con:

  • El nombre que verá el comercio, tu logo (PNG, JPG o WebP) y el sitio de tu plataforma.
  • Tus direcciones de regreso exactas: https, completas y sin #. La que mandes al pedir el permiso tiene que ser idéntica a una de ellas.
  • Los permisos que necesitas y la URL de tus avisos.

Te damos el client_id (fxapp_...), el client_secret (fxsec_...) y el secreto de los avisos (whsec_...). Los secretos se muestran una sola vez y viven solo en tu servidor. Empieza con una aplicación de prueba; la de producción llega cuando tu integración funcione.

El flujo

  1. Tu servidor genera un code_verifier al azar, su code_challenge (SHA-256 en base64url) y un state, y los guarda en la sesión.
  2. El comercio toca tu botón y lo mandas a https://firux.co/oauth/authorize.
  3. Entra a Firux o crea su cuenta, ve qué permisos pides y elige Permitir. Solo el dueño o un administrador del negocio puede darlo.
  4. Firux lo devuelve a tu dirección de regreso con code y tu state.
  5. Tu servidor cambia el código por el acceso en POST /v1/oauth/token, con tu code_verifier.
  6. Con el acceso creas cobros a nombre de ese comercio y recibes sus avisos en tu URL.

Pedir el permiso

GEThttps://firux.co/oauth/authorize

https://firux.co/oauth/authorize?client_id=fxapp_...
  &redirect_uri=https%3A%2F%2Ftu-plataforma.com%2Ffirux%2Fvuelta
  &response_type=code
  &scope=charges%3Awrite%20charges%3Aread%20account%3Aread
  &state=8f2c1a...
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
ParámetroQué va
client_idEl de tu aplicación.
redirect_uriUna de tus direcciones de regreso, idéntica.
response_typeSiempre code.
scopeLos permisos, separados por un espacio. Solo los que tiene tu aplicación.
stateUn valor al azar que vuelve igual. Compáralo al regresar: protege al comercio de que lo conecten a una cuenta ajena.
code_challengebase64url (sin =) del SHA-256 de tu code_verifier (de 43 a 128 caracteres).
code_challenge_methodSiempre S256.
email, name, phoneOpcionales. Si el comercio todavía no tiene cuenta, solo llenan su registro; nunca lo crean solos.

Si el comercio permite, vuelve a https://tu-plataforma.com/firux/vuelta?code=...&state=.... Si cancela, vuelve con error=access_denied. Si falta algo de la petición, vuelve con error y error_description (invalid_request, invalid_scope o unsupported_response_type). Si el client_id no existe o no está aprobado, o la dirección de regreso no es una de las tuyas, Firux no lo devuelve a ningún lado: le muestra el error en su página.

Cambiar el código por el acceso

POST/v1/oauth/token · antes de 10 minutos; el código sirve una sola vez.

curl -X POST https://api.firux.co/v1/oauth/token \
  -u "fxapp_...:fxsec_..." \
  -d grant_type=authorization_code \
  -d code=EL_CODIGO \
  -d redirect_uri=https://tu-plataforma.com/firux/vuelta \
  -d code_verifier=TU_CODE_VERIFIER
{
  "access_token": "firux_oat_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "firux_ort_live_...",
  "scope": "charges:write charges:read account:read",
  "account_id": "0a1b2c3d-1111-7222-8333-444455556666",
  "connection_id": "0a1b2c3d-9999-7888-8777-666655554444",
  "livemode": true
}
  • account_id es el comercio y connection_id tu conexión con él: los mismos que llegan en cada aviso. Guárdalos junto a los tokens, cifrados.
  • Tu aplicación se identifica con Basic (client_id:client_secret) o con client_id y client_secret en el cuerpo. Las respuestas llevan Cache-Control: no-store.
  • Si el código se usa dos veces, lo que se emitió con él deja de servir.

Renovar el acceso

El acceso dura 1 hora. Renuévalo antes o cuando la API responda 401 token_expired:

curl -X POST https://api.firux.co/v1/oauth/token \
  -u "fxapp_...:fxsec_..." \
  -d grant_type=refresh_token \
  -d refresh_token=firux_ort_live_...
  • Cada renovación te da un refresh_token nuevo y el anterior deja de servir: guarda siempre el último.
  • Si alguien vuelve a usar uno viejo, se revoca la conexión completa y te llega connection.revoked con refresh_token_reused. Si dos procesos tuyos renuevan a la vez, pasa lo mismo: renueva desde un solo lugar.
  • La renovación vence a los 180 días sin uso. Si el comercio vuelve a dar el permiso, los tokens anteriores de esa conexión dejan de servir: guarda los nuevos.

Usar el acceso

Va como Bearer en los endpoints de siempre:

Authorization: Bearer firux_oat_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Permiso y endpointsLo que lee el comercio
charges:write
POST /charges y POST /charges/{id}/simulate_payment
Crear cobros Bre-B a nombre de tu negocio
charges:read
GET /charges y GET /charges/{id}
Ver si tus cobros se pagaron
account:read
GET /account y el aviso account.updated
Ver los datos básicos de tu cuenta: nombre, tope por cobro y plan
payment_orders:write
Todo /payment_orders
Crear órdenes de pago, para que los pagos a tu llave se crucen solos con tus pedidos
charges:fee
application_fee en POST /charges
Cobrar su comisión en cada venta, que va a su cuenta Firux, con el máximo por venta. Ver Tu comisión.
balance:read
GET /balance, GET /transactions y sus avisos
Ver tu saldo de Firux y tus movimientos, sin poder retirar. Ver El monedero.
  • Sin el permiso del endpoint: 403 con "type": "insufficient_scope" y el permiso que falta en error.scope.
  • Cada acceso solo ve los cobros y las órdenes de su conexión.
  • Ningún permiso permite retirar, dispersar ni mover saldo, y no hay endpoint para eso.

Tu comisión por venta

Si tu plataforma cobra una comisión por cada venta, Firux la separa sola: cuando se confirma el pago, la pasa del saldo del comercio a tu cuenta Firux. No tienes que cobrársela aparte.

  • Necesitas el permiso charges:fee, junto con charges:write, y tu cuenta Firux en el plan Cobros Empresa. Lo activamos en tu aplicación con esa cuenta (la que recibe la comisión) y tu máximo por venta. Conectar con Firux Pay sin comisión sigue gratis.
  • El comercio ve ese máximo al dar el permiso: "Tu plataforma podrá crear cobros Bre-B a nombre de Ferretería La 52 y ver si se pagaron. También cobrará su comisión, de hasta el 3 % de cada venta, que va a su cuenta Firux. Fuera de su comisión, no podrá retirar ni mover tu dinero."
  • En POST /charges mandas application_fee (pesos enteros) o application_fee_percent (porcentaje de la venta, con hasta dos decimales), nunca los dos. El porcentaje se calcula en pesos, hacia abajo.
curl -X POST https://api.firux.co/v1/charges \
  -H "Authorization: Bearer firux_oat_live_..." \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount": 120000, "external_reference": "pedido-1042", "payment_method": "llave", "application_fee": 3600}'
  • El cobro y el aviso charge.paid traen application_fee en pesos, o null si no pusiste comisión.
  • Sale de lo que recibe el comercio, después de la tarifa de Firux. Si pasa el máximo que autorizó o lo deja sin nada de la venta, la API responde 422 application_fee_too_high. Sin el permiso, 403 insufficient_scope.
  • Se cobra si la conexión sigue activa cuando llega el pago. Si el comercio te desconecta antes, ese pago queda completo para él.
  • Si tu cuenta deja el plan Cobros Empresa, tus cobros salen sin comisión (application_fee en null) y el comercio se queda con el 100 % hasta que vuelvas al plan.
  • Con un acceso de prueba la comisión se revisa y sale en el cobro y en el aviso, sin mover dinero.
  • Si el comercio devuelve un pago, tu comisión no se devuelve.
  • Tu comisión queda en el saldo de tu cuenta Firux y la retiras desde su panel, como cualquier saldo. Por la API no se retira nada.

El monedero de tus comercios

Con el permiso balance:read muestras en tu app el saldo de Firux de cada comercio conectado y sus movimientos, y te llegan los avisos de su saldo. Es solo lectura: el retiro sigue en el panel de cada comercio, con su verificación. Tu cuenta Firux tiene que estar en el plan Cobros Empresa, como para la comisión.

El saldo es de cada comercio: tu plataforma no puede retenerlo, congelarlo ni condicionar sus retiros, y la API no tiene ninguna forma de bloquearlo. Lo dicen los términos de uso de la API.

GET/v1/balance

{
  "object": "balance",
  "account_id": "0a1b2c3d-1111-7222-8333-444455556666",
  "available": 1250000,
  "in_transit": 300000,
  "currency": "COP",
  "free_payouts_left_today": 1,
  "last_movement": {
    "id": "mov_0a1b...",
    "object": "balance_transaction",
    "type": "charge",
    "amount": 120000,
    "balance_after": 1250000,
    "currency": "COP",
    "charge_id": "chg_9f8c...",
    "payout_id": null,
    "reference": "API-7K2M9Q",
    "created_at": "2026-11-03T10:15:00-05:00"
  },
  "withdraw_url": "https://firux.co/payouts",
  "livemode": true
}
  • available: lo que el comercio puede retirar hoy, en pesos. in_transit: lo que ya salió de su saldo hacia un banco (retiros, devoluciones y dispersiones en proceso).
  • free_payouts_left_today: los retiros gratis que le quedan hoy. Los demás tienen su tarifa.
  • withdraw_url abre el panel del comercio en la pantalla de retiro. Ponlo detrás de un botón "Retirar en Firux": el retiro nunca se hace por API.

GET/v1/transactions · del más nuevo al más viejo, hasta 100 por página.

ParámetroQué va
from, toDías de Colombia, como 2026-11-01. Opcionales.
typeUn solo tipo, como charge. Opcional.
limitDe 1 a 100. Por defecto, 25.
starting_afterEl id del último movimiento que ya tienes, para la página siguiente. Mientras has_more sea true, hay más.
typeQué es
chargeUn cobro pagado que entró al saldo.
firux_feeLa tarifa de Firux por ese cobro, con su IVA.
platform_feeLa comisión de una plataforma conectada.
payout, payout_feeUn retiro al banco del comercio y su tarifa.
refund, refund_feeUna devolución a quien pagó y su tarifa.
dispersion, dispersion_fee, gmfUn pago de Dispersiones, su tarifa y el 4x1.000.
payout_reversal, fee_reversal, gmf_reversalLo que volvió al saldo porque un pago no salió.
split_sent, split_received, platform_fee_received, plan_payment, adjustmentRepartos, comisiones recibidas, el pago del plan con el saldo y ajustes.

Los avisos del monedero, en tu URL de siempre: balance.updated (el mismo cuerpo de GET /v1/balance, cada vez que cambia el saldo; varios cambios seguidos llegan en un solo aviso), payout.completed y payout.failed:

{
  "type": "payout.completed",
  "account_id": "0a1b2c3d-1111-7222-8333-444455556666",
  "connection_id": "0a1b2c3d-9999-7888-8777-666655554444",
  "data": {
    "payout_id": "po_3c9a...",
    "object": "payout",
    "type": "withdrawal",
    "status": "completed",
    "amount": 500000,
    "fee": 1071,
    "currency": "COP",
    "destination": "300 *** 4567",
    "created_at": "2026-11-03T10:15:00-05:00",
    "completed_at": "2026-11-03T10:15:09-05:00"
  }
}
  • type: withdrawal (un retiro), refund (una devolución) o dispersion. En payout.failed va failed_at, y el monto y la tarifa volvieron al saldo.
  • La llave de destino va enmascarada: nunca completa.
  • Si tu cuenta deja Cobros Empresa, el monedero responde 403 plan_required y sus avisos dejan de llegar hasta que vuelvas al plan.

La cuenta del comercio

GET/v1/account · permiso account:read. También funciona con la llave de API.

{
  "id": "0a1b2c3d-1111-7222-8333-444455556666",
  "object": "account",
  "name": "Ferretería La 52",
  "verification": { "status": "verified" },
  "limits": { "minimum": 2000, "per_charge": 12000000, "raises_when_verified": false },
  "capabilities": { "charges": true, "llave_dinamica": false },
  "verificador": { "plan": "aviso_plus", "payment_orders": true, "verified_payments_remaining": 412 },
  "livemode": true
}
  • verification.status: verified, limited (cobra con un tope menor hasta verificar su identidad), in_review o blocked.
  • limits.per_charge: el tope por cobro de hoy, en pesos. Si raises_when_verified es true, sube cuando verifica su identidad.
  • verificador.payment_orders: si es false, muéstrale al comercio que las órdenes de pago vienen con el plan Verificador Plus o uno superior.
  • Cuando algo de esto cambia (salvo el cupo que queda), te llega account.updated.

Avisos de la plataforma

Una sola URL para todos tus comercios, firmada con el secreto whsec_ de tu aplicación. Los headers, la firma y los reintentos son los de siempre: mira Verificar la firma. Cada aviso trae arriba account_id (el comercio) y connection_id (tu conexión con él).

EventoCuándo llega
charge.paidUn cobro que creaste se pagó (confirmado en el riel).
charge.expiredUn cobro que creaste venció sin pago.
payment_order.paid y payment_order.review_requiredUna orden de pago que creaste se pagó, o la pagó otra persona.
account.updatedCambió la cuenta del comercio. Solo con el permiso account:read.
connection.revokedEl comercio te desconectó o se revocó la conexión.
balance.updatedCambió el saldo del comercio. Solo con el permiso balance:read.
payout.completed y payout.failedUn retiro, una devolución o una dispersión del comercio salió, o no salió. Solo con balance:read.

Eliges los avisos con tu aplicación. payment.notified (todos los pagos que el Verificador le avisa al comercio) no llega a las plataformas: mostraría pagos que no son tuyos.

{
  "id": "evt_3c9a...",
  "type": "connection.revoked",
  "api_version": "2026-07-25",
  "created_at": "2026-10-30T10:15:00-05:00",
  "livemode": true,
  "simulated": false,
  "account_id": "0a1b2c3d-1111-7222-8333-444455556666",
  "connection_id": "0a1b2c3d-9999-7888-8777-666655554444",
  "data": {
    "connection_id": "0a1b2c3d-9999-7888-8777-666655554444",
    "account_id": "0a1b2c3d-1111-7222-8333-444455556666",
    "application": { "client_id": "fxapp_...", "name": "Tu plataforma" },
    "reason": "merchant_disconnected",
    "revoked_at": "2026-10-30T10:15:00-05:00"
  }
}

Desconexión

  • El comercio te desconecta en Ajustes, Aplicaciones conectadas: tus tokens dejan de servir al instante y te llega connection.revoked con merchant_disconnected.
  • Tú desconectas con POST/v1/oauth/revoke y un token de la conexión (token=..., con tus credenciales): llega connection.revoked con application_revoked. Responde 200 aunque el token no exista.
  • Desconectar no toca los cobros pagados ni el saldo del comercio.
  • Si el comercio vuelve a conectarse, es una conexión nueva, con otro connection_id.

Ejemplo en PHP

1. Mandar al comercio a dar el permiso

<?php
session_start();
$b64url = fn (string $b) => rtrim(strtr(base64_encode($b), '+/', '-_'), '=');
$verificador = $b64url(random_bytes(32));
$_SESSION['firux_verificador'] = $verificador;
$_SESSION['firux_state'] = bin2hex(random_bytes(16));

header('Location: https://firux.co/oauth/authorize?' . http_build_query([
    'client_id' => getenv('FIRUX_CLIENT_ID'),
    'redirect_uri' => 'https://tu-plataforma.com/firux/vuelta',
    'response_type' => 'code',
    'scope' => 'charges:write charges:read account:read',
    'state' => $_SESSION['firux_state'],
    'code_challenge' => $b64url(hash('sha256', $verificador, true)),
    'code_challenge_method' => 'S256',
], '', '&', PHP_QUERY_RFC3986));

2. La vuelta: cambiar el código por el acceso

<?php
session_start();
if (! hash_equals($_SESSION['firux_state'] ?? '', $_GET['state'] ?? '')) {
    http_response_code(400);
    exit('El state no coincide.');
}
if (isset($_GET['error'])) {
    exit('El comercio no dio el permiso.');
}

$ch = curl_init('https://api.firux.co/v1/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FIRUX_CLIENT_ID') . ':' . getenv('FIRUX_CLIENT_SECRET'),
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'authorization_code',
        'code' => $_GET['code'],
        'redirect_uri' => 'https://tu-plataforma.com/firux/vuelta',
        'code_verifier' => $_SESSION['firux_verificador'],
    ]),
]);
$token = json_decode(curl_exec($ch), true);
// Guarda cifrados: account_id, connection_id, access_token, refresh_token y cuándo vence.

Ejemplo en Node.js

Con Express y el fetch de Node 18 o superior:

const crypto = require("crypto");
const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const basic = "Basic " + Buffer.from(`${process.env.FIRUX_CLIENT_ID}:${process.env.FIRUX_CLIENT_SECRET}`).toString("base64");

app.get("/firux/conectar", (req, res) => {
  const verificador = b64url(crypto.randomBytes(32));
  req.session.firux = { verificador, state: b64url(crypto.randomBytes(16)) };
  const url = new URL("https://firux.co/oauth/authorize");
  url.search = new URLSearchParams({
    client_id: process.env.FIRUX_CLIENT_ID,
    redirect_uri: "https://tu-plataforma.com/firux/vuelta",
    response_type: "code",
    scope: "charges:write charges:read account:read",
    state: req.session.firux.state,
    code_challenge: b64url(crypto.createHash("sha256").update(verificador).digest()),
    code_challenge_method: "S256",
  });
  res.redirect(url.toString());
});

app.get("/firux/vuelta", async (req, res) => {
  if (!req.session.firux || req.query.state !== req.session.firux.state) return res.status(400).send("El state no coincide.");
  if (req.query.error) return res.send("El comercio no dio el permiso.");
  const r = await fetch("https://api.firux.co/v1/oauth/token", {
    method: "POST",
    headers: { Authorization: basic, "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code: req.query.code,
      redirect_uri: "https://tu-plataforma.com/firux/vuelta",
      code_verifier: req.session.firux.verificador,
    }),
  });
  const token = await r.json();
  // Guarda cifrados: account_id, connection_id, access_token y refresh_token.
  res.send("Conectado");
});

// Renovar: el refresh_token nuevo reemplaza al anterior.
async function renovar(refreshToken) {
  const r = await fetch("https://api.firux.co/v1/oauth/token", {
    method: "POST",
    headers: { Authorization: basic, "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken }),
  });
  return r.json();
}

Modo prueba

  • Una aplicación de prueba solo da accesos firux_oat_test_.... Un acceso de prueba nunca opera una conexión de producción, ni al revés.
  • Con un acceso de prueba, POST /v1/charges/{id}/simulate_payment manda charge.paid firmado a tu URL de avisos sin mover dinero real. Con uno de producción no funciona.
  • Con un acceso de prueba, GET /v1/balance da el saldo en cero, GET /v1/transactions una lista vacía y los avisos del monedero no llegan: el monedero solo muestra plata de verdad.
  • Para probar el permiso, crea gratis una cuenta de negocio en firux.co y conéctala con tu botón.

Colección de Postman

Descargar la colección

  1. Impórtala en Postman y llena sus variables: client_id, client_secret y redirect_uri.
  2. Para el código, abre en tu navegador la dirección de Pedir el permiso con tu code_challenge, da el permiso con tu cuenta de prueba y copia el code de la vuelta. Si prefieres que Postman haga el permiso solo (Authorization, OAuth 2.0, "Authorization Code (With PKCE)"), pídenos agregar https://oauth.pstmn.io/v1/callback a las direcciones de regreso de tu aplicación de prueba.
  3. Corre "Cambiar el código por el acceso": guarda access_token y refresh_token en las variables. Después, la cuenta, un cobro, su consulta, la simulación del pago, la renovación y la revocación.

El botón "Conectar con Firux Pay"

Así se ve:

Conectar con Firux Pay

<a href="https://tu-plataforma.com/firux/conectar" class="firux-conectar">
  <img src="https://developers.firux.co/images/logo-64.png" alt="" width="20" height="20">
  Conectar con Firux Pay
</a>
<style>
  .firux-conectar { display: inline-flex; align-items: center; gap: 10px; padding: 10px 18px;
    border-radius: 10px; background: #0742F2; color: #fff; font: 600 15px/1.2 system-ui, sans-serif;
    text-decoration: none; }
  .firux-conectar img { background: #fff; border-radius: 6px; padding: 2px; }
  .firux-conectar:hover { background: #0535c9; }
</style>
  • El texto es "Conectar con Firux Pay". No cambies el logo ni sus colores, y no le ocultes al comercio que su cuenta es de Firux: son reglas de los términos de uso de la API.
  • El botón lleva a tu servidor, que arma la dirección con PKCE y el state. El client_secret nunca va en el navegador ni en una app.
  • Al lado, una línea basta: "Cobra por Bre-B y recibe la confirmación en tu sistema".

Errores

Error y dónde llegaQué hacer
access_denied
La vuelta
El comercio canceló. Ofrécele intentarlo de nuevo.
invalid_request, invalid_scope
La vuelta
Revisa state, PKCE y que pidas solo los permisos de tu aplicación.
400 invalid_grant
/oauth/token
Código vencido, usado o de otra dirección de regreso; code_verifier que no corresponde; o renovación vencida o reemplazada. Pide el permiso otra vez.
401 invalid_client
/oauth/token
El client_id, el secreto o la aprobación de tu aplicación.
429
/oauth/token
Demasiados intentos: hasta 30 por minuto por aplicación y dirección IP.
401 token_expired
La API
Renueva el acceso.
401 token_revoked
La API
El comercio te desconectó o se revocó la conexión: pídele que conecte de nuevo.
403 insufficient_scope
La API
Tu acceso no tiene el permiso de ese endpoint (error.scope).
422 application_fee_too_high
POST /charges
La comisión pasa el máximo que autorizó el comercio o lo deja sin nada de la venta. Baja la comisión.
403 plan_required
El monedero
Tu cuenta Firux no está en el plan Cobros Empresa.
403 oauth_required
El monedero
El monedero es para accesos de Conectar con Firux Pay, no para la llave de API.

Soporte

¿Quieres tu aplicación o tienes dudas? Escríbenos a soporte@firux.co. Todo esto está también en el OpenAPI, con el esquema firuxOAuth y los permisos de cada endpoint.