GST + UPI Reconciliation Copilot (India)

Perform deterministic reconciliation between GST invoice CSV data and UPI transaction CSV data. Generate four outputs: reconciled rows, GST-unmatched rows, UPI-unmatched rows, and a summary JSON.

Quick workflow

1. Confirm both input files are CSV and represent:
2. GST invoices/sales register
3. UPI collections/statement
4. Validate required intent-level fields exist (invoice id/date/total, txn date/amount/status).
5. Run:

python3 scripts/reconcile_gst_upi.py 
  --gst-csv /path/gst.csv 
  --upi-csv /path/upi.csv 
  --output-prefix /path/out/recon_2026_03 
  --date-window-days 7

1. Read and report key metrics from *_summary.json:
2. matched rows
3. unmatched GST rows
4. unmatched UPI rows
5. reconciliation coverage %
6. Provide next actions for unmatched rows (follow-up / corrections / data cleanup).

Matching policy

• Match only UPI rows with success-like status: success, completed, captured, paid.
• Require amount match (±0.01 tolerance).
• Enforce date window (default 7 days).
• Boost confidence if invoice number or customer tokens appear in UPI note/txn_id/UTR.
• Ensure one UPI transaction maps to one invoice only.

Edge-case handling

• Ignore failed/pending/reversed UPI statuses for settlement matching.
• Preserve GST rows with empty/invalid dates as unmatched (do not force guesswork).
• Preserve UPI rows with missing amount as unmatched.
• Support flexible date formats in both files.
• Handle currency symbols and commas in amount fields.

Required outputs to share with user

Always return:

1. Reconciliation snapshot:
2. matched rows / total GST rows
3. matched amount / total GST amount
4. File paths generated:
5. *_reconciled.csv
6. *_gst_unmatched.csv
7. *_upi_unmatched.csv
8. *_summary.json
9. Priority action items:
10. high-value unmatched GST invoices
11. suspicious UPI rows (success + high amount + no invoice)

References

• Read references/csv-schemas.md for accepted columns and alias mapping.