Elige tu integración
El Merchant cobra en cinco escenarios. Todos comparten las mismas reglas: tu sistema nunca ve una tarjeta ni una clave de pago, cada cobro termina en un veredicto (APROBADA, RECHAZADA, EN_DUDA, CANCELADA o EXPIRADA) y un EN_DUDA nunca se trata como rechazo.
¿Dónde ocurre la venta?
| Escenario | Usa | Quién inicia el cobro | Cómo te enteras |
|---|---|---|---|
| Tienda web o app; el cliente paga solo | Checkout y SDK web | Tu servidor crea una sesión; el cliente elige el medio | Webhook firmado checkout.sesion |
| ERP, despacho o delivery; un terminal cobra lejos de tu sistema | Cobro empujado | Tu servidor crea una intención y la empuja a un terminal | Consulta de la intención o suscripción de eventos |
| Caja registradora en la misma red que el terminal | API ECR del terminal (Beta) | La caja llama al terminal | Respuesta síncrona del terminal |
| Caja de escritorio en Windows | FINORA Pago | La caja llama a FINORA Pago en el mismo equipo | Respuesta local o callback firmado |
| Flota de terminales (TI del comercio) | TMS | Tu software ordena comandos al terminal | Estado del comando y latido del terminal |
Recorrido 1: cobro en línea con el checkout
Tu servidor crea la sesión con la clave API; el navegador solo recibe un token de esa sesión. El cliente paga en la página alojada o en el componente <finora-checkout>, y el webhook firmado decide la entrega del pedido.
Guías: Empezar en 10 minutos, Ciclo de vida de la sesión, Checkout web y app y Webhooks.
Recorrido 2: cobro empujado a un terminal
Para ventas que se cobran donde está el cliente (delivery, mesa, mostrador lejos de la caja). Tu ERP crea una intención con un bloque despacho y el terminal la recoge, cobra con tarjeta y reporta el veredicto.
Guía: Cobro empujado.
Recorrido 3: caja registradora con el terminal en la red local (Beta)
Integración semiintegrada: la caja envía monto y referencia al terminal y espera el veredicto en la misma respuesta. El tiempo agotado se trata como EN_DUDA y se resuelve consultando la misma clave de idempotencia.
Guía: Cobrar desde una caja registradora.
Recorrido 4: caja de escritorio con FINORA Pago
FINORA Pago se instala en el equipo de la caja y expone una API solo en ese equipo (http://127.0.0.1:9810), una URI finora-pago:// y una línea de comandos. Tu caja no integra rieles ni terminales. Guía: FINORA Pago.
Recorrido 5: enterarte de todo con webhooks
| Aviso | Para qué | Guía |
|---|---|---|
checkout.sesion | Resultado de cada sesión del checkout, a la webhookUrl de la sesión | Webhooks |
intencion.resultado, vale.* | Resultado de intenciones y vales, a las URL que suscribas | Suscripciones de eventos (Beta) |
Todos se firman igual: X-Finora-Signature: t=…,v1=… con HMAC-SHA256 sobre t + "." + cuerpo, se reintentan a 1, 5, 25 y 125 minutos y se deduplican por X-Finora-Entrega.
Antes de pasar a producción
- Prueba cada desenlace en el sandbox: aprobado, rechazado y en duda.
- Verifica la firma de los webhooks sobre el cuerpo crudo y deduplica las entregas.
- Guarda la clave de idempotencia de cada cobro junto a la venta.
- No entregues un pedido con un resultado que solo viste en el navegador.
- Revisa el alcance de tus claves API: una clave por sistema, con el mínimo alcance necesario.