Process a Terminal Payment
Flow
1. The cashier enters the amount on the POS
2. The POS app submits the subtotal to Migo, referencing the terminal/device
3. Migo validates the terminal and its bound processor/account
4. Migo creates the terminal payment (status starts as "created", totalAmount 0)
The card capture and authorization are handled out-of-band by the card-processor integration — they are not performed via card data in this request.
Request
The body is CreateTerminalPaymentInput. Only subtotal is required; supply at least one of externalTerminalId, terminalId, or deviceId so the terminal can be resolved.
{
"externalTerminalId": "TRM-EXT-001",
"subtotal": 150.5,
"additionalData": { "invoiceNumber": "INV-001" }
}
| Field | Type | Notes |
|---|---|---|
subtotal | number | Required. Payment subtotal, must be greater than 0 |
externalTerminalId | string | Optional. External terminal identifier from the payment network |
terminalId | number | Optional. Internal terminal identifier |
deviceId | string | Optional. Identifier of the device initiating the payment |
operationId | string | Optional. Operation identifier for tracking. Auto-generated if omitted |
additionalData | object | Optional. Free-form metadata persisted on the terminal payment |
The currency is taken from the terminal configuration, not from the request.
Response (created)
Creating a terminal payment returns the newly created record. It starts with status created and totalAmount "0". The monetary fields subtotal and totalAmount are returned as strings, and additionalData may be 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"
}
}
Errors
Errors use the standard CustomResponse envelope: { statusCode, message, error: { code, name, detail } }. Terminal-payment error codes include:
| Code | Name | Meaning |
|---|---|---|
7307 | ERROR_CREATING_TERMINAL_PAYMENT | Failed to create the terminal payment |
7308 | ERROR_TERMINAL_PAYMENT_STATUS | Invalid status transition |
7400 | TERMINAL_NOT_FOUND | The referenced terminal does not exist |
7401 | TERMINAL_INACTIVE | The terminal is not active |
7402 | TERMINAL_PAYMENT_NOT_FOUND | The terminal payment does not exist |
7006 | EXTERNAL_ID_ALREADY_EXISTS | Duplicate externalId |