recordPaymentLeg method

SplitSession recordPaymentLeg({ required PaymentResult result, required String paymentMethod, String? description, int? transactionNumber, String? customerId, String? customerName, })

Records a payment leg result and returns the updated session.

Both successful and failed payments are recorded. Only successful payments affect the outstanding balance.

Implementation

SplitSession recordPaymentLeg({
  required PaymentResult result,
  required String paymentMethod,
  String? description,
  int? transactionNumber,
  String? customerId,
  String? customerName,
}) {
  if (_currentSession == null) {
    _logger?.error(this, 'recordPaymentLeg: no active session');
    throw StateError('Cannot record payment leg: no active split session.');
  }

  // Capture the cash tendered amount for cash legs.
  // result.otherAmount holds the amount the customer physically tendered
  // on the cash tendered popup. We store it so we can compute per-leg
  // change (cashTendered − legAmount) in buildCumulativeResult().
  final Decimal? cashTendered =
      paymentMethod.toLowerCase() == 'cash' &&
          result.otherAmount > Decimal.zero
      ? result.otherAmount
      : null;

  final isCash = paymentMethod.toLowerCase() == 'cash';

  String? nullIfEmpty(String? v) =>
      (v == null || v.isEmpty) ? null : v;

  final leg = PaymentLeg(
    id: const Uuid().v4(),
    paymentMethod: paymentMethod,
    amount: result.amount,
    isSuccess: result.transactionStatus == PaymentStatus.processed,
    timestamp: DateTime.now(),
    description: description,
    reference: result.traceId.isNotEmpty ? result.traceId : null,
    cashTendered: cashTendered,
    transactionNumber: transactionNumber,
    cardType: isCash ? null : nullIfEmpty(result.paymentMethod),
    maskedPan: isCash ? null : nullIfEmpty(result.maskedPan),
    paymentStatus: nullIfEmpty(result.status),
    batchNumber: result.batchNumber > 0 ? result.batchNumber.toString() : null,
    authResponse: nullIfEmpty(result.authResponse),
    authResponseCode: nullIfEmpty(result.authResponseCode),
    authCode: nullIfEmpty(result.authCode),
    entryMode: nullIfEmpty(result.entryMode),
    terminalId: nullIfEmpty(result.terminalId),
    customerId: nullIfEmpty(customerId),
    customerName: nullIfEmpty(customerName),
  );

  _currentSession = _currentSession!.addPaymentLeg(leg);

  _logger?.info(
    this,
    'recordPaymentLeg: ${leg.isSuccess ? 'success' : 'failed'} — '
    'amount=${leg.amount}, '
    'method=$paymentMethod, '
    'totalPaid=${_currentSession!.amountPaid}, '
    'outstanding=${_currentSession!.amountOutstanding}, '
    'state=${_currentSession!.state.name}',
  );

  return _currentSession!;
}