# SSLCommerz + SaaS Billing Checklist

এই backend এখন SSLCommerz-ready structure পেয়ে গেছে।
নিচের items complete করলে local থেকে production flow চালাতে পারবেন।

## 1. Environment লাগবে

`server/.env` এ add করুন:

- `PORT=5000`
- `MONGO_URI=mongodb://127.0.0.1:27017/hr-harmony-saas`
- `APP_URL=http://localhost:5173`
- `BACKEND_BASE_URL=http://localhost:5000`
- `JWT_ACCESS_SECRET=...`
- `JWT_REFRESH_SECRET=...`
- `SMTP_HOST=...`
- `SMTP_PORT=587`
- `SMTP_USER=...`
- `SMTP_PASS=...`
- `MAIL_FROM=...`
- `SSLCOMMERZ_IS_LIVE=false` (sandbox)
- `SSLCOMMERZ_STORE_ID=...`
- `SSLCOMMERZ_STORE_PASSWORD=...`

## 2. Plans setup

Plans now support:
- `free`
- `weekly`
- `monthly`
- `yearly`

Default plan seed endpoint:
- `POST /api/v1/billing/plans/seed-defaults` (super_admin auth required)

Public active plans:
- `GET /api/v1/billing/plans/active`

## 3. Payment flow (SSLCommerz)

### Start checkout
- `POST /api/v1/billing/payments/init`
- auth required + tenant required
- body: `{ "planCode": "monthly", "customerName": "...", "customerEmail": "...", "customerPhone": "..." }`

### Callback endpoints (SSLCommerz)
- `POST /api/v1/billing/payments/success`
- `POST /api/v1/billing/payments/fail`
- `POST /api/v1/billing/payments/cancel`
- `POST /api/v1/billing/payments/ipn`

### User payment history
- `GET /api/v1/billing/payments/my`

## 4. Free vs Paid behavior

- Free plan: no gateway payment needed, subscription directly active
- Paid plans (weekly/monthly/yearly): SSLCommerz checkout session required
- Success callback validates `val_id` via SSLCommerz validator API

## 5. Route coverage check

Billing routes now include:
- plan routes
- payment routes
- subscription CRUD routes
- invoice CRUD routes

## 6. What is already added in code

- Plan model
- PaymentTransaction model
- Subscription updated for SSLCommerz + intervals
- SSLCommerz utility for init + validation
- Plan controller (active list + seed + CRUD)
- Payment controller (init/success/fail/cancel/ipn/history)
- Env example updated

## 7. Before production

- Set `SSLCOMMERZ_IS_LIVE=true`
- Use live store credentials
- Set HTTPS backend URL in `BACKEND_BASE_URL`
- Add signature verification rules if required by SSLCommerz account policy
- Add retry/queue for webhook resilience

## 8. SSLCommerz Developer Testing Checklist (Live Go-Forward)

SSLCommerz authority will check/test the following scenarios before moving your account to "Live" status limit. Your backend handles all of these, but you must manually run them on sandbox:

1. **Success Flow Test**: Complete a dummy transaction using their sandbox card. System must successfully catch the `POST` payload at the `/success` callback and mark Invoice as `Paid`.
2. **Fail Flow Test**: Use a reject-testing card. System must route to `/fail` and mark log/transaction as `Failed` without crashing. 
3. **Cancel Flow Test**: Start a payment -> Do not pay -> Click "Cancel". Must route to `/cancel`.
4. **Validation (val_id) Check**: Extremely important. Your backend must call their Validation API using the returned `val_id` to ensure no one manipulated the HTML amount. (Our code already handles this securely).
5. **IPN (Instant Payment Notification) Test**: Close the browser midway through success. IPN listener must still execute and confirm the database update.

## 9. Required Test Report exactly what to submit to SSLCommerz

To get your Live Credentials, reply to their onboarding integration email with:

1. **Successful Transaction ID:** Provide the exact `tran_id` for a successful Sandbox test. 
2. **Failed Transaction ID:** Provide the `tran_id` for a declined test.
3. **Validation Code (val_id):** Provide your received `val_id` showing you successfully intercepted their validation structure.
4. **IPN Execution Proof:** A screenshot of your terminal/database showing the IPN ping successfully updated your user's Subscriptions.
5. **Screenshots:** Attach screenshots of the frontend Checkout Button -> SSLCommerz pop-up -> Your beautiful "Payment Success / Subscription Active" redirect page.