# LARI Payments Platform

Lightweight payment intake for Botswana travel & tours companies. Partners keep their own websites; we provide a hosted checkout, payment confirmation, and basic operational visibility.

This repo is the Phase 0 foundation: safe deploys, clear configuration, and a documented path to the payments MVP.

## What we are building
An API + hosted checkout + webhook system that lets Botswana travel/tour operators accept foreign card payments without becoming a travel agency or replacing their websites.

Key points:
- Partners stay on their own sites
- We handle payment intake and confirmation
- We pay out partners manually (early MVP)
- No travel marketplace or booking engine
- Avoid travel-agent regulation by staying in payments + confirmation

## Scope (MVP)
Included:
- Checkout session creation
- Hosted checkout page
- Payment webhook handling
- Payment status API
- Audit event log

Not included (MVP):
- Marketplace, booking inventory, or itinerary management
- Mobile app
- Automated payouts
- Local mobile money rails

## Phase 0 deliverables (current)
Goal: Ship safely and avoid early tech debt.

Deliverables:
- Repo + CI (lint/tests)
- Dev/Prod configuration separation
- Secrets handling (no keys in code)
- Database migrations
- Logging + request IDs
- Baseline schema

Definition of done:
- "Hello API" can be deployed
- Migrations run in CI and locally
- Logs show request IDs for a checkout attempt

## High-level architecture
Partner Website -> Payment API -> Hosted Checkout -> Payment Processor
                        |                 |
                        v                 v
                    Database <-------- Webhooks
                        |
                        v
                 Partner Dashboard (Phase 2)

Core components:
- Payment API: session creation, status lookup, webhook handling
- Hosted Checkout: redirect-based payment UI
- DB: partners, sessions, events, payouts
- Dashboard (later): partner visibility and payouts

## Minimal API (planned)
- POST /v1/checkout-sessions
  - Creates a session for a partner + order
- GET /v1/checkout-sessions/{id}
  - Returns status: pending | paid | failed | expired
- POST /v1/webhooks/payment-processor
  - Receives payment confirmation (signature verified)

## Data model (minimum)
partners:
- id
- name
- api_key_hash
- callback_url (optional)

checkout_sessions:
- id
- partner_id
- external_order_id
- amount
- currency
- status
- success_url
- cancel_url
- timestamps

events (audit):
- id
- session_id
- type (created | paid | failed | webhook_received)
- payload (json)
- timestamp

payouts:
- id
- partner_id
- period_start, period_end
- status (not_paid | scheduled | paid)
- method (bank | mobile_money)
- total_amount
- timestamp

## Environment configuration
We only run two environments:
- dev: feature work, internal testing
- prod: real payments and partner transactions

All secrets must be injected via environment variables or CI secrets.
Do not commit keys to the repo.

Expected env vars (initial draft):
- APP_ENV=dev|prod
- DATABASE_URL=sqlite:///./lari.db (dev) or postgres://... (prod)
- PAYMENT_PROVIDER_SECRET=...
- PAYMENT_WEBHOOK_SECRET=...
- LOG_LEVEL=info|debug|warn

## Logging & observability
Minimum standard:
- Every request has a request_id
- All payment events are append-only
- Webhook events are recorded even if they fail validation

## Local development
Stack: FastAPI + SQLAlchemy + Alembic.

Typical steps:
1) Create virtualenv and install dependencies
   - `python -m venv .venv`
   - `source .venv/bin/activate`
   - `pip install .`
   - `pip install pytest httpx ruff pre-commit`
2) Set env vars for dev
   - `cp .env.example .env`
3) Run migrations
   - `alembic upgrade head`
4) Start API server
   - `uvicorn app.main:app --reload`
5) Create a partner record (temporary for Phase 1 dev)
   - SQLite example:
     - `sqlite3 lari.db "insert into partners (id, name, created_at) values ('demo-partner', 'Demo Partner', datetime('now'));"`

## CI/CD
GitHub Actions workflow in `.github/workflows/ci-cd.yml`.

Rules:
- Push to dev/** or feature/** -> deploy to dev
- Release published -> deploy to prod

Replace the deploy placeholder scripts with real commands.

## Roadmap (phases)
Phase 0: foundation (current)
Phase 1: payments core
Phase 1.5: integration kit
Phase 2: partner ops dashboard
Phase 3: real pilot
Phase 4: productization
Phase 5: local rails + compliance readiness

## Security & compliance guardrails
- No card data touches our servers
- Webhooks are verified and idempotent
- Audit logs are append-only
- Avoid travel-agent classification by not brokering bookings

## How to contribute
- Keep scope narrow and focused on payments
- Add tests for payment state transitions
- Avoid hardcoding secrets
- Run `pre-commit install` locally to align with CI

## Developer workflow (day-to-day)
Why these commands exist:
- `pre-commit install` sets up Git hooks so formatting/lint checks run automatically before each commit.
- `pre-commit run --all-files` validates the entire codebase (useful before big pushes or after large refactors).
- `pre-commit run` runs only on staged files (fast, ideal for small changes).

Common command flow:
1) Install hooks and deps (once per machine)
   - `source .venv/bin/activate`
   - `pip install pre-commit`
   - `pre-commit install`
2) Before committing
   - `pytest`
   - `pre-commit run --all-files`
3) Commit and push
   - `git status`
   - `git add .`
   - `git commit -m "your message"`
   - `git push origin main`

Do you need to run them every time?
- `pip install pre-commit` is one-time per virtualenv (re-run only if you recreate the venv).
- `pre-commit install` is one-time per repo clone (re-run if hooks are missing).
- `pre-commit run` is recommended per commit, but the hook will also run it automatically.
- `pre-commit run --all-files` is occasional (big refactors or before large pushes).

## Test procedure
Core test run:
1) Activate the virtualenv
   - `source .venv/bin/activate`
2) Run the test suite
   - `pytest`

Optional smoke checks (manual sanity):
1) Run migrations
   - `alembic upgrade head`
2) Start the API
   - `uvicorn app.main:app --reload`
3) Hit the health endpoint
   - `http://127.0.0.1:8000/health`

## Push to GitHub
1) Confirm working tree
   - `git status`
2) Stage changes
   - `git add .`
3) Commit
   - `git commit -m "your message"`
4) Push
   - `git push origin main`

## Notes
This repo is currently a foundation scaffold. As soon as we choose the stack,
we will add setup instructions and the first API endpoints.
