# Payment Gateways

Southend supports parent fee payments through **manual reference**, **PayChangu**, and **One Khusa**.

## Environment variables

Copy from `.env.example`:

| Variable | Purpose |
|----------|---------|
| `PAYMENTS_CURRENCY` | Default currency (MWK) |
| `PAYCHANGU_ENABLED` | Enable PayChangu checkout |
| `PAYCHANGU_PUBLIC_KEY` / `PAYCHANGU_SECRET_KEY` | API credentials |
| `PAYCHANGU_WEBHOOK_SECRET` | HMAC verification for webhooks |
| `ONE_KHUSA_ENABLED` | Enable One Khusa request-to-pay |
| `ONE_KHUSA_API_KEY` / `ONE_KHUSA_API_SECRET` | API credentials |
| `ONE_KHUSA_ORGANISATION_ID` | Organisation ID |
| `ONE_KHUSA_MERCHANT_ACCOUNT_NUMBER` | Merchant account |
| `ONE_KHUSA_WEBHOOK_SECRET` | HMAC verification for webhooks |

## Webhook & callback URLs

Register these in your provider dashboard (replace `{APP_URL}`):

| Provider | URL | Method |
|----------|-----|--------|
| PayChangu webhook | `{APP_URL}/payments/webhooks/paychangu` | POST |
| PayChangu callback | `{APP_URL}/payments/paychangu/callback` | POST |
| PayChangu return | `{APP_URL}/payments/paychangu/return` | GET |
| One Khusa webhook | `{APP_URL}/payments/webhooks/one-khusa` | POST |

When `PAYCHANGU_WEBHOOK_SECRET` or `ONE_KHUSA_WEBHOOK_SECRET` is set, unsigned requests are rejected.

## Parent portal flow

1. Parent opens **Fees → Pay** on an outstanding invoice.
2. Chooses payment method:
   - **Manual / Bank / Mobile Money** — submits reference; finance confirms in **Finance → Payment Reconciliation**.
   - **PayChangu** — redirected to hosted checkout; on success a receipt is posted automatically.
   - **One Khusa** — receives a timed account number (TAN); on webhook success a receipt is posted automatically.

## Finance reconciliation

- **Payment Reconciliation** lists all payments with gateway metadata.
- Manual parent payments appear in **Awaiting finance confirmation** with Confirm / Reject actions.
- Confirm posts a receipt, updates the invoice balance, and notifies the parent.
- Online gateway payments auto-settle when the provider confirms payment.

## API

```
GET /api/payments?status=pending&gateway=paychangu&gateway_status=success
GET /api/payments/{id}?include_payload=1
```

Requires Sanctum token and `finance.view` permission.

## Sandbox testing

1. Set `PAYCHANGU_ENABLED=true` or `ONE_KHUSA_ENABLED=true` with sandbox credentials.
2. Log in as a parent linked to a student with an outstanding invoice.
3. Submit a payment and verify webhook delivery to your local app (use ngrok or similar for local dev).

See also: [DEPLOYMENT.md](DEPLOYMENT.md)