API de sesiones de cobro

Contrato v1 de la API de checkout. Todas las rutas cuelgan de la URL del servidor de FINORA de tu ambiente (<URL_DEL_MERCHANT>). Los montos van en unidades con dos decimales (227.00), nunca en céntimos. Las fechas van en ISO 8601.

La API tiene dos caras del mismo recurso:

Cara	Autenticación	Quién la usa
Servidor del comercio	Cabecera X-API-Key: <TU_CLAVE_API>	Tu backend
Cliente	Cabecera Authorization: Bearer <TOKEN>, o ?t=<TOKEN> como respaldo	El componente, en el navegador. CORS abierto solo en estas rutas; máximo 60 peticiones por minuto por sesión

Servidor del comercio

Crear una sesión: POST /api/v1/checkout/sesiones

Responde 201.

Campo	Obligatorio	Notas
monto	Sí	Mayor que cero
moneda	No	ISO 4217. Por defecto, la moneda de liquidación del comercio
referencia	No	Tu pedido o factura, hasta 64 caracteres. Vuelve en el aviso y en el recibo
descripcion, items	No	Solo para mostrar. items es JSON libre
terminalId	No	El terminal físico que cobra con tarjeta. Debe ser de tu comercio
pagador	No	tipoDocumento, documento, nombre, telefono. Precarga los campos de los medios
returnUrl	No	A dónde vuelve el cliente desde la página alojada, con ?sesion=…&estado=…
webhookUrl	No	http(s), hasta 512 caracteres. Sin ella no hay aviso: consultas por API
ttlSegundos	No	Entre 60 y 3600. Por defecto 900
sandbox	No	Marca la sesión como de pruebas: se ve en la página y en el aviso

Parámetro opcional ?merchantCode= para que un comercio principal cree la sesión a nombre de una de sus sucursales.

{
  "sesionId": "CS7Hq2mVx0Ld",
  "token": "…",
  "expiraEn": "2026-10-04T15:20:00Z",
  "urlPago": "https://pago.finoracore.com/s/CS7Hq2mVx0Ld?t=…",
  "estado": "CREADA",
  "medios": [ "…ver «Medios y campos»…" ]
}

El token solo aparece en esta respuesta. FINORA guarda su huella y no puede volver a mostrarlo.

Consultar una sesión: GET /api/v1/checkout/sesiones/{sesionId}

La vista completa: los campos de la creación más merchantCode, riel, intencion, intentos[], creadaEn, expiraEn, cerradaEn y resultado. Responde 404 SESION_NO_ENCONTRADA si la sesión no existe o no es de tu comercio, sin distinguir.

Listar sesiones: GET /api/v1/checkout/sesiones?desde&hasta&estado&max

desde y hasta en ISO 8601; estado, uno de los estados; max, hasta 500 (100 por defecto). Las más recientes primero.

Cancelar una sesión: POST /api/v1/checkout/sesiones/{sesionId}/cancelar

Idempotente. Responde 409 COBRO_EN_CURSO si hay una autorización en vuelo o el terminal ya aceptó la orden. Si la sesión tuvo intentos rechazados, la cancelación la cierra como RECHAZADA; si no, como CANCELADA.

Aviso de prueba: POST /api/v1/checkout/webhooks/prueba

Cuerpo { "url": "https://…" }. Envía un aviso checkout.prueba firmado en ese momento y responde cómo fue: estado de la entrega, código HTTP de tu endpoint, error si lo hubo, y la firma y el cuerpo exactos que se enviaron.

Medios disponibles sin abrir sesión: GET /api/v1/pagos/rieles

Parámetros merchantCode, terminalId, amount y presencial. Una tienda web manda presencial=false. Devuelve los medios del comercio con sus límites efectivos.

Cliente (token de sesión)

Esto es lo que hace el componente por ti. Lo necesitas solo si construyes tu propia interfaz.

Paso	Ruta	Qué hace
1	GET /api/v1/checkout/sesiones/{id}	Monto, comercio, medios con sus campos, modo de pedir la cédula
2	POST /api/v1/checkout/sesiones/{id}/medio	Elige el medio y envía sus datos. Si el medio confirma en línea, la respuesta ya trae el veredicto
3	GET /api/v1/checkout/sesiones/{id}/estado	Cada 2 segundos mientras haya un cobro en vuelo
—	POST /api/v1/checkout/sesiones/{id}/cancelar	El botón «Cancelar»

Ejemplo de elección de pago móvil:

{
  "riel": "PAGO_MOVIL",
  "tipoDocumento": "V",
  "documento": "00000001",
  "campos": { "telefono": "04140000001", "banco": "0001", "clave": "123456" }
}

Para tarjeta, { "riel": "TARJETA" }, con campos.terminalId solo si la sesión no lo fijó. La orden viaja al terminal y la respuesta queda EN_CURSO con resultado.despacho.estado = PENDIENTE. El navegador nunca envía un número de tarjeta.

Deja de consultar /estado cuando el estado sea APROBADA, RECHAZADA, EN_DUDA, CANCELADA o EXPIRADA. Si vuelve a CREADA con TERMINAL_SIN_RESPUESTA o CANCELADA_EN_TERMINAL, muestra otra vez los medios. Si sigue EN_CURSO y cambió resultado.ultimoIntento, hubo un rechazo: muéstralo y ofrece reintentar o cancelar.

Medios y campos

Cada medio de la lista medios trae, entre otros:

Campo	Qué dice
code, name	El identificador del medio (TARJETA, PAGO_MOVIL, TRANSFERENCIA…) y su nombre visible
instructions	Texto para el cliente, definido por el comercio
campos[]	Los datos que pide, con code, label, fieldType, required y validationRegex
minAmount, maxAmount	Los límites efectivos para este comercio
requiereTerminal	true en tarjeta
disponible, motivoNoDisponible	Si se puede elegir ahora y, si no, por qué

fieldType es uno de CEDULA, TELEFONO, BANCO, SECRETO, TEXTO, NUMERO o CORREO. Un campo SECRETO, como la clave de pago móvil, viaja al banco y no se guarda.

El resultado

GET …/estado devuelve el bloque resultado:

Campo	Qué trae
estado, riel, codigo, mensaje	Cómo va o cómo terminó
autorizacion	estado del intento (INICIADO, AUTORIZANDO, APROBADO, RECHAZADO, EN_DUDA, REVERSADO), código y referencia del banco
recibo	Solo con APROBADA: referencias de FINORA, del comercio y del banco, monto, medio, origen del pago y fecha. Con tarjeta, el origen es el número enmascarado
despacho	Solo con tarjeta: PENDIENTE, ENTREGADA, ACEPTADA, COMPLETADA, EN_DUDA, CANCELADA o EXPIRADA. Con ACEPTADA el cliente ya no puede cancelar
ultimoIntento, intentos[]	El último rechazo y el historial de intentos de la sesión

Nota

Los errores de todas estas rutas se describen en Códigos de error y de resultado. Los avisos que recibe tu servidor, en Avisos (webhooks).