Introducción

Esta integración permite que un TPV en la misma red local que el terminal lance cobros y devoluciones directamente contra él por HTTPS, sin pasar por la Cloud API de honei.

Primero necesitas una clave por terminal. Después ya puedes cobrar y devolver.

URL base

Las peticiones se hacen directamente al terminal, no a los servidores de honei:

https://<ip-local-del-terminal>:8743

Todas las rutas de esta sección empiezan por /device-bridge, por ejemplo https://<ip-local-del-terminal>:8743/device-bridge/init-payment.

Usa la IP local del terminal en tu red. Te recomendamos asignarle una IP estática, por ejemplo con una reserva de DHCP, en lugar de depender de una dinámica, para que esta URL base siga siendo válida con el tiempo.

El terminal sirve HTTPS con un certificado autofirmado, así que no puede validarse contra una CA pública. Fíjalo por su huella SHA-256, que se entrega junto con el secreto de firma: consulta Autorización.

Para comprobar que llegas al terminal, usa esta llamada, que no necesita firma:

GETComprobar el servidor/device-bridge/healthAPI reference

Autenticación

No hay cabecera Authorization. En su lugar, cada petición (salvo health) lleva dos campos JSON adicionales, counter y hmac:

• counter: un número que debe aumentar estrictamente en cada petición que envíes a este terminal. No hace falta que sea una marca de tiempo; basta con un contador que empiece en 1, siempre que nunca se repita ni disminuya. Un valor repetido o menor se rechaza con 409 Conflict.
• hmac: una firma HMAC-SHA256, que se calcula así:
  1. Toma todos los campos de la petición excepto hmac, ordenados alfabéticamente por nombre.
  2. Únelos como pares clave=valor con &, por ejemplo amount=12.5&counter=1&ref=abc.
  3. Firma esa cadena con HMAC-SHA256, usando el secreto compartido como clave.

El terminal firma sus respuestas del mismo modo, con su propio campo hmac. Verifícalo en cada respuesta que recibas, igual que el terminal verifica las tuyas.

El secreto compartido se emite una vez por terminal, al darlo de alta: consulta Autorización.