startSession method

SplitSession startSession({ required Decimal orderTotal, String? splitPaymentId, Decimal? explicitTipAmount, })

Creates a new split payment session for the given order total.

When splitPaymentId is provided (non-null, non-empty), the session reuses that ID instead of generating a new UUID. This allows the backend to find and resume the existing parent event instead of creating a new one.

Throws StateError if there is already an active session with successful payment legs. Call discardSession first to explicitly abandon an in-progress session.

Implementation

SplitSession startSession({
  required Decimal orderTotal,
  String? splitPaymentId,
  Decimal? explicitTipAmount,
}) {
  if (_currentSession != null && _currentSession!.hasSuccessfulPayments) {
    _logger?.error(
      this,
      'startSession: blocked — active session has '
      '${_currentSession!.successfulLegCount} successful leg(s)',
    );
    throw StateError(
      'Cannot start a new session: the current session has '
      '${_currentSession!.successfulLegCount} successful payment leg(s). '
      'Call discardSession() first to explicitly abandon it.',
    );
  }

  final effectiveId = (splitPaymentId != null && splitPaymentId.isNotEmpty)
      ? splitPaymentId
      : null;
  final tip = explicitTipAmount ?? Decimal.zero;

  _currentSession = effectiveId != null
      ? SplitSession(
          splitId: effectiveId,
          orderTotal: orderTotal,
          explicitTipAmount: tip,
          paymentLegs: const [],
        )
      : SplitSession.create(
          orderTotal: orderTotal,
          explicitTipAmount: tip,
        );

  _logger?.info(
    this,
    'startSession: created — '
    'splitId=${_currentSession!.splitId}, '
    'orderTotal=$orderTotal, '
    'explicitTipAmount=$tip, '
    'reusedId=${effectiveId != null}',
  );
  return _currentSession!;
}