🪙 Wallet System API

Points System

• 1 Knot = 100 Points (display unit)
• 1 OMR = 100 Points (currency conversion for top-ups)
• Top-Up Commission: 3% added to the base amount (buyer pays base + 3%)
• Price Guard: P2P trades limited to 950-1000 baisas per Knot
• Annual Mint Limit: 1,000,000 points per merchant

Authentication

All endpoints require JWT Bearer token unless marked as Public

Authorization: Bearer <jwt_token>

Base URL

/wallet

Get current user's wallet balance

Response

{
  "points": 50000,
  "knots": 50,
  "frozenPoints": 5000,
  "frozenKnots": 5,
  "availablePoints": 45000,
  "availableKnots": 45
}

Get another user's wallet balance (public info)

Get current user's transaction history

Initiate a top-up to buy points (default gateway: Thawani). To force EdfaPay, pass gateway=edfapay.

Request Body

Response

{
  "topUpId": "uuid",
  "redirectUrl": "https://checkout.thawani.om/pay/...",
  "pointsToCredit": 5000,
  "amountInCurrency": 51.50,
  "currency": "OMR"
}

amountInCurrency: Stored/returned in OMR major units (2 decimals) and includes the 3% commission.

Get user's top-up history

Transfer points to another user

Set custom escrow/shipping duration for an order (must be called before checkout)

Pay for an order with points (creates escrow)

Confirm delivery (buyer only). For points-based orders, delivery confirmation must be done by the assigned carrier via /shipments/:shipmentId/confirm-delivery

Carrier confirms pickup from merchant/company (must be the assigned carrier unless admin)

Carrier confirms delivery to customer. For points-based orders, this releases escrow and completes the order

Mark order as shipped (seller only)

Cancel order and refund escrow (buyer or seller)

List all open trade offers

List user's trades

Create a trade offer (sell points)

Request to buy from a trade offer

Seller approves buyer's request (freezes seller's points)

Buyer completes trade (after external payment)

Cancel trade (unfreezes points if approved)

Mint points directly for a user

Response

{
  "success": true,
  "message": "Minted 1000 points for user",
  "transaction": { "id": "...", "amount": "1000", ... },
  "newBalance": "5000"
}

List verified charities

Get charity by slug (for donation pages/QR codes)

Get charity details

Get charity's donation history

Register a new charity profile

Update charity profile (owner only)

Donate points to a charity

Donate by charity slug (for QR code donations)

Create a withdrawal request (convert points to bank transfer)

Response

{
  "id": "uuid",
  "amount": "10000",
  "status": "pending",
  "bankName": "Bank Muscat",
  "accountNumber": "1234567890",
  "reason": "selling_various_materials",
  "attachmentUrl": "https://example.com/doc.pdf",
  "reasonNotes": null,
  "currencyAmount": "10000",
  "currency": "OMR"
}

Get user's withdrawal request history

Get details of a specific withdrawal request

Cancel a pending withdrawal request (restores frozen points)

Get wallet system statistics

Response

{
  "totalCirculatingPoints": 50000000,
  "totalFrozenPoints": 1000000,
  "totalUsersWithWallet": 1250,
  "totalTopUpAmountInCurrency": 45000000,
  "currency": "OMR"
}

Get platform profit reports (weekly / monthly / yearly) aggregated by period and side (buyer/seller)

Example

GET /admin/profit/reports?period=monthly&from=2026-01-01&to=2026-12-31

Response

[
  {
    "period": "2026-01-01T00:00:00.000Z",
    "side": "buyer",
    "totalQuantity": 1500,
    "totalSar": 15,
    "totalPoints": 1500
  },
  {
    "period": "2026-01-01T00:00:00.000Z",
    "side": "seller",
    "totalQuantity": 1500,
    "totalSar": 15,
    "totalPoints": 1500
  }
]

Get full dashboard with wallet and audit stats

Get detailed dashboard with date range

List all mint requests

Approve a mint request (requires 2 different admins)

Reject a mint request

List all charities (including pending)

Verify a charity (enables donations)

List all withdrawal requests

Get count of pending withdrawal requests (for dashboard badge)

Response

5

Mark withdrawal as completed after bank transfer

Reject a withdrawal request (restores user's frozen points)

Get audit logs with filtering

Advanced audit log search

Get critical security events

Get all audit logs for a specific user

Get audit statistics

Get detailed user wallet info (balance, transactions, audit logs)

Freeze points in user's wallet

Unfreeze points in user's wallet

Adjust user's balance (for corrections)

EdfaPay payment callback (called by EdfaPay servers)

Thawani payment callback (called by Thawani servers)

EdfaPay 3DS return handler (user redirect after 3DS)

Wallet

User's point balance and statistics

WalletTransaction

Record of all point movements

TopUp

Payment gateway top-up records

Escrow

Buyer protection for order payments

Order (Escrow Fields)

Order entity fields related to escrow

P2PTrade

Peer-to-peer point trading offers

MintRequest

Merchant requests to mint new points

Charity

Verified charity profiles for donations

WithdrawalRequest

User requests to withdraw points to bank account

WalletAuditLog

Audit trail for all wallet actions

Notification Events

All wallet actions trigger email notifications to relevant users

Audit Actions

All wallet operations are logged with full context

Logged Information

• User ID and action timestamp
• Points amount and balance after
• Related entity (topup, escrow, trade, etc.)
• IP address and user agent
• Admin who performed action (if applicable)
• Custom metadata (JSON)

Required Environment Variables

# SMTP Configuration (Email)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-username
SMTP_PASS=your-password
MAIL_FROM=Invare <support@invare.sa>

# App Settings
APP_NAME=Invare
SUPPORT_EMAIL=support@invare.sa

# EdfaPay Configuration
EDFAPAY_API_BASE=https://api.edfapay.com
EDFAPAY_MERCHANT_ID=your-merchant-id
EDFAPAY_PASSWORD=your-password
EDFAPAY_CURRENCY=OMR

System Constants

Scheduled Jobs