Referencia (API Merchant)
Cada endpoint de la API Merchant, con sus parámetros, cuerpos y respuestas, está en la referencia navegable. Abajo los tienes agrupados por quién hace la llamada, que suele ser la primera pregunta.
Todas las rutas cuelgan de la URL base de tu entorno.
Lo que llama tu backend (token Bearer)
| Operación | Método | Ruta |
|---|---|---|
| Registrarte como comercio | POST | /api/v1/merchants (pública) |
| Iniciar sesión | POST | /api/v1/merchants/auth/login (pública) |
| Generar OTP para pairing | POST | /api/v1/merchants/{merchantId}/pos-terminals/{serialNumber}/pairing |
| Solicitar pago | POST | /api/v1/merchants/{merchantId}/transactions |
| Consultar pago | GET | /api/v1/merchants/{merchantId}/transactions/{orderId} |
| Anular pago | POST | /api/v1/merchants/{merchantId}/transactions/{orderId}/cancellation |
| Listar cierres de un terminal | GET | /api/v1/merchants/{merchantId}/pos-terminals/{serialNumber}/settlements |
| Consultar un cierre | GET | /api/v1/pos-terminals/{serialNumber}/settlements/{batchNumber} |
Lo que llama el terminal (firma HMAC)
| Operación | Método | Ruta |
|---|---|---|
| Activar dispositivo POS | POST | /api/v1/pos-terminals/{serialNumber}/pairing/activate (pública) |
| Listar pagos del POS | GET | /api/v1/pos-terminals/{serialNumber}/transactions |
| Consultar el estado de un pago | GET | /api/v1/pos-terminals/{serialNumber}/transactions/{orderId} |
| Confirmar pago | POST | /api/v1/pos-terminals/{serialNumber}/transactions/{orderId}/commit |
| Confirmar anulación | POST | /api/v1/pos-terminals/{serialNumber}/transactions/{orderId}/cancellation/commit |
| Crear cierre de lote | POST | /api/v1/pos-terminals/{serialNumber}/settlements |
| Listar cierres | GET | /api/v1/pos-terminals/{serialNumber}/settlements |
Fíjate en las dos rarezas: activar el dispositivo es público —el terminal aún no tiene con qué firmar— y consultar un cierre concreto pide token, no firma, aunque la ruta cuelgue de pos-terminals.
Cómo leer "POSSignature" en la referencia
La referencia navegable etiqueta estos endpoints como POSSignature sin decir en qué cabecera viaja la firma. Es x-pos-signature, y va siempre acompañada de x-pos-timestamp — que el contrato no declara, pero el servidor exige. El detalle, con vector de prueba, está en Comunicación con punto de venta.
También útil
- Comunicación con punto de venta — pairing y firma, paso a paso.
- Estados de un pago — los cinco estados y qué llamada provoca cada salto.
- Diccionario de datos — todos los campos del contrato, con su tipo y descripción.