Conceptos (Merchant)
El modelo Merchant gira en torno a un terminal físico que opera de forma autónoma y segura. Cuatro ideas lo resumen, y con ellas puedes leer cualquier guía de esta doc.
1. Dos actores, dos llaves
La API separa dos roles para que el robo de un dispositivo no comprometa la cuenta del comercio:
| Actor | Alcance | Se autentica con |
|---|---|---|
| Merchant / Admin | Tu backend, ERP, dashboards | JWT (Bearer) — token de una hora, se pide en /auth/login |
| Terminal / POS | El hardware del mostrador | HMAC — firma con una secret key que vive solo en el aparato |
Comprometer un dispositivo no compromete la cuenta, y al revés. Cada uno puede hacer exactamente lo suyo: tu backend crea y anula pagos; el terminal los cobra y los confirma.
2. Pairing (vinculación) — una sola vez
El terminal se "presenta" al servidor una única vez en su vida:
- El admin (con su Bearer) solicita vincular un serial y genera un OTP.
- El técnico ingresa el OTP en el POS; el dispositivo lo canjea.
- El servidor genera una Secret Key y la guarda asociada al serial; el POS la guarda en su memoria segura.
A partir de ahí, la Secret Key nunca vuelve a viajar por internet. → Comunicación con punto de venta.
3. Operación firmada (HMAC)
Ya vinculado, cada petición del POS se firma con HMAC-SHA256 sobre el cuerpo, el timestamp y la URL, usando su Secret Key. Esto da integridad (si cambian el monto o la URL, la firma falla) y protección contra replay (por el timestamp).
4. Pago a dos tiempos y cierre de lote
Ningún pago se cierra de una sola llamada, y esa es la idea central:
- Tu backend crea el pago; nace
PENDING. Todavía no hay dinero. - El terminal lo cobra con la tarjeta y lo confirma (
commit); ahí pasa aPAID. - Anular funciona igual, en dos tiempos: tu backend lo pide (
VOID_PENDING), el terminal lo ejecuta (VOIDED). - Al final de la jornada, el terminal envía un cierre de lote para conciliar el día.
Los cinco estados y sus saltos están en Estados de un pago.