# SasaPay & Africa's Talking SMS — Deployment Guide

## What Was Built

### New Files
| File | Purpose |
|------|---------|
| `payments/sms_service.py` | Africa's Talking SMS — all notification helpers, logs every SMS |
| `payments/sasapay_service.py` | SasaPay API — token, STK push, B2C disbursement, IPN processor |
| `payments/sasapay_models.py` | DB models: IPN logs, STK results, disbursement results, unknown payments, **SMSLog** |
| `payments/sasapay_views.py` | Django views for all SasaPay callbacks and staff dashboard |
| `payments/sms_views.py` | **SMS Logs admin views** — list, detail, resend, stats API |
| `payments/migrations/0003_sasapay_models.py` | Django migration for all new models |
| `sasapay_sms_tables.sql` | Raw SQL — run in phpMyAdmin (includes sms_logs table) |
| `templates/payments/sasapay_dashboard.html` | SasaPay & SMS admin dashboard |
| `templates/payments/sasapay_unknown_payments.html` | Unknown payments review page |
| `templates/payments/sms_logs.html` | **SMS Logs list page** |
| `templates/payments/sms_log_detail.html` | **SMS Log detail + resend page** |

### Modified Files
| File | Change |
|------|--------|
| `payments/urls.py` | Added SasaPay URLs + SMS log URLs + compatibility redirects |
| `branch_system/settings.py` | Added AT_USERNAME, AT_API_KEY, SASAPAY_* settings, SITE_URL |
| `.env` | Added AT and SasaPay credentials + SITE_URL |
| `requirements.txt` | Added `africastalking==1.2.7` |
| `users/navigation_service.py` | Added "M-Pesa Dashboard", "SasaPay & SMS", **"SMS Logs"** nav links |
| `templates/payments/dashboard.html` | Added SasaPay button in header |
| `templates/payments/sasapay_dashboard.html` | Added SMS Logs button |
| `templates/utils/settings.html` | Added SasaPay & SMS section with SMS Logs link |
| `templates/loans/repayments.html` | Added auto-payment info banner + SasaPay/SMS links + ⚡ Auto badge |
| `loans/views.py` | Added SMS hooks on loan approval + repayment recording |

---

## Step 1 — Install the Python package on the server

```bash
pip install africastalking==1.2.7
```

---

## Step 2 — Create the database tables

Run `sasapay_sms_tables.sql` in **phpMyAdmin** on the `xygbfpsg_loans` database.

Or via SSH:
```bash
mysql -u xygbfpsg_graz -p xygbfpsg_loans < sasapay_sms_tables.sql
```

---

## Step 3 — Register SasaPay callback URLs

Log into your SasaPay merchant portal and set:

| Type | URL |
|------|-----|
| C2B IPN (incoming payments) | `https://uzuriapps.xyz/payments/sasapay/ipn/` |
| STK Push callback | `https://uzuriapps.xyz/payments/sasapay/stk-callback/` |
| B2C Disbursement callback | `https://uzuriapps.xyz/payments/sasapay/disbursement-callback/` |

---

## Step 4 — Restart the application

```bash
touch tmp/restart.txt
```

---

## Step 5 — Verify

1. Go to **Settings → SasaPay & SMS** or navigate to `/payments/sasapay/`
2. Click **🔑 Test SasaPay Token** — should show success
3. Send a **Test SMS** to your phone number — check `/payments/sms/` to see it logged
4. Try an **STK Push** with a small amount (KES 1) to verify the full flow
5. Check **Repayments page** — auto-payments show ⚡ Auto (SasaPay) badge
6. Check **SMS Logs** at `/payments/sms/` — every SMS appears here with delivery status

---

## Credentials (from old PHP system)

| Service | Key | Value |
|---------|-----|-------|
| Africa's Talking | Username | `Uzuriapps` |
| Africa's Talking | API Key | `atsk_e810a145...` (in .env) |
| SasaPay | Client ID | `e63utew7...` (in .env) |
| SasaPay | Merchant Code | `1122` |
| SasaPay | Network Code | `63902` (M-Pesa) |

---

## How SMS Notifications Fire

| Event | Recipients | Message |
|-------|-----------|---------|
| SasaPay IPN payment received | 4 admin numbers + customer | `{ref} Confirmed. KES {amount} paid...` |
| Unknown/unmatched payment | 4 admin numbers + sender | `{ref} Confirmed. KES {amount} unknown payment...` |
| Loan approved (manual) | Customer only | `Dear {name}, your loan {number} for KES {amount} has been APPROVED...` |
| Manual repayment recorded | 4 admin numbers + customer | `{receipt} Confirmed. KES {amount} paid...` |
| Loan disbursed via B2C | 4 admin numbers + customer | `Dear {name}, KES {amount} has been disbursed...` |
| Overdue reminder | Customer only | `Dear {name}, your loan {number} has an overdue balance...` |

---

## SasaPay Flow

```
Customer pays via M-Pesa paybill
        ↓
SasaPay IPN → POST /payments/sasapay/ipn/
        ↓
process_ipn_callback() in sasapay_service.py
        ↓
Match borrower by phone/loan number
        ↓
Create Repayment record
        ↓
Send SMS confirmation to admins + customer
```

```
Staff clicks "Disburse Loan"
        ↓
POST /payments/sasapay/disburse/
        ↓
disburse_loan() → SasaPay B2C API
        ↓
SasaPay sends money to borrower's M-Pesa
        ↓
Callback → POST /payments/sasapay/disbursement-callback/
        ↓
Loan status updated to 'active'
        ↓
SMS sent to borrower + admins
```