Bank Transfers & Wallet Top-Up

Overview

Bank transfers provide an alternative payment method for users who prefer traditional banking. The system supports wallet top-ups and trip payment transfers with admin verification and approval.

Request Wallet Top-Up

Submit a bank transfer receipt to request wallet top-up.

POST /api/wallet/top-up/bank-transfer

This endpoint accepts multipart/form-data for file upload. Users must upload a receipt image.

Request Parameters

bankAccountId

string

required

ID of the platform bank account where transfer was sent

amount

string

required

Amount transferred (can include currency symbols, will be parsed)

note

string

required

User’s note describing the transfer

receiptImage

file

Receipt image file (JPG, JPEG, PNG, GIF, WEBP - max 10MB)

Response Fields

success

boolean

required

Indicates if request was submitted successfully

message

string

required

Status message in Arabic

transferId

string

Unique transfer request ID

status

string

Transfer status (Pending, Approved, Rejected)

Supported User Types

Passenger: Top up passenger wallet
Driver: Top up driver wallet
Company: Top up company wallet

Example Request

curl -X POST "https://api.masareagle.sa/api/wallet/top-up/bank-transfer" \
  -H "Authorization: Bearer USER_TOKEN" \
  -F "bankAccountId=bank_acc_123" \
  -F "amount=500 SAR" \
  -F "note=Wallet top-up via Al Rajhi Bank" \
  -F "receiptImage=@/path/to/receipt.jpg"

Success Response

{
  "success": true,
  "message": "تم إرسال طلب شحن المحفظة للمراجعة. سيتم إشعارك عند الموافقة.",
  "transferId": "bt_a1b2c3d4e5f6",
  "status": "Pending"
}

Error Responses

Invalid File Type:

{
  "success": false,
  "message": "نوع الملف غير مدعوم. الأنواع المسموح بها: JPG, JPEG, PNG, GIF, WEBP"
}

File Too Large:

{
  "success": false,
  "message": "حجم الملف كبير جداً. الحد الأقصى 10 ميجابايت"
}

Bank Account Not Active:

{
  "success": false,
  "message": "الحساب البنكي غير مفعل حالياً"
}

Receipt images are uploaded to cloud storage in organized folders by year and month. A pending review notification is automatically sent to admins.

Get Pending Bank Transfers (Admin)

Retrieve all pending bank transfer requests awaiting review.

GET /api/admin/bank-transfers/pending

Query Parameters

page

integer

default:"1"

Page number for pagination

pageSize

integer

default:"20"

Number of items per page (1-100)

Response Fields

success

boolean

required

Request success indicator

message

string

required

Status message

bankTransfers

array

Array of pending transfer requests

Show transfer object

string

required

Transfer ID

userType

string

Type of user (Passenger, Driver, Company)

userName

string

User’s name

userPhone

string

User’s phone number

transferType

string

required

Transfer type (WalletTopUp, BookingPayment)

requestedAmount

string

Original amount string entered by user

amount

decimal

required

Parsed transfer amount

currency

string

required

Currency code

note

string

User’s transfer note

receiptImageUrl

string

URL to uploaded receipt image

bankAccount

object

Bank account details where money was sent

booking

object

Booking details if transfer is for trip payment

createdAt

datetime

required

When transfer request was created

pagination

object

Pagination metadata

Show pagination object

page

integer

Current page

pageSize

integer

Items per page

totalCount

integer

Total number of pending transfers

totalPages

integer

Total pages

hasPreviousPage

boolean

Has previous page

hasNextPage

boolean

Has next page

Example Request

curl -X GET "https://api.masareagle.sa/api/admin/bank-transfers/pending?page=1&pageSize=20" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Example Response

{
  "success": true,
  "message": "تم جلب الحوالات المعلقة بنجاح",
  "bankTransfers": [
    {
      "id": "bt_xyz789",
      "userType": "Passenger",
      "userName": "محمد أحمد",
      "userPhone": "+966501234567",
      "transferType": "WalletTopUp",
      "requestedAmount": "500 ريال",
      "amount": 500.00,
      "currency": "SAR",
      "note": "Transferred via Al Rajhi Bank",
      "receiptImageUrl": "https://storage.masareagle.sa/receipts/2026/03/receipt_xyz.jpg",
      "bankAccount": {
        "id": "bank_123",
        "bankName": "Al Rajhi Bank",
        "accountNumber": "SA1234567890123456789012",
        "displayInfo": "Al Rajhi Bank - SA12****9012"
      },
      "createdAt": "2026-03-10T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 5,
    "totalPages": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

Approve Bank Transfer (Admin)

Approve a pending bank transfer for trip payment.

POST /api/admin/bank-transfers/{transferId}/approve

This endpoint is for trip payment transfers. For wallet top-ups, use the Approve Wallet Top-Up endpoint.

Path Parameters

transferId

string

required

The transfer request ID

Request Body

adminNotes

string

Optional admin notes for the approval

Response Fields

success

boolean

required

Approval success indicator

message

string

required

Status message in Arabic

Approval Process

Validate Transfer: Check transfer exists and is pending
Currency Normalization: Convert currency symbols to codes
Passenger Wallet Operations:
- Deposit transfer amount to passenger wallet
- Deduct amount for booking payment
- Validate sufficient balance (fraud check)
Driver Wallet Operations:
- Calculate commission
- Add booking amount to driver wallet
Booking Update: Set payment method to Wallet and confirm booking
Notifications: Send approval notifications to passenger and driver

Example Request

curl -X POST "https://api.masareagle.sa/api/admin/bank-transfers/bt_xyz789/approve" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adminNotes": "Receipt verified - Al Rajhi Bank transfer confirmed"
  }'

Success Response

{
  "success": true,
  "message": "تم قبول الحوالة بنجاح"
}

Error Responses

Transfer Not Found:

{
  "success": false,
  "message": "الحوالة غير موجودة"
}

Not Pending:

{
  "success": false,
  "message": "الحوالة ليست في حالة معلقة. الحالة الحالية: Approved"
}

Fraud Detected:

{
  "success": false,
  "message": "الحوالة مزيفة - الراكب لا يملك رصيد كافي"
}

The fraud detection works by depositing the amount, then immediately attempting to deduct it. If deduction fails, the transfer is marked as fraudulent and rejected.

Approve Wallet Top-Up (Admin)

Approve a wallet top-up request and add funds to user’s wallet.

POST /api/admin/wallet-top-up/{transferId}/approve

Path Parameters

transferId

string

required

The wallet top-up request ID

Request Body

approvedAmount

decimal

required

Amount to add to wallet. Admin can adjust from requested amount.

adminNotes

string

Optional admin notes explaining approval or adjustment

Response Fields

success

boolean

required

Approval success indicator

message

string

required

Status message

approvedAmount

decimal

Amount approved and added to wallet

newBalance

decimal

User’s new wallet balance

Wallet Auto-Creation

Driver Wallets: Must exist, will fail if not found
Passenger Wallets: Must exist, will fail if not found
Company Wallets: Auto-created if they don’t exist

Example Request

curl -X POST "https://api.masareagle.sa/api/admin/wallet-top-up/bt_abc123/approve" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approvedAmount": 500.00,
    "adminNotes": "Verified Al Rajhi transfer - receipt matches"
  }'

Success Response

{
  "success": true,
  "message": "تم الموافقة على طلب شحن المحفظة وإضافة المبلغ",
  "approvedAmount": 500.00,
  "newBalance": 1250.50
}

Approval with Amount Adjustment

curl -X POST "https://api.masareagle.sa/api/admin/wallet-top-up/bt_abc123/approve" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approvedAmount": 450.00,
    "adminNotes": "Adjusted amount - transfer fees deducted"
  }'

If the approved amount differs from the requested amount, the admin notes should explain the adjustment. The original amount is preserved in the transfer record.

Reject Wallet Top-Up (Admin)

Reject a wallet top-up request with a reason.

POST /api/admin/wallet-top-up/{transferId}/reject

Path Parameters

transferId

string

required

The wallet top-up request ID

Request Body

rejectionReason

string

required

Reason for rejection (required)

adminNotes

string

Optional additional admin notes

Response Fields

success

boolean

required

Rejection success indicator

message

string

required

Status message

Example Request

curl -X POST "https://api.masareagle.sa/api/admin/wallet-top-up/bt_abc123/reject" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rejectionReason": "Receipt image is unclear and cannot be verified",
    "adminNotes": "Please resubmit with clearer image"
  }'

Success Response

{
  "success": true,
  "message": "تم رفض طلب شحن المحفظة"
}

Rejection notifications are sent to users explaining why their request was denied. Users can submit a new request with corrections.

Transfer Statuses

Status	Description	Next Actions
Pending	Awaiting admin review	Admin can approve or reject
Approved	Transfer verified and funds added	No further action
Rejected	Transfer declined by admin	User can submit new request

Best Practices

For Users

Clear Receipt Images: Ensure transfer receipt shows amount, date, and reference
Accurate Amount: Enter the exact amount transferred
Descriptive Notes: Mention bank name and transfer method
Supported Formats: Use JPG, PNG, or WEBP under 10MB

For Admins

Verify Receipt Details: Check amount, bank account, and timestamp
Cross-Reference: Match receipt with bank statement
Document Adjustments: Always explain amount changes in notes
Timely Review: Process requests within 24 hours for better UX
Fraud Detection: Watch for duplicate receipts or mismatched amounts

For high-volume operations, consider implementing OCR (Optical Character Recognition) to auto-extract amount and reference from receipt images.

Overview

Identity Service

Users Service

Trips Service

Wallet & Payments

Admin APIs

Notifications

​Overview

​Request Wallet Top-Up

​Request Parameters

​Response Fields

​Supported User Types

​Example Request

​Success Response

​Error Responses

​Get Pending Bank Transfers (Admin)

​Query Parameters

​Response Fields

​Example Request

​Example Response

​Approve Bank Transfer (Admin)

​Path Parameters

​Request Body

​Response Fields

​Approval Process

​Example Request

​Success Response

​Error Responses

​Approve Wallet Top-Up (Admin)

​Path Parameters

​Request Body

​Response Fields

​Wallet Auto-Creation

​Example Request

​Success Response

​Approval with Amount Adjustment

​Reject Wallet Top-Up (Admin)

​Path Parameters

​Request Body

​Response Fields

​Example Request

​Success Response

​Transfer Statuses

​Best Practices

​For Users

​For Admins

Build docs developers (and LLMs) love

Overview

Request Wallet Top-Up

Request Parameters

Response Fields

Supported User Types

Example Request

Success Response

Error Responses

Get Pending Bank Transfers (Admin)

Query Parameters

Response Fields

Example Request

Example Response

Approve Bank Transfer (Admin)

Path Parameters

Request Body

Response Fields

Approval Process

Example Request

Success Response

Error Responses

Approve Wallet Top-Up (Admin)

Path Parameters

Request Body

Response Fields

Wallet Auto-Creation

Example Request

Success Response

Approval with Amount Adjustment

Reject Wallet Top-Up (Admin)

Path Parameters

Request Body

Response Fields

Example Request

Success Response

Transfer Statuses

Best Practices

For Users

For Admins