# Subscription-Based Payment System ## Overview This document describes the design and flow of the subscription-based payment system for the Viso platform. Vendors can activate their services through a structured payment flow, while admins have full control over payment management and free trial grants. --- ## System Architecture ``` ┌─────────────────────────────────────────────────────────────────────┐ │ VISO PLATFORM │ │ │ │ ┌──────────────────────────┐ ┌──────────────────────────────┐ │ │ │ VENDOR APP │ │ ADMIN PANEL │ │ │ │ │ │ │ │ │ │ ① Add Services │ │ ① Payment List Page │ │ │ │ ② Select Services │◄──►│ ② Payment Detail Page │ │ │ │ ③ Review Charges │ │ - Manual Approval │ │ │ │ ④ Make Payment │ │ - Free Trial Grant │ │ │ │ ⑤ Confirmation │ │ │ │ │ └──────────────────────────┘ └──────────────────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ PAYMENT GATEWAY │ │ │ │ (Stripe / Telr / PayTabs / etc.) │ │ │ └─────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ DATABASE │ │ │ │ vendors | services | subscriptions | │ │ │ │ payments | service_activations │ │ │ └─────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## Vendor App Flow ### Step 1 — Add Services (Pending State) Vendors add their services via the existing service creation flow. After submission: - The service record is created in the database with status = `pending`. - The service is **NOT activated** until a successful payment is made. - Vendor sees a banner/notice: *"Your services are pending activation. Please complete payment to go live."* ``` Vendor Adds Service │ ▼ Service Created status = "pending" is_active = false │ ▼ Redirect to → Service Selection Page ``` --- ### Step 2 — Service Selection Page After adding services, the vendor lands on the **Service Selection Page**: - Lists all vendor's services that are in `pending` state. - Each service row has a **checkbox** for selection. - Each service displays its name, description, and individual charge/price. - Vendor can select one or multiple services to activate. ``` ┌─────────────────────────────────────────────────────────────┐ │ SELECT SERVICES TO ACTIVATE │ ├──────┬────────────────────────┬──────────────┬─────────────┤ │ [✓] │ Service Name │ Category │ Price/mo │ ├──────┼────────────────────────┼──────────────┼─────────────┤ │ [✓] │ Photography │ Media │ AED 150 │ │ [ ] │ Videography │ Media │ AED 200 │ │ [✓] │ Event Setup │ Logistics │ AED 300 │ │ [ ] │ Catering │ Food │ AED 250 │ └──────┴────────────────────────┴──────────────┴─────────────┘ [Proceed to Payment →] ``` --- ### Step 3 — Charge Calculation As the vendor selects/deselects services, the total is **dynamically calculated**: - Each selected service adds its price to the total. - A running subtotal is shown in real time (via JavaScript). - Breakdown is visible per service. ``` SELECTED SERVICES SUMMARY ───────────────────────────────────── Photography AED 150.00 Event Setup AED 300.00 ───────────────────────────────────── Subtotal AED 450.00 VAT (5%) AED 22.50 ───────────────────────────────────── TOTAL AED 472.50 ═════════════════════════════════════ ``` --- ### Step 4 — Payment - Vendor clicks **"Pay Now — AED 472.50"** button. - Redirected to the payment gateway (or an embedded payment form). - Payment captures: - Vendor ID - Selected service IDs - Total amount - Transaction reference ``` Vendor Clicks "Pay Now" │ ▼ Payment Gateway │ ┌────┴────┐ │ │ SUCCESS FAILED │ │ ▼ ▼ Webhook Webhook received received │ │ ▼ ▼ Activate Mark payment services as "failed" │ │ ▼ ▼ Redirect Redirect to to failure page confirm (retry option) page ``` --- ### Step 5 — Confirmation Page After successful payment: - A **Confirmation Page** is shown to the vendor. - Lists all activated services with a green checkmark. - Shows payment receipt details (transaction ID, date, amount). - Services are now `is_active = true` and visible on the vendor's public profile. ``` ┌──────────────────────────────────────────────────────────┐ │ ✅ PAYMENT SUCCESSFUL │ │ │ │ Transaction ID : TXN-20260721-0042 │ │ Amount Paid : AED 472.50 │ │ Date : 21 Jul 2026 │ │ │ │ ACTIVATED SERVICES: │ │ ✓ Photography │ │ ✓ Event Setup │ │ │ │ Your services are now LIVE on your profile. │ │ │ │ [View My Profile] [Add More Services] │ └──────────────────────────────────────────────────────────┘ ``` --- ## Admin Panel ### Page 1 — Payment List Displays all payment transactions across all vendors. ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ PAYMENT MANAGEMENT [Filter ▼] [Export] │ ├──────┬───────────────────┬──────────────┬────────────┬───────────┬──────────┤ │ # │ Vendor Name │ Services │ Amount │ Status │ Action │ ├──────┼───────────────────┼──────────────┼────────────┼───────────┼──────────┤ │ 001 │ Al Noor Events │ 3 services │ AED 650 │ ✅ Paid │ [View] │ │ 002 │ Luxe Catering │ 1 service │ AED 200 │ ❌ Failed│ [View] │ │ 003 │ Dubai Decor │ 2 services │ AED 450 │ 🎁 Trial │ [View] │ │ 004 │ Stars Media │ 4 services │ AED 900 │ ⏳ Pending│ [View] │ └──────┴───────────────────┴──────────────┴────────────┴───────────┴──────────┘ ``` **Filter options:** By status (Paid / Failed / Trial / Pending), Date range, Vendor name. **Status Badges:** | Badge | Meaning | |---|---| | ✅ Paid | Payment successful, services active | | ❌ Failed | Payment gateway returned failure | | 🎁 Trial | Admin granted free trial | | ⏳ Pending | Awaiting payment from vendor | --- ### Page 2 — Payment Detail Full detail view for a single payment record. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ PAYMENT DETAIL #002 │ ├─────────────────────────────────────────────────────────────────────┤ │ Vendor : Luxe Catering │ │ Contact : luxe@example.com | +971-50-000-0000 │ │ Transaction ID : TXN-20260720-0031 │ │ Amount : AED 200.00 │ │ Gateway Ref : PAY-GW-991234 │ │ Date : 20 Jul 2026 │ │ Status : ❌ FAILED │ │ Failure Reason : Card declined by issuing bank │ ├─────────────────────────────────────────────────────────────────────┤ │ SERVICES SELECTED │ │ ───────────────── │ │ • Videography AED 200.00 ⛔ Inactive │ ├─────────────────────────────────────────────────────────────────────┤ │ ADMIN ACTIONS │ │ │ │ [✅ Mark as Paid & Activate Services] │ │ Override failed payment → activate services manually. │ │ │ │ [🎁 Grant Free Trial] │ │ Activate services for a limited trial period (no charge). │ │ Duration: [ 7 days ▼ ] [ Apply Trial ] │ │ │ │ [📋 View Payment History for This Vendor] │ └─────────────────────────────────────────────────────────────────────┘ ``` --- #### Feature 1 — Manual Payment Approval (Failed → Active) When a payment has failed, the admin can manually override it: ``` Admin clicks "Mark as Paid & Activate Services" │ ▼ Confirmation prompt: "Are you sure you want to manually approve this payment and activate the vendor's selected services?" │ ┌─────────┴─────────┐ [Yes, Confirm] [Cancel] │ ▼ payment.status = "manually_approved" payment.approved_by = admin_id payment.approved_at = now() │ ▼ service_activations.is_active = true for each selected service │ ▼ Notify vendor via email/SMS: "Your payment has been approved and services are now active." │ ▼ Admin log entry created (audit trail) ``` --- #### Feature 2 — Free Trial Grant Admin can activate services for a vendor for a defined trial period without requiring payment: ``` Admin selects trial duration → clicks "Apply Trial" │ ▼ payment.status = "trial" trial_start = now() trial_end = now() + selected_duration granted_by = admin_id │ ▼ service_activations.is_active = true service_activations.trial_end = trial_end for each selected service │ ▼ Scheduled job checks daily: if (now() >= trial_end) → deactivate services notify vendor 3 days before trial ends │ ▼ Vendor notified: "Your free trial is active until [date]. Subscribe to continue using services." ``` **Trial Duration Options:** 7 days / 14 days / 30 days / Custom date --- ## Full End-to-End Flow Diagram ``` VENDOR SYSTEM ADMIN │ │ │ │── Add Service ───────────────►│ │ │ │ Service created (pending) │ │◄── Redirect to selection ─────│ │ │ │ │ │── Select services + checkbox ►│ │ │ │ Calculate total dynamically │ │◄── Show amount breakdown ─────│ │ │ │ │ │── Click "Pay Now" ───────────►│ │ │ │──► Payment Gateway │ │ │ │ │ ┌─────────┴──────────┐ │ │ PAYMENT SUCCESS PAYMENT FAILED │ │ │ │ │ │ ▼ ▼ │ │ Activate services Mark as failed │ │ Confirm page Notify vendor │ │ │ │ │ │◄── Admin reviews ─│ │ │ │ │ ┌─────┴───────┐ │ │ Manual Approve Free Trial │ │ │ │ │ │ ▼ ▼ │ │◄──────────── Services Activated ──┴──────────────┘ │ │ │ │ │── View active profile ───────►│ │ ``` --- ## Database Schema (Proposed) ### `services` table | Column | Type | Notes | |---|---|---| | id | bigint PK | | | vendor_id | bigint FK | | | name | varchar | | | description | text | | | price | decimal(10,2) | Monthly subscription price | | status | enum | `pending`, `active`, `inactive` | | is_active | boolean | | | created_at | timestamp | | ### `payments` table | Column | Type | Notes | |---|---|---| | id | bigint PK | | | vendor_id | bigint FK | | | transaction_id | varchar | Gateway transaction ref | | amount | decimal(10,2) | | | status | enum | `pending`, `paid`, `failed`, `manually_approved`, `trial` | | gateway_response | json | Raw response from gateway | | approved_by | bigint FK | Admin user ID (nullable) | | approved_at | timestamp | | | trial_start | timestamp | | | trial_end | timestamp | | | created_at | timestamp | | ### `payment_services` table (pivot) | Column | Type | Notes | |---|---|---| | id | bigint PK | | | payment_id | bigint FK | | | service_id | bigint FK | | | price_at_time | decimal(10,2) | Price snapshot at payment time | ### `service_activations` table | Column | Type | Notes | |---|---|---| | id | bigint PK | | | service_id | bigint FK | | | payment_id | bigint FK | | | is_active | boolean | | | activated_at | timestamp | | | expires_at | timestamp | null = no expiry (paid), date = trial expiry | | activation_type | enum | `payment`, `manual`, `trial` | --- ## Service Status Lifecycle ``` ┌─────────────────────────────────────────────────────┐ │ │ Vendor adds Payment Admin Manual Admin Trial service success Approve Grant │ │ │ │ ▼ ▼ ▼ ▼ PENDING ────────► ACTIVE ◄──────────────────────────── │ │ │ Trial expires / │ Admin deactivates │ │ └──────────► INACTIVE ◄── Vendor deactivates ``` --- ## Notifications | Event | Recipient | Channel | |---|---|---| | Services added (pending) | Vendor | In-app | | Payment successful | Vendor | Email + In-app | | Payment failed | Vendor | Email + In-app | | Admin manually approved | Vendor | Email + In-app | | Free trial granted | Vendor | Email + In-app | | Trial expiring in 3 days | Vendor | Email + In-app | | Trial expired | Vendor | Email + In-app | | New payment received | Admin | In-app / Dashboard | | Payment failed alert | Admin | In-app / Dashboard | --- ## Security Considerations - All payment webhook endpoints must verify the gateway signature before processing. - Admin override actions must be logged with admin ID, timestamp, and reason (audit trail). - Trial grants must be logged and cannot be applied more than once per vendor per service (configurable). - Payment amounts must be server-validated — never trust client-side totals. - PCI-DSS: Card data must never be stored; all sensitive data passes through the gateway only. --- *Document version: 1.0 | Created: 2026-07-21 | Project: Viso Admin — Subscription Payment System*