finaliseTransaction method

Future<void> finaliseTransaction(String transactionId, CloudPosTransactionStatus status, { String? message, })

Finalises a transaction by reporting its terminal status to the backend.

Called by the originating device once it knows the final outcome (via SignalR from Terminal Manager). This updates the MongoDB record to a terminal state and frees the target terminal for other devices.

status must be a terminal status (e.g. Completed, Declined, Failed, TimedOut, Abandoned). Non-terminal statuses will be rejected by the backend.

This call is designed to be fire-and-forget — callers should catch and log errors rather than surfacing them to the user, since the originating device already has the transaction result.

Implementation

Future<void> finaliseTransaction(
  String transactionId,
  CloudPosTransactionStatus status, {
  String? message,
}) async {
  final url =
      '$baseUrl/cloudpos/api/cloudpos/transactions/$transactionId/finalise';

  _logger.info(
    this,
    'finaliseTransaction: $transactionId -> ${status.toApiString()}',
  );

  final body = {
    'status': status.toApiString(),
    if (message != null) 'message': message,
  };

  final response = await _httpClient.post(
    url: url,
    user: _authService.user,
    requestData: body,
  );

  if (response != null && response.statusCode == HttpStatus.ok) {
    _logger.info(
      this,
      'finaliseTransaction succeeded: $transactionId -> ${status.toApiString()}',
    );
    return;
  }

  _logger.error(
    this,
    'finaliseTransaction failed: ${response?.statusCode} ${response?.statusMessage}',
  );

  throw PlatformException(
    code: 'FINALISE_FAILED',
    message:
        'Failed to finalise transaction: ${response?.statusCode ?? 'no response'}',
  );
}