# ITNA Hotspot V8 — Integrations

## Install or upgrade
- Backup V7 application folder, `/storage/config.php`, `/storage/app.sqlite` and VPS database before upgrading.
- Deploy V8 files retaining the existing storage directory and encryption key. **Never replace the existing config.php with a new key.**
- On a clean server use `setup.php`; on an upgrade the new integration tables are created lazily at first access.
- Install PHP 8.1+ with pdo_sqlite, mbstring, openssl and curl. V8 Dockerfile includes curl.
- Use HTTPS reverse proxy and configure `API Settings` → public application URL.

## SSLCommerz
1. Obtain merchant sandbox store ID/password, enter under `API Settings`, keep mode Sandbox.
2. The operator creates an unsold voucher, navigates to `Payments & SSLCommerz`, enters customer phone (`8801XXXXXXXXX`), name, email and opens hosted checkout.
3. Register publicly accessible HTTPS IPN URL `https://YOUR-DOMAIN/gateway-callback.php?type=ipn` in the SSLCommerz merchant portal.
4. The application **does not trust browser redirects**. It validates `val_id` by server-side SSLCommerz validation API, matches transaction ID, BDT amount and currency, and holds risk-level != 0.
5. On successful validation it atomically marks the voucher sold and queues SMS/email. Docker RADIUS sync worker sees sold voucher in SQLite and provisions it on its next run.
6. Payment and notification metadata are in `gateway_orders`, `notification_queue`. Verify actual RADIUS login and a test SMS/email before switching merchant account to Live.
7. Payment failures/cancel redirects do not activate vouchers. For interrupted checkout, create a new session or reconcile transaction manually; automatic payment retry and refunds are not implemented.

## BulkSMSBD
- Get approved sender ID and API key; enter under API Settings. SMS goes to `https://bulksmsbd.net/api/smsapi` with POST, `api_key`, `senderid`, `number`, `message`.
- HTTP API accepted `response_code=202` is submission, **not delivery**. Check delivery reports in provider dashboard.

## SMTP email
- Enter SMTP host, port 587, user/password and sender email. STARTTLS is mandatory; SMTPS 465 is not supported by the included client.
- Edit customer templates under Message Templates. Available placeholders `{customer_name}`, `{amount}`, `{voucher_code}`, `{voucher_pin}`, `{package}`, `{transaction_id}`.
- SMS and email notifications are queued and processed via Docker `notifications` service every 60 seconds, manual dashboard action, or CLI cron `php scripts/notifications.php`. Attempts capped at five; inspect errors under Notifications.
- V8 supports payment confirmation and payment-held templates. Failed checkout redirects intentionally **do not automatically enqueue failure messages** because they are not authenticated gateway proof.

## Important limitations
- This V8 deployment candidate is not certified or end-to-end tested against live merchant systems, SMTP server, SMS provider or RouterOS.
- Current hosted checkout is operator initiated from the admin panel, not a public self-service portal.
- Production hardening still requires robust replay/reconciliation controls, payment expiry/retry design, notification retention and consent policies, rate limiting, support workflows, SMTP deliverability and operational monitoring.
- RouterOS legacy API requires private VPN network and auditing; FreeRADIUS is deployed separately in Docker. No automatic live bank refunds.
- Payment activation is idempotent on the voucher status check. Do not run manual router and RADIUS authentication on the same hotspot without a clear design.
- Before enabling real money, test gateway partial failures and duplicate IPN callbacks, risky status, wrong amount, expired credentials, queue retries, RADIUS login and offsite restore on staging.

## Provider references
https://developer.sslcommerz.com/
https://www.bulksmsbd.com/bulksms-api-bangladesh.php
