Avisos (webhooks)

FINORA envía un POST a la webhookUrl de la sesión. Sin webhookUrl no hay aviso y tu servidor consulta por API.

Cabeceras

Cabecera	Valor
Content-Type	application/json
User-Agent	FINORA-Checkout-Webhook/1.0
X-Finora-Evento	checkout.sesion, checkout.intento.rechazado o checkout.prueba
X-Finora-Entrega	Identificador de la entrega. Un reintento trae el mismo: úsalo para no procesar dos veces
X-Finora-Signature	t=<segundos>,v1=<hex>,v0=<hex>. Cómo verificarla: Verifica la firma del aviso

checkout.sesion: la sesión se cerró

Llega cuando la sesión termina en APROBADA, RECHAZADA, EN_DUDA, CANCELADA o EXPIRADA. Es el aviso que decide qué pasa con el pedido.

{
  "evento": "checkout.sesion",
  "sesionId": "CS7Hq2mVx0Ld",
  "estado": "APROBADA",
  "referencia": "PED-1042",
  "monto": 227.00,
  "moneda": "VES",
  "riel": "PAGO_MOVIL",
  "codigo": "00",
  "mensaje": "Aprobada",
  "autorizacion": { "estado": "APROBADO", "codigo": "00", "mensaje": "Aprobada", "referenciaBanco": "BK-7HQ2-1" },
  "recibo": {
    "referencia": "FNR7HQ2MVX",
    "referenciaComercio": "PED-1042",
    "monto": 227.00,
    "moneda": "VES",
    "comercio": "Panadería Ejemplo",
    "riel": "PAGO_MOVIL",
    "referenciaBanco": "BK-7HQ2-1",
    "referenciaPagador": "04140000001",
    "fecha": "2026-10-04T15:05:12Z"
  },
  "sandbox": true,
  "ocurridoEn": "2026-10-04T15:05:12Z"
}

recibo es null si la sesión no quedó APROBADA. Un EN_DUDA produce dos avisos checkout.sesion para la misma sesión: el primero con EN_DUDA y el segundo con el desenlace. El último es el que vale.

checkout.intento.rechazado: un intento falló, la sesión sigue

Llega por cada intento rechazado mientras la sesión sigue abierta. Es informativo: no anules el pedido con él.

{
  "evento": "checkout.intento.rechazado",
  "sesionId": "CS7Hq2mVx0Ld",
  "estado": "EN_CURSO",
  "referencia": "PED-1042",
  "monto": 227.00,
  "moneda": "VES",
  "intento": { "secuencia": 1, "riel": "PAGO_MOVIL", "codigo": "51", "mensaje": "Fondos insuficientes" },
  "intentosRechazados": 1,
  "sandbox": true,
  "ocurridoEn": "2026-10-04T15:04:40Z"
}

checkout.prueba

El aviso que dispara POST /api/v1/checkout/webhooks/prueba. Trae evento, merchantCode, un mensaje y ocurridoEn, firmado igual que los demás.

Firma

Parte	Cálculo
t	Momento del envío, en segundos desde 1970
v1	hex(HMAC-SHA256(secreto, t + "." + cuerpo)). Verifica esta
v0	hex(HMAC-SHA256(secreto, cuerpo)). Formato anterior, se retira

Rechaza el aviso si |ahora − t| supera 300 segundos. Cada intento de entrega se firma con un t nuevo y con el secreto vigente.

El secreto es uno por comercio. Se regenera desde el Portal del comercio y el nuevo se muestra una sola vez.

Entrega y reintentos

Regla	Valor
Respuesta esperada	Cualquier 2xx en menos de 10 segundos
Reintentos	A 1, 5, 25 y 125 minutos: cinco intentos en total
Después del último	La entrega queda fallida. Se puede reenviar desde el Portal del comercio
Comercio suspendido	Los avisos pendientes esperan y salen cuando el comercio se reactiva