analysis/04-functional-spec/payments-and-financials-module.md

Payments & Financials

Payments & Financials Module – Functional Specification

1. Purpose

The Payments & Financials Module defines how monetary transactions are processed, stored, validated, and reported across MASARUK.

It unifies:

Online payments for bookings
Online payments for ad campaigns
VAT calculation
Recording financial transactions
Payout tracking for Providers
Integration with payment gateways
Financial reporting for Admins

2. Related Entities

Entity	Description
PaymentTransaction	Record of any payment attempt or completion.
Booking	Generates a PaymentTransaction upon success.
AdCampaign	Generates a PaymentTransaction upon creation.
User	Pays for bookings.
Provider	Receives payouts from completed trips.
FinancialRecord	Reflected in Admin Financial Reports.
Trip	Source of booking revenues.

3. Available Payment Methods

Credit Card

Credit Card via HyperPay

Mada

Saudi Debit Card

STC Pay

Mobile Payment

SADAD

Bill Payment

4. Data Fields

4.1 PaymentTransaction

Field	Type	Notes
id	UUID / PK	—
reference	String	Gateway reference / tracking number
user_id	FK	Required (payer)
provider_id	FK	For provider-origin campaigns
related_type	Enum	booking / ad_campaign
related_id	FK	booking_id or ad_campaign_id
amount	Decimal	Base amount
vat_amount	Decimal	VAT (differs per module)
grand_total	Decimal	amount + vat
payment_method	Enum	credit_card, mada, stc_pay, sadad
payment_status	Enum	pending / success / failed
created_at	timestamp	—
updated_at	timestamp	—

4.2 FinancialRecord (Admin Report Row)

Field	Notes
Transaction ID	PaymentTransaction.id or reference
Total Amount	amount
Platform Commission	commission
Date	created_at
Details	Trip/Booking/Ad text
Net Amount	amount - commission
Status	UI badge (Transferred / In Current Balance / Refunded)

5. VAT Rules

Bookings

15%

Standard Saudi VAT rate (platformSettings.vatRateDefault = 0.15)

Ad Campaigns

20%

⚠️ Logged in open-questions until business confirms

6. Financial Record States

PendingCompletedRefunded

Label	Meaning	Enum
In Current Balance	Funds held by system, not yet paid out	IN_CURRENT_BALANCE
Transferred	Paid out to provider	TRANSFERRED
Refunded	Refunded	REFUNDED

7. Business Rules

BR-1. Payment must succeed to create a booking

Booking creation occurs only when: payment_status = success

BR-2. Payments for Ad Campaigns require upfront payment

A provider cannot create an AdCampaign unless payment is completed. UI evidence: 'Pay [amount]' inside ad campaign modal.

BR-3. VAT rules differ by module

Bookings: 15% | Ad Campaigns: 20%

BR-4. Commission Rules

'Platform Commission' is stored per transaction. 'Net Amount' = amount - commission. Commission percentage is not shown in UI, so module must not assume any rate.

BR-5. Refund rules

Refund creates: A reversed transaction (negative row), Updated booking status → Cancelled, Updated transaction status → REFUNDED, Appears in financial report table.

8. Payment Lifecycle

PENDINGPending

Payment initiated, waiting for gateway response.

COMPLETEDCompleted

Payment captured successfully.

CANCELLEDCancelled

Payment failed or refunded.

PENDING → COMPLETED      (Gateway callback OK)
PENDING → CANCELLED      (Gateway failure or timeout)
COMPLETED → CANCELLED    (Refund action by admin)

10. Financial KPI Cards (Admin)

إجمالي المبيعات

Total Sales

عمولة المنصة

Platform Commission

الإيرادات

Revenue

صافي الأرباح

Net Profit

11. My Credit / رصيدي (Slice 5)

SSOT: analysis/04-functional-spec/payments-and-financials-module.md §11

⚠️ NOT an e-wallet — This is Store Credit only. No withdrawals, no top-ups.

Store credit balance usable only for bookings on the platform.

Forbidden Features (Legal Compliance)

❌ Withdrawals (سحب)
❌ Top-ups / Deposits (شحن/إيداع)
❌ Transfer to other users
❌ External bank transfer

Allowed Credit Sources (DEC-S5-02 ✅)

✅ Refunds — Default destination (DEC-S5-01)
✅ Admin Gift (هدية) — Manual promotional credit
✅ Admin Compensation (تعويض) — Customer service resolution

Official Decisions ✅

• DEC-S5-01 ✅ Credit is DEFAULT refund destination; Card is exception (Admin override)
• DEC-S5-02 ✅ Credit sources = Refunds + Admin adjustments (Gift/Compensation)

12. Refund Processing (Slice 10)

SSOT: analysis/04-functional-spec/payments-and-financials-module.md §12

12.1 Refund Destination (DEC-S5-01)

My Credit (Default)

Instant credit to user balance

سيتم إضافة المبلغ إلى رصيدك

Card (Exception) [PROPOSED]

5-14 business days (estimate, not commitment), Admin approval required

قد يستغرق 5-14 يوم عمل (تقدير)

12.2 Refund States

State	Arabic	Description
NONE	لا يوجد	No refund (0% tier) — DEC-S10-01 OFFICIAL
PENDING	معلق	Refund initiated — DEC-S10-01 OFFICIAL
PROCESSING	جاري المعالجة	Card refund in progress — DEC-S10-01 OFFICIAL
COMPLETED	مكتمل	Refund finalized — DEC-S10-01 OFFICIAL
FAILED	فشل	Card refund failed — DEC-S10-01 OFFICIAL

12.3 Admin Actions

Process refund to Credit (default)
Approve refund to Card (exception, requires reason)
Add credit adjustment (Gift/Compensation)

12.4 Notification Wording (Slice 11)

SSOT: notifications-and-messaging-module.md §13

Event	In-App	Email/SMS
Refund to Credit	In-App [OFFICIAL] §13.6	[PROPOSED]
Admin Gift	In-App [OFFICIAL] §13.7	[PROPOSED]
Admin Compensation	In-App [OFFICIAL] §13.7	[PROPOSED]