Cobrar desde un canal

Estos endpoints ya están implementados y verificados contra el sandbox de DSI (creación del pago con link real y cierre del estado por webhook). Falta el host público definitivo de los callbacks para operar en producción; por eso el grupo sigue marcado como Pronto.

Un canal (POS, Kiosco, Web o App) usa estos endpoints para cobrar a través de PayBridge. El canal envía solo los datos de la transacción (orden, monto, método, storeId, terminalId); PayBridge resuelve el proveedor, crea el pago y devuelve un link de pago que el canal le muestra al cliente. El estado final llega por el webhook de estado. La configuración del comercio (credenciales, métodos, terminales) ya vive en el proveedor vía el config sync, por eso el cobro viaja lean.

Autenticación

string

requerido

API key de Fire vendor-scoped con el scope paybridge:charge. El accountId y el vendorId se derivan de la key; una key sin vendor responde 403.

Todas las respuestas viajan envueltas en { "success": true, "data": { … } }.

Cobro e intentos

Cobro (intent)

El cobro de una orden: monto total, moneda, tienda, terminal y canal. Es lo que el canal crea una sola vez.

Intento (attempt)

Cada intento de pago dentro del cobro. Ocupa un cupo (slot): un cupo por método en el pago mixto, y un intento nuevo en el mismo cupo cuando se reintenta.

Estados del cobro:

Estado	Significado
`processing`	Hay un intento en curso, todavía sin link para el cliente.
`requires_action`	Hay un link de pago esperando al cliente.
`partially_paid`	Se cobró parte del total (pago mixto en curso).
`succeeded`	El total quedó cobrado.
`failed`	Todos los intentos fallaron y no hay ninguno activo.
`canceled`	Todos los intentos se cancelaron.
`pending` / `reversed`	Reservados (sin intentos aún / reverso total).

Estados del intento:

Estado	Significado
`created`	Registrado en Fire, todavía sin enviar al proveedor.
`requires_redirect`	El proveedor devolvió el `paymentLink`: hay que mostrárselo al cliente.
`succeeded`	Pago aprobado (lo confirma el webhook).
`failed`	No se pudo crear el pago o el proveedor lo rechazó; el motivo va en `errorDescription`.
`canceled`	El intento se canceló (link sin pagar o vencido).
`solving`	Reembolso en curso, esperando la confirmación del proveedor.
`refunded`	Reembolso confirmado.
`processing` / `requires_action`	Reservados.

Flujo

Crear el cobro

El canal llama a POST /intents con la orden, el monto, el método y su storeId/terminalId. PayBridge crea el pago en el proveedor y devuelve el paymentLink en el primer intento.

Mostrar el link

El canal muestra el paymentLink (redirect, QR o iframe) para que el cliente pague.

Conocer el resultado

Fire recibe el estado del proveedor por webhook y actualiza el intento y el cobro. El canal lo consulta con GET /intents/{intentId}.

Cerrar el caso

Si el cliente no paga, cancela el intento. Si el pago ya está aprobado, reembolsa. Si falla o falta plata, agrega otro intento con POST /intents/{intentId}/pay.

Endpoints

Operación	Método	Endpoint
Crear cobro	`POST`	`/api/v1/external/paybridge/intents`
Consultar cobro	`GET`	`/api/v1/external/paybridge/intents/{intentId}`
Agregar intento (mixto o reintento)	`POST`	`/api/v1/external/paybridge/intents/{intentId}/pay`
Cancelar intento	`POST`	`/api/v1/external/paybridge/attempts/{attemptId}/cancel`
Reembolsar intento	`POST`	`/api/v1/external/paybridge/attempts/{attemptId}/refund`

Crear cobro

POST /api/v1/external/paybridge/intents

string

requerido

Identificador de la orden en el sistema del canal (máx. 80 caracteres). Es la clave de idempotencia: repetir el mismo valor devuelve el cobro ya creado, sin duplicarlo.

string

requerido

Código del método de pago en Fire (p. ej. deuna, rutpay). Debe estar activo en el catálogo, si no responde 400.

number

requerido

Monto total a cobrar, en la unidad mayor de la moneda (p. ej. 19.90).

string

requerido

Moneda ISO 4217 de 3 letras (USD, CLP, COP, ARS, VES, BRL).

string

requerido

UUID de la tienda en Fire. Viaja al proveedor como branchOffice.

string

requerido

Id de la terminal POS o del dispositivo de kiosco. Viaja al proveedor como pointOfSale.

string

requerido

Canal que origina el cobro: POS, KIOSK, WEB o APP.

string

País del cobro (ISO alpha-2). Se puede omitir si el método pertenece a un solo país: en ese caso Fire lo deriva. En métodos multi-país es obligatorio; sin él, el intento queda failed porque no se puede resolver la conexión del país.

object

Datos opcionales del pagador. Se reenvían al proveedor cuando los pide.

Mostrar customer

string

Nombre completo; se parte en nombre y apellido.

string

Identificación fiscal, según el país.

string

object

El cobro con todos sus intentos.

Mostrar intent

string

UUID del cobro en Fire.

string

Estado del cobro.

number

Suma de los intentos aprobados.

string

string | null

string

string | null

Reservado; hoy siempre null.

object[]

Mostrar attempt

string

number

Cupo del pago mixto (1, 2, 3…).

number

Nº de reintento dentro del cupo.

string

Estado del intento.

number

string

string | null

Link para mostrarle al cliente.

string | null

Motivo del fallo, si hubo.

{
  "externalOrderId": "ORD-2026-001234",
  "methodCode": "deuna",
  "amount": 19.90,
  "currency": "USD",
  "storeId": "3f6c1b6e-52b1-4f0e-9c2a-2b7d5e8a1c40",
  "terminalId": "EC-D0123-POS-1",
  "channel": "KIOSK",
  "country": "EC",
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "document": "0912345678" }
}

{
  "success": true,
  "data": {
    "intent": {
      "intentId": "9d1f0b62-3c77-4a1e-9f2b-11a0d8c4e5aa",
      "externalOrderId": "ORD-2026-001234",
      "status": "requires_action",
      "amountTotal": 19.90,
      "amountPaid": 0,
      "currency": "USD",
      "storeId": "3f6c1b6e-52b1-4f0e-9c2a-2b7d5e8a1c40",
      "terminalId": "EC-D0123-POS-1",
      "channel": "KIOSK",
      "expiresAt": null,
      "attempts": [
        {
          "attemptId": "6b2c9a54-8d31-4f77-b0c6-9e3a1f5d2b88",
          "slot": 1,
          "attemptNumber": 1,
          "methodCode": "deuna",
          "status": "requires_redirect",
          "amount": 19.90,
          "currency": "USD",
          "paymentLink": "https://checkout.example.com/deuna/9f8e7d6c",
          "errorDescription": null
        }
      ]
    }
  }
}

Si el proveedor rechaza la creación del pago, la respuesta sigue siendo 201: el cobro existe y su intento queda en failed con el motivo en errorDescription. Revisa el estado del intento, no solo el código HTTP.

Consultar cobro

GET /api/v1/external/paybridge/intents/{intentId} Devuelve el estado local del cobro y todos sus intentos. No llama al proveedor: el estado se mantiene al día con el webhook.

string

requerido

UUID del cobro devuelto al crearlo. Solo se ven los cobros de la cuenta de la API key; el de otra cuenta responde 404.

object

Mismo objeto que devuelve la creación.

{
  "success": true,
  "data": {
    "intent": {
      "intentId": "9d1f0b62-3c77-4a1e-9f2b-11a0d8c4e5aa",
      "externalOrderId": "ORD-2026-001234",
      "status": "succeeded",
      "amountTotal": 19.90,
      "amountPaid": 19.90,
      "currency": "USD",
      "storeId": "3f6c1b6e-52b1-4f0e-9c2a-2b7d5e8a1c40",
      "terminalId": "EC-D0123-POS-1",
      "channel": "KIOSK",
      "expiresAt": null,
      "attempts": [
        {
          "attemptId": "6b2c9a54-8d31-4f77-b0c6-9e3a1f5d2b88",
          "slot": 1,
          "attemptNumber": 1,
          "methodCode": "deuna",
          "status": "succeeded",
          "amount": 19.90,
          "currency": "USD",
          "paymentLink": "https://checkout.example.com/deuna/9f8e7d6c",
          "errorDescription": null
        }
      ]
    }
  }
}

Agregar un intento

POST /api/v1/external/paybridge/intents/{intentId}/pay Sirve para dos cosas: reintentar un método que falló y pagar mixto (varios métodos en la misma orden).

string

requerido

UUID del cobro.

string

requerido

Método del intento nuevo.

number

Monto del intento. Si se omite, se usa lo que falta (amountTotal - amountPaid).

number

Cupo al que pertenece el intento. Si se omite, se abre un cupo nuevo (pago mixto). Para reintentar, manda el slot del intento que falló. Un cupo con un intento activo responde 400.

object

El cobro actualizado, con el intento nuevo dentro de attempts.

{ "methodCode": "deuna", "slot": 1 }

{ "methodCode": "rutpay", "amount": 5.00 }

Un cobro ya cerrado (succeeded, canceled o reversed) no acepta intentos nuevos: responde 400.

Cancelar intento

POST /api/v1/external/paybridge/attempts/{attemptId}/cancel Cancela un intento activo cuyo link todavía no se pagó (o venció).

string

requerido

Id del intento a cancelar.

object

El cobro actualizado; el intento queda en canceled.

El proveedor solo acepta la cancelación cuando el link ya está esperando el pago (waitingPayment). Un intento recién creado suele responder “no aplica para cancelación”: en ese caso Fire no marca el intento como cancelado y devuelve el error, para no dar por cancelado un pago que sigue vivo del otro lado.

Reembolsar intento

POST /api/v1/external/paybridge/attempts/{attemptId}/refund Reembolsa un intento ya aprobado (succeeded).

string

requerido

Id del intento aprobado.

object

El cobro actualizado; el intento pasa a solving hasta que el proveedor confirme.

Solo reembolso total. El proveedor no admite montos parciales: si mandas amount en el body, la respuesta es 400. El reembolso es asíncrono — el intento queda en solving y pasa a refunded cuando llega el webhook refundPayment (o vuelve a solving con el motivo si llega refundFailed).

Errores

HTTP	`error`	Cuándo
`400`	`VALIDATION_ERROR`	Body inválido (falta un campo, `storeId` no es UUID, moneda de 4 letras…).
`400`	`DOMAIN_ERROR`	Método inactivo, cobro cerrado, cupo con intento activo, reembolso parcial, intento no cancelable.
`403`	`FORBIDDEN`	API key sin scope `paybridge:charge` o sin vendor.
`404`	`NOT_FOUND`	El cobro o el intento no existe, o es de otra cuenta.

Todos los errores traen { "success": false, "error": "…", "message": "…" }.

Relacionado

Webhook de estado

Cómo el proveedor le avisa a Fire que el pago se aprobó, se canceló o se reembolsó.

Config sync hacia DSI

Cómo la config del comercio llega al proveedor para que el cobro sea lean.

Métodos soportados por país

Qué métodos puede cobrar cada país y con qué código.

Disponibilidad de métodos

Qué método está encendido en cada tienda, dispositivo y canal.

​Autenticación

​Cobro e intentos

Cobro (intent)

Intento (attempt)

​Flujo

​Endpoints

​Crear cobro

​Consultar cobro

​Agregar un intento

​Cancelar intento

​Reembolsar intento

​Errores

​Relacionado

Webhook de estado

Config sync hacia DSI

Métodos soportados por país

Disponibilidad de métodos

Autenticación

Cobro e intentos

Flujo

Endpoints

Crear cobro

Consultar cobro

Agregar un intento

Cancelar intento

Reembolsar intento

Errores

Relacionado