Settlement & Reconciliation

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

---

Overview

The Settlement & Reconciliation domain manages the daily settlement process to reconcile transactions, balance cash drawers, and prepare financial reports. It provides comprehensive tracking of payment breakdowns across different methods and providers, manages cash discrepancies, handles card slip reconciliation with processor reports, and ensures financial accuracy across the entire system. This domain is critical for end-of-day operations, financial reporting, and maintaining audit trails.

Table of Contents

• Purpose
• Settlement Process
• Card Slip Management
• API Endpoints Summary

---

Purpose

Daily settlement process to reconcile transactions, balance cash drawer, and prepare financial reports.

Settlement Entity

{
  "id": "settlement_uuid",
  "store_id": 2,
  "settlement_date": "2026-01-28",
  "start_time": "2026-01-28T00:00:00Z",
  "end_time": "2026-01-28T23:59:59Z",
  "payment_method_breakdown": {
    "cash": {
      "transaction_count": 150,
      "total_amount": 5000000
    },
    "qr": {
      "paypay": {
        "transaction_count": 200,
        "total_amount": 8000000
      },
      "line_pay": {
        "transaction_count": 50,
        "total_amount": 2000000
      }
    },
    "credit_card": {
      "visa": {
        "transaction_count": 100,
        "total_amount": 6000000
      },
      "mastercard": {
        "transaction_count": 80,
        "total_amount": 4000000
      }
    }
  },
  "total_transactions": 580,
  "total_amount": 25000000,
  "cash_expected": 5000000,
  "cash_actual": 4995000,
  "cash_discrepancy": -5000,
  "status": "open|closed|reconciled",
  "reconciled_by": "user_uuid",
  "reconciled_at": "2026-01-29T09:00:00Z",
  "notes": "Missing ¥5,000 cash - investigating"
}

---

Settlement Process

End of Day - Staff initiates settlement

1. Generate Settlement Report
   └─ Query all completed payments for store in date range
   └─ Group by payment_method and provider
   └─ Calculate totals per method
   └─ Calculate expected cash = SUM(cash payments)

2. Count Cash Drawer
   └─ Staff physically counts cash
   └─ Enter actual cash amount
   └─ Calculate discrepancy = actual - expected
   └─ If discrepancy > threshold: Flag for review

3. Match with Provider Reports
   For QR providers:
     └─ Fetch PayPay settlement report (via API)
     └─ Compare PGW transactions vs. Provider report
     └─ Flag discrepancies

   For Credit Card:
     └─ Fetch card slip report from SP-NET
     └─ Match by card_document_number
     └─ Verify approval_codes
     └─ Flag missing or mismatched slips

4. Close Settlement
   └─ Lock transactions (prevent modification)
   └─ Mark settlement: status = closed
   └─ Generate PDF report
   └─ Store in S3
   └─ Send to accounting system

5. Reconciliation (if discrepancies)
   └─ Investigate missing transactions
   └─ Adjust for refunds/voids
   └─ Record resolution notes
   └─ Mark: status = reconciled

Related Domains:

• Payment Processing - Source of transaction data for settlement
• Payment Gateway - Provider reports and reconciliation data
• Merchant Hierarchy - Store-level settlement organization

---

Card Slip Management

Purpose: Track credit card payment slips for reconciliation with processor reports.

Card Slip Entity

{
  "id": 1,
  "payment_id": "payment_uuid",
  "slip_number": "00123456",
  "approval_code": "123456",
  "card_last_4": "1234",
  "card_brand": "VISA",
  "transaction_amount": 100000,
  "transaction_date": "2026-01-28",
  "status": "approved|declined|voided",
  "processor_batch_id": "BATCH-2026-01-28-001",
  "reconciled": false,
  "created_at": "2026-01-28T11:00:00Z"
}

Reconciliation Process

Daily batch from SP-NET processor
  └─ Contains: all card slips for store
  └─ Match by: slip_number, approval_code

For each slip in processor report:
  └─ Find card_slip in database
  └─ Compare: amount, card_last_4, approval_code
  └─ If match: Mark reconciled = true
  └─ If mismatch: Flag for investigation
  └─ If not found: Flag missing transaction

Generate reconciliation report:
  └─ Matched slips
  └─ Unmatched slips (in POS but not in processor)
  └─ Missing slips (in processor but not in POS)
  └─ Amount discrepancies

Related Domains:

• Payment Processing - Credit card payment transactions
• Reporting - Settlement and reconciliation reports

---

API Endpoints Summary

Method	Endpoint	Purpose
POST	/settlements	Create/start settlement
GET	/settlements	List settlements (filtered by store/date)
GET	/settlements/{id}	Settlement details
PATCH	/settlements/{id}	Update cash count, notes
POST	/settlements/{id}/close	Close settlement
POST	/settlements/{id}/reconcile	Mark as reconciled
GET	/settlements/{id}/report	Download PDF report
GET	/card_slips	List card slips for reconciliation
POST	/card_slips/reconcile	Batch reconcile slips

---

Navigation

• Previous: Receipt & Invoice Management
• Next: App Update Management
• Up: Domain Models Index