Agenda una demo
DocumentaciónAPI reference
Menú: Documentación

Pay at counter y APK

Elegir una integración

Compara la Cloud API, la Local API y los Intents de Android para lanzar cobros en un terminal honei desde tu TPV o tu APK.

honei ofrece tres formas de que un TPV lance un cobro en un terminal: la Cloud API, la Local API y los Intents de Android.

La Cloud API y la Local API admiten las dos configuraciones posibles:

  • Un TPV en otro dispositivo que envía el cobro al terminal.
  • Una APK de TPV instalada en el propio terminal que envía el cobro a ese mismo terminal.

Los Intents de Android solo sirven para el segundo caso: tu APK y honei Terminal se comunican directamente dentro del dispositivo.

Las tres vías de un vistazo

Cloud APITPVCualquier dispositivoInternethoneiNubeAviso al terminalTerminalCobraLocal APITPVMisma red localHTTPS firmadoTerminalCobraIntents de AndroidAPKDentro del terminalIntent de Androidhonei TerminalCobra

Comparativa

Cloud API Local API Intents de Android
Con quién habla tu TPV Servidores de honei El terminal, por la red local La app honei Terminal, en el mismo dispositivo
Dónde se ejecuta Cualquier lugar con internet Misma red local o mismo dispositivo Solo una APK instalada en el terminal
Autenticación Authorization + venue-api-key Firma HMAC-SHA256 por terminal Sin credenciales; opcionalmente, solo tu app autorizada
Resultado Consultas el estado Consultas el estado Lo recibes en tu app al terminar
Cobros Sí Sí Sí
Devoluciones Sí Sí No
Cancelar una operación en curso Sí Todavía no No
Imprimir tickets Sí No No

Mismo flujo, distinto transporte

Con la Cloud API y la Local API, el TPV hace exactamente lo mismo, en el mismo orden:

  1. Envía el cobro o la devolución al terminal en una llamada que responde de inmediato.
  2. El terminal muestra la pantalla para pasar o acercar la tarjeta y la procesa.
  3. El TPV consulta un endpoint de estado hasta recibir un resultado final (completed, declined, error…).

Esa secuencia no cambia entre las dos. Lo que cambia es con quién habla realmente el TPV y cómo se autentica.

Con los Intents de Android no hay consultas de estado: tu app abre honei Terminal, el operador cobra y Android te devuelve el resultado.

Diferencias clave

Cloud API

El TPV habla con los servidores de honei (api.honei.app), así que necesita internet allí donde se ejecute. Todas las llamadas llevan un terminalId en la ruta, de modo que un mismo cliente puede dirigirse a cualquier terminal del negocio.

Las peticiones se autentican con Authorization: Bearer <clientSecret> y venue-api-key, las mismas credenciales que en el resto de la API REST, sin configuración adicional. También permite cancelar una operación en curso.

Local API

El TPV habla directamente con el terminal, así que debe estar en su misma red local o en el mismo dispositivo. No hay terminalId: el servidor local del terminal solo se atiende a sí mismo.

Las peticiones se firman con HMAC-SHA256 usando un secreto que se emite una vez por terminal (consulta Autorización), y hay que fijar por su huella el certificado autofirmado del terminal. Todavía no permite cancelar operaciones.

Intents de Android

Tu APK lanza un Intent de Android con el importe, honei Terminal se abre para gestionar el cobro y el resultado vuelve a tu app. No hay llamadas HTTP ni credenciales que gestionar.

Esta vía cubre cobros, pero no devoluciones, cancelaciones ni impresión. Si tu APK necesita devolver un pago, combínala con la Local API o la Cloud API. Para imprimir tickets, usa la Cloud API.

Cuándo usar cada una

Usa la Cloud API si quieres la configuración más sencilla: sirven las mismas clientSecret y venue-api-key que ya usas, sin ningún paso por terminal. También es la opción si necesitas cancelar un cobro o una devolución en curso, porque la Local API todavía no lo permite.

Usa la Local API si la conexión entre el TPV y el terminal debe seguir funcionando durante una caída de internet: depende solo de la red local o del propio dispositivo, no de llegar a los servidores de honei para enviar y consultar el cobro. A cambio, requiere la configuración inicial por terminal de Autorización.

Usa los Intents de Android si tu TPV es una APK instalada en el terminal y solo necesitas cobrar: es la integración con menos código.

Si no lo tienes claro, empieza por la Cloud API. Si más adelante la conexión a internet resulta ser un problema, pasa a la Local API.

Cuando tengas tu integración, pruébala en staging.