Skip to main content

Settlement Concept

Overview​

Settlement in the Moneta Network refers to the process of reconciling and transferring funds between Membership Organizations (MOs) and their members. This document explains the settlement process, types, and implementation details.

Settlement Types​

1. Regular Settlement​

  • Scheduled periodic settlements
  • Batch processing of transactions
  • Standard processing time (T+1 or T+2)

2. Instant Settlement​

  • Real-time fund transfers
  • Individual transaction processing
  • Premium service with additional fees

3. Bulk Settlement​

  • Large volume transaction processing
  • Optimized for efficiency
  • Scheduled during off-peak hours

Settlement Flow​

Settlement States​

  1. Pending

    • Settlement requested
    • Awaiting processing

  2. Processing

    • Funds being transferred
    • Validation in progress

  3. Completed

    • Funds successfully transferred
    • Records updated

  4. Failed

    • Error in settlement
    • Requires investigation

Implementation Details​

Settlement Configuration​

interface SettlementConfig {
  scheduleType: 'DAILY' | 'WEEKLY' | 'MONTHLY';
  cutoffTime: string; // HH:mm in UTC
  settlementWindow: number; // hours
  minimumAmount: number;
  currency: string;
  notificationEndpoints: string[];
}

Settlement Record​

interface SettlementRecord {
  id: string;
  moId: string;
  amount: number;
  currency: string;
  status: SettlementStatus;
  createdAt: Date;
  completedAt?: Date;
  transactions: Transaction[];
  metadata: {
    batchId?: string;
    referenceNo: string;
    settlementType: SettlementType;
  };
}

Processing Rules​

1. Amount Calculation​

function calculateSettlementAmount(transactions: Transaction[]): number {
  return transactions.reduce((total, tx) => {
    const fee = calculateFee(tx);
    return total + (tx.amount - fee);
  }, 0);
}

2. Validation Rules​

async function validateSettlement(settlement: SettlementRecord): Promise<boolean> {
  // 1. Check minimum amount
  if (settlement.amount < config.minimumAmount) {
    throw new Error('Below minimum settlement amount');
  }

  // 2. Verify transaction status
  const invalidTx = settlement.transactions.find(tx => !isValidForSettlement(tx));
  if (invalidTx) {
    throw new Error(`Invalid transaction: ${invalidTx.id}`);
  }

  // 3. Check MO status
  const moStatus = await getMOStatus(settlement.moId);
  if (!moStatus.isActive) {
    throw new Error('MO account inactive');
  }

  return true;
}

Reporting​

1. Settlement Report​

interface SettlementReport {
  periodStart: Date;
  periodEnd: Date;
  totalAmount: number;
  transactionCount: number;
  successfulSettlements: SettlementRecord[];
  failedSettlements: SettlementRecord[];
  fees: {
    total: number;
    breakdown: {
      type: string;
      amount: number;
    }[];
  };
}

2. Reconciliation Data​

interface ReconciliationData {
  settlementId: string;
  bankReference: string;
  clearedAmount: number;
  clearedAt: Date;
  discrepancies: {
    type: DiscrepancyType;
    amount: number;
    reason: string;
  }[];
}

Error Handling​

Common Issues​

  1. Insufficient Funds

    {
      "error": "insufficient_funds",
      "details": {
        "required": 1000.00,
        "available": 500.00,
        "currency": "USD"
      }
    }

  2. Bank Rejection

    {
      "error": "bank_rejection",
      "code": "BANK_001",
      "message": "Invalid bank account details"
    }

Recovery Procedures​

async function handleSettlementError(error: SettlementError): Promise<void> {
  switch (error.type) {
    case 'INSUFFICIENT_FUNDS':
      await notifyMO(error.moId, 'FUNDS_REQUIRED');
      await scheduleRetry(error.settlementId, 24); // Retry in 24h
      break;
    
    case 'BANK_ERROR':
      await escalateToSupport(error);
      await notifyMO(error.moId, 'BANK_ISSUE');
      break;
    
    default:
      await logError(error);
      throw error;
  }
}

Best Practices​

  1. Monitoring

    • Real-time settlement tracking
    • Automated alerts for failures
    • Performance metrics collection

  2. Reconciliation

    • Daily balance checks
    • Transaction matching
    • Discrepancy resolution

  3. Security

    • Multi-level approvals
    • Audit trail maintenance
    • Fraud detection