Get Company Wallets
Retrieve a paginated list of all company wallets with optional currency filtering.
This endpoint requires admin authorization.
GET /api/admin/wallets/companies
Query Parameters
Filter wallets by currency code (e.g., SAR, EGP) or symbol. Optional.
Page number for pagination. Automatically adjusted to 1 if less than 1.
Number of items per page. Must be between 1 and 100 (defaults to 20 if outside range).
Response Fields
Array of company wallet items
Company’s name (defaults to “غير معروف” if unavailable)
Wallet currency code (SAR, EGP, etc.)
Current available balance in wallet
Lifetime earnings from bookings
Total commission deducted
Net profit (earnings - commission)
Total amount deposited to wallet
Total amount withdrawn from wallet
Timestamp of last wallet update
Total number of company wallets
Example Request
curl -X GET "https://api.masareagle.sa/api/admin/wallets/companies?currency=SAR&page=1&pageSize=20" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
Example Response
{
"wallets": [
{
"companyId": "company_789",
"companyName": "شركة النقل الحديث",
"logoUrl": "https://storage.masareagle.sa/logos/company_789.png",
"currency": "SAR",
"walletBalance": 45000.00,
"totalEarnings": 250000.00,
"totalCommission": 25000.00,
"netProfit": 225000.00,
"totalDeposits": 50000.00,
"totalWithdrawals": 30000.00,
"lastUpdatedAt": "2026-03-10T11:00:00Z"
}
],
"totalCount": 15,
"page": 1,
"pageSize": 20,
"totalPages": 1
}
Get Company Wallet Transactions
Retrieve paginated transaction history for a specific company wallet.
GET /api/admin/wallets/companies/{companyId}/transactions
Path Parameters
Query Parameters
Currency code for the wallet (SAR, EGP, etc.)
Page number for pagination
Number of transactions per page (1-100)
Response Fields
Array of wallet transactions
Transaction type code (Deposit, Withdraw, Deduct, Add, Refund, Commission, Settlement)
Arabic display name for transaction type
Wallet balance before transaction
Wallet balance after transaction
Reference to related entity (booking ID, transfer ID, etc.)
Type of reference (Booking, Transfer, etc.)
User ID who performed the transaction
Type of performer (Admin, System, Company)
Transaction notes or description
Bank transfer reference number if applicable
UTC timestamp when transaction was created
Transaction currency code
Total number of transactions
Example Request
curl -X GET "https://api.masareagle.sa/api/admin/wallets/companies/company_789/transactions?currency=SAR&page=1&pageSize=10" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
Example Response
{
"transactions": [
{
"id": "tx_abc123",
"transactionType": "Settlement",
"transactionTypeDisplay": "إيداع إيرادات حجز",
"amount": 500.00,
"balanceBefore": 44500.00,
"balanceAfter": 45000.00,
"referenceId": "booking_xyz",
"referenceType": "Booking",
"performedBy": "system",
"performedByType": "System",
"notes": "Booking revenue settlement",
"bankTransferReference": null,
"createdAtUtc": "2026-03-10T11:00:00Z",
"currency": "SAR"
}
],
"totalCount": 150,
"page": 1,
"pageSize": 10,
"totalPages": 15
}
Transaction Types
| Type | Arabic Display | Description |
|---|
| Deposit | إيداع | Manual deposit by admin |
| Withdraw | سحب | Manual withdrawal by admin |
| Deduct | خصم عمولة | Commission deduction |
| Add | إضافة من حجز | Earnings from booking |
| Refund | استرجاع | Refund to company |
| Commission | عمولة | Commission transaction |
| Settlement | إيداع إيرادات حجز | Booking revenue settlement |
Deposit to Company Wallet
Add funds to a company’s wallet (admin operation).
POST /api/admin/companies/{companyId}/wallet/deposit
Path Parameters
Request Body
Amount to deposit. Must be positive.
Currency code (SAR, EGP, etc.) or symbol
Optional bank transfer or transaction reference number
Optional admin notes for this deposit
Response Fields
Indicates if deposit was successful
Success or error message in Arabic
Company’s new wallet balance after deposit
Example Request
curl -X POST "https://api.masareagle.sa/api/admin/companies/company_789/wallet/deposit" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000.00,
"currency": "SAR",
"transferReference": "COMP-DEP-20260310",
"notes": "Initial balance deposit"
}'
Example Response
{
"success": true,
"message": "تم إيداع 10000.00 SAR بنجاح",
"newBalance": 55000.00
}
Company wallets are auto-created if they don’t exist. A notification is sent to the company upon successful deposit.
Withdraw from Company Wallet
Withdraw funds from a company’s wallet (admin operation).
POST /api/admin/companies/{companyId}/wallet/withdraw
Path Parameters
Request Body
Amount to withdraw. Must be positive and not exceed wallet balance.
Currency code (SAR, EGP, etc.) or symbol
Optional bank transfer or transaction reference number
Optional admin notes for this withdrawal
Response Fields
Indicates if withdrawal was successful
Success or error message in Arabic
Company’s new wallet balance after withdrawal
Example Request
curl -X POST "https://api.masareagle.sa/api/admin/companies/company_789/wallet/withdraw" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000.00,
"currency": "SAR",
"transferReference": "COMP-WD-20260310",
"notes": "Company withdrawal request"
}'
Example Response
{
"success": true,
"message": "تم سحب 5000.00 SAR بنجاح",
"newBalance": 50000.00
}
Error Response
{
"success": false,
"message": "رصيد غير كافي",
"newBalance": null
}
Withdrawals will fail if the amount exceeds the available wallet balance. A withdrawal notification is sent to the company upon success.