API
Confirmar pago
Registra el cobro de una orden abierta y la salda. Acepta varios medios de pago en un mismo cobro y también los intentos rechazados.
POST
Cierra el ciclo del pago diferido: la orden nació abierta, la cocina ya trabajó, y acá llega el
cobro. La orden pasa a
COMPLETED y arranca la facturación cuando lo aprobado llega exacto al
total de la orden.
Un cobro con varias piezas, en una sola llamada. Si repartís la cuenta entre efectivo y
tarjeta, mandá las dos piezas en la misma llamada: las piezas aprobadas tienen que sumar
exacto el total de la orden. Un cobro que no cuadra se rechaza entero y no se registra nada —
consolidá tus parciales antes de mandarlos.Reintentar es seguro y esperado: reenviá el envío completo y la idempotencia por
transaction_id se encarga del resto.Autenticación
string
requerido
Tu API key de Fire con scope
orders:write. La key debe ser vendor-scoped — las keys sin
vendorId se rechazan con 403.Path params
string
requerido
Cualquiera de las tres referencias públicas de la orden:
Es el mismo conjunto que aceptan Obtener orden y
Cancelar orden.
Cuerpo
object[]
requerido
Los medios con los que cobraste la orden. Entre 1 y 20 piezas. Cada objeto se guarda tal cual lo
enviaste; abajo solo están los campos que Fire lee.
string
requerido
Estado del intento. Cuentan como cobrado:
APPROVED, AUTHORIZED, CAPTURED, PAID,
SUCCESS, SUCCEEDED (sin distinguir mayúsculas).Cualquier otro valor se trata como rechazo, incluso si no lo reconocemos. Es deliberado:
facturar un cobro que no ocurrió no tiene vuelta atrás, mientras que no saldar algo que sí se
cobró se resuelve con otro envío.string
requerido
Identificador de la transacción. Es la clave de idempotencia: reenviar el mismo no vuelve a
cobrar ni a facturar. Si tu medio no lo genera, Fire usa
payments[].uid.number
requerido
Monto de esta pieza, decimal. Debe ser mayor que cero. Si no viene, Fire cae al
payments[].total
del nivel superior.string
requerido
Moneda de la pieza. Todas las piezas aprobadas deben compartir la misma — incluidas las de
llamadas anteriores de la misma orden. Si no viene, Fire cae al
payments[].currency_code del
nivel superior.string
Motivo del rechazo, con un código de Motivos de rechazo.
Solo aplica cuando
transaction_status no es aprobado.El código de tu adquirente (51, do_not_honor) hay que traducirlo de tu lado al del catálogo:
Fire no guarda los códigos de cada proveedor. Si mandás uno que no está, se acepta y se guarda,
pero vuelve con resolvedTo: null y queda fuera de tus métricas agrupadas.string
Medio de pago (
CASH, CREDIT, DEBIT, PIX…). Se usa para la facturación y las métricas.Petición
Qué hace Fire con lo que enviás
Solo las piezas aprobadas suman y saldan. Las rechazadas se registran para tus métricas, no suman y nunca bloquean el cobro.Qué pasó con cada rechazo
Cada pieza rechazada vuelve endeclines[], con lo que enviaste y si lo encontramos en el catálogo.
exceedsOrderTotal: true quiere decir que el monto que intentaste cobrar supera el total de la
orden. No exigimos que cada pieza sea igual al total —en un cobro repartido, $20 sobre $35,90 es
legítimo— pero superarlo nunca lo es: casi siempre significa que se está cobrando otra orden. El
rechazo es tu aviso gratis, porque si el siguiente intento aprueba se saldaría un monto que no
corresponde.
resolvedTo: null quiere decir que ese código no existe en el catálogo — en el ejemplo, se mandó
el código crudo del adquirente en vez del de Fire. El rechazo se registró igual y el valor quedó
guardado, pero no aparece en nada agrupado por motivo.
Una orden cerrada no acepta nada más
Una orden recibe cobros mientras está abierta. Una vez cerrada está cerrada, sin importar cómo llegó a estarlo. Una pieza que nunca vio se rechaza y no se registra nada — ni aprobada ni rechazada. El código de error te dice por qué está cerrada, y las dos cosas piden acciones distintas:
Lo que separa un rechazo de un reintento es el
transaction_id, no el estado de la orden:
Cuando el cobro salda
Saldar es lo que completa la orden, así que ahí es cuando Fire emiteorder.completed — la orden nació OPEN y recién ahora
terminó. La respuesta lo informa como flowsTriggered.
flowsTriggered: 0 no es un error de cobro. Significa una de tres cosas:
Esa última fila es deliberada. Si Fire respondiera con error porque no pudo encolar un
evento, reintentarías un cobro que ya entró. El dinero manda sobre el aviso.
Una orden con pago diferido ya emitió su documento fiscal al abrirse, y vuelve a pasar
por el paso fiscal en
order.completed. Fire detecta el documento existente y saltea
la segunda emisión — no te llegan dos facturas.Idempotencia
Cada pieza se identifica por sutransaction_id dentro de la orden. Podés reintentar sin miedo:
- Reenviar el cobro completo →
duplicate. No se vuelve a saldar ni a facturar. - Reenviar después de un timeout → reenviá el envío entero. Un cobro incompleto nunca se
registró, y cualquier pieza que sí haya entrado se ignora por su
transaction_id.
Validaciones
Todas devuelven400 salvo donde se indique. Cada rechazo trae un code además del mensaje:
ramificá por el código, no por el texto — el mensaje está escrito para leerse y se puede reescribir, el
código es contrato.
Los campos que Fire no conoce se aceptan y se guardan: podés enviar tu objeto de pago completo
sin recortarlo. La moneda de una pieza rechazada no invalida el envío, porque no suma.
Respuestas
Relacionado
Motivos de rechazo
Catálogo agrupado para clasificar los intentos rechazados.
Obtener orden
Consultá el estado y el total antes de cobrar.