Procesar un Pago con Terminal
Flujo
1. El cajero ingresa el monto en el POS
2. La app del POS envía el subtotal a Migo, referenciando la terminal/dispositivo
3. Migo valida la terminal y su procesador/cuenta asociados
4. Migo crea el pago con terminal (el estado inicia como "created", totalAmount 0)
La captura y autorización de la tarjeta se manejan fuera de banda por la integración con el procesador de tarjetas — no se realizan con datos de tarjeta en esta solicitud.
Solicitud
El body es CreateTerminalPaymentInput. Solo subtotal es requerido; proporciona al menos uno de externalTerminalId, terminalId o deviceId para que la terminal pueda resolverse.
{
"externalTerminalId": "TRM-EXT-001",
"subtotal": 150.5,
"additionalData": { "invoiceNumber": "INV-001" }
}
| Campo | Tipo | Notas |
|---|---|---|
subtotal | number | Requerido. Subtotal del pago, debe ser mayor que 0 |
externalTerminalId | string | Opcional. Identificador de terminal externo de la red de pagos |
terminalId | number | Opcional. Identificador interno de la terminal |
deviceId | string | Opcional. Identificador del dispositivo que inicia el pago |
operationId | string | Opcional. Identificador de operación para seguimiento. Se autogenera si se omite |
additionalData | object | Opcional. Metadatos de formato libre persistidos en el pago con terminal |
La currency se toma de la configuración de la terminal, no de la solicitud.
Respuesta (creado)
Crear un pago con terminal devuelve el registro recién creado. Inicia con estado created y totalAmount "0". Los campos monetarios subtotal y totalAmount se devuelven como strings, y additionalData puede ser null.
{
"success": true,
"status": 200,
"message": "terminal payment created successfully.",
"data": {
"id": 34,
"terminalId": 1,
"externalId": "",
"subtotal": "10",
"totalAmount": "0",
"status": "created",
"currency": "GTQ",
"additionalData": null,
"createdAt": "2025-06-03T04:52:07.637Z",
"updatedAt": "2025-06-03T04:52:07.637Z"
}
}
Errores
Los errores usan el envelope estándar CustomResponse: { statusCode, message, error: { code, name, detail } }. Los códigos de error de pago con terminal incluyen:
| Código | Nombre | Significado |
|---|---|---|
7307 | ERROR_CREATING_TERMINAL_PAYMENT | Falló la creación del pago con terminal |
7308 | ERROR_TERMINAL_PAYMENT_STATUS | Transición de estado inválida |
7400 | TERMINAL_NOT_FOUND | La terminal referenciada no existe |
7401 | TERMINAL_INACTIVE | La terminal no está activa |
7402 | TERMINAL_PAYMENT_NOT_FOUND | El pago con terminal no existe |
7006 | EXTERNAL_ID_ALREADY_EXISTS | externalId duplicado |