Booking Management

Book Seat (Driver Trip)

Book one or more seats on a driver-created trip. Supports multiple payment methods including cash, wallet, Moyasar, and bank transfer.

Two versions available:

/api/trips/{tripId}/book-seat - JSON body (legacy)
/api/v1/trips/{tripId}/book-seat - Form data with image upload support

curl -X POST "https://api.masareagles.com/api/trips/{tripId}/book-seat" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "passengerId": "psng_abc123",
    "requestedSeatsCount": 2,
    "paymentMethod": "Cash"
  }'

Endpoint

method

string

required

POST

url

string

required

/api/trips/{tripId}/book-seat (JSON) or /api/v1/trips/{tripId}/book-seat (Form Data)

tripId

string

required

Trip identifier

Request Body (JSON Version)

passengerId

string

required

Passenger identifier

requestedSeatsCount

integer

required

Number of seats to book (1-100)

paymentMethod

string

Payment method: Cash, Wallet, Moyasar, BankTransfer (default: Cash)

bankTransferData

object

Bank transfer details (required if paymentMethod is BankTransfer)

Show Bank Transfer Data

bankAccountId

string

required

Company bank account identifier

note

string

Transfer note or reference number

Request Body (Form Data Version)

passengerId

string

required

Passenger identifier

requestedSeatsCount

integer

required

Number of seats to book

paymentMethod

string

Payment method

bankAccountId

string

Bank account ID (required for bank transfer)

note

string

Transfer note (required for bank transfer)

receiptImage

file

Receipt image file (JPG, JPEG, PNG, GIF, WEBP). Max size: 10MB. Required for bank transfers.

Response

success

boolean

Indicates if booking was successful

message

string

Success or error message in Arabic

bookingId

string

Unique booking identifier

totalPrice

decimal

Total booking cost

bookingDate

string

Booking creation timestamp

currency

string

Price currency code

requiresPayment

boolean

Whether payment is required (true for Moyasar)

paymentOrderId

string

Moyasar payment order ID (for Moyasar payments)

publishableKey

string

Moyasar publishable key (for Moyasar payments)

{
  "success": true,
  "message": "تم حجز المقعد بنجاح",
  "bookingId": "bkg_abc123xyz",
  "totalPrice": 300.00,
  "bookingDate": "2026-03-10T10:45:00Z",
  "currency": "SAR",
  "requiresPayment": false
}

Create Company Trip Booking

Create a booking for a company trip route. Passenger specifies exact pickup/dropoff locations and trip date/time.

curl -X POST "https://api.masareagles.com/api/trips/{tripId}/bookings" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "tripDateTime=2026-03-15T08:00:00Z" \
  -F "pickupLatitude=24.7136" \
  -F "pickupLongitude=46.6753" \
  -F "pickupAddress=King Khalid International Airport" \
  -F "dropoffLatitude=26.4207" \
  -F "dropoffLongitude=50.0888" \
  -F "dropoffAddress=King Fahd International Airport" \
  -F "paymentMethod=Cash"

Endpoint

method

string

required

POST

url

string

required

/api/trips/{tripId}/bookings

tripId

string

required

Company trip route identifier

Request Body (Form Data)

tripDateTime

string

required

Desired trip date and time in UTC (ISO 8601 format)

pickupLatitude

decimal

required

Pickup location latitude

pickupLongitude

decimal

required

Pickup location longitude

pickupAddress

string

Detailed pickup address

dropoffLatitude

decimal

required

Dropoff location latitude

dropoffLongitude

decimal

required

Dropoff location longitude

dropoffAddress

string

Detailed dropoff address

paymentMethod

string

Payment method: Cash, Wallet, Moyasar, BankTransfer (default: Cash)

bankAccountId

string

Company bank account ID (required if paymentMethod is BankTransfer)

note

string

Transfer note or reference (for bank transfer)

receiptImage

file

Bank transfer receipt image (JPG, JPEG, PNG, GIF, WEBP, PDF). Max size: 10MB.

Response

success

boolean

Indicates if booking was created successfully

message

string

Success or error message

data

object

Booking details

Show Booking Data

bookingId

string

Unique booking identifier

bookingNumber

string

Human-readable booking number

tripId

string

Trip route identifier

status

string

Booking status (e.g., “Pending”, “Confirmed”)

paymentStatus

string

Payment status (e.g., “Pending”, “Paid”)

amountPaid

decimal

Total amount paid

currency

string

Currency code

tripDateTime

string

Scheduled trip date/time

requiresPayment

boolean

Whether online payment is required

paymentOrderId

string

Moyasar order ID (if applicable)

publishableKey

string

Moyasar publishable key (if applicable)

bankTransferId

string

Bank transfer record ID (if applicable)

{
  "success": true,
  "message": "تم إنشاء الحجز بنجاح",
  "data": {
    "bookingId": "bkg_comp789",
    "bookingNumber": "BKNG-2026-001234",
    "tripId": "comptrip_abc123",
    "status": "Pending",
    "paymentStatus": "Pending",
    "amountPaid": 200.00,
    "currency": "SAR",
    "tripDateTime": "2026-03-15T08:00:00Z",
    "requiresPayment": false,
    "bankTransferId": "bt_xyz456"
  }
}

Accept Booking

Driver accepts a pending booking request.

curl -X POST "https://api.masareagles.com/api/bookings/{bookingId}/accept" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "driverId": "drv_xyz789",
    "driverNotes": "Confirmed pickup at terminal 1",
    "reason": "Passenger verified"
  }'

Endpoint

method

string

required

POST

url

string

required

/api/bookings/{bookingId}/accept

bookingId

string

required

Booking identifier

Request Body

driverId

string

required

Driver identifier

driverNotes

string

Optional notes from driver

reason

string

Optional reason for acceptance

Response

success

boolean

Indicates if booking was accepted

message

string

Result message

bookingId

string

Booking identifier

status

string

New booking status (typically “Confirmed”)

{
  "success": true,
  "message": "تم قبول الحجز بنجاح",
  "bookingId": "bkg_abc123",
  "status": "Confirmed"
}

Reject Booking

Driver rejects a pending booking request.

curl -X POST "https://api.masareagles.com/api/bookings/{bookingId}/reject" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "driverId": "drv_xyz789",
    "rejectionReason": "Schedule conflict"
  }'

Endpoint

method

string

required

POST

url

string

required

/api/bookings/{bookingId}/reject

Request Body

driverId

string

required

Driver identifier

rejectionReason

string

Reason for rejection

Response

success

boolean

Indicates if booking was rejected

message

string

Result message

bookingId

string

Booking identifier

status

string

New booking status (typically “Rejected”)

{
  "success": true,
  "message": "تم رفض الحجز",
  "bookingId": "bkg_abc123",
  "status": "Rejected"
}

Cancel Booking

Passenger cancels their own booking.

curl -X POST "https://api.masareagles.com/api/bookings/{bookingId}/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "passengerId": "psng_abc123",
    "reason": "Change of plans"
  }'

Endpoint

method

string

required

POST

url

string

required

/api/bookings/{bookingId}/cancel

Request Body

passengerId

string

required

Passenger identifier

reason

string

Cancellation reason

Response

success

boolean

Indicates if cancellation succeeded

message

string

Result message in Arabic

bookingId

string

Booking identifier

status

string

New booking status (typically “Cancelled”)

{
  "success": true,
  "message": "تم إلغاء الحجز بنجاح",
  "bookingId": "bkg_abc123",
  "status": "Cancelled"
}

Get Driver Bookings

Retrieve all bookings for a specific driver, optionally filtered by status.

curl -X GET "https://api.masareagles.com/api/drivers/{driverId}/bookings" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint

method

string

required

GET

url

string

required

/api/drivers/{driverId}/bookings

driverId

string

required

Driver identifier

Query Parameters

status

string

Filter by booking status (e.g., “Pending”, “Confirmed”, “Cancelled”)

Response

success

boolean

Indicates if request succeeded

message

string

Result message

bookings

array

Array of booking objects

Show Booking Item

string

Booking identifier

tripId

string

Associated trip ID

passengerId

string

Passenger identifier

passengerName

string

Passenger name

passengerProfileImage

string

Passenger profile image URL

passengerRating

decimal

Passenger rating

requestedSeatsCount

integer

Number of seats booked

totalPrice

decimal

Total booking price

status

string

Booking status

paymentMethod

string

Payment method used

bankTransferMessage

string

Bank transfer notes (if applicable)

requestedAtUtc

string

Booking request timestamp

confirmedAtUtc

string

Confirmation timestamp

driverNotes

string

Driver’s notes

rejectionReason

string

Rejection reason (if rejected)

{
  "success": true,
  "message": "تم جلب الحجوزات بنجاح",
  "bookings": [
    {
      "id": "bkg_abc123",
      "tripId": "trip_xyz789",
      "passengerId": "psng_def456",
      "passengerName": "Sara Al-Mutairi",
      "passengerProfileImage": "https://cdn.example.com/passengers/sara.jpg",
      "passengerRating": 4.9,
      "requestedSeatsCount": 2,
      "totalPrice": 300.00,
      "status": "Pending",
      "paymentMethod": "Cash",
      "requestedAtUtc": "2026-03-10T09:30:00Z",
      "bookingDate": "2026-03-15T08:00:00Z",
      "createdAtUtc": "2026-03-10T09:30:00Z",
      "updatedAtUtc": "2026-03-10T09:30:00Z"
    }
  ]
}

Overview

Identity Service

Users Service

Trips Service

Wallet & Payments

Admin APIs

Notifications

Book Seat (Driver Trip)

Endpoint

Request Body (JSON Version)

Request Body (Form Data Version)

Response

Create Company Trip Booking

Endpoint

Request Body (Form Data)

Response

Accept Booking

Endpoint

Request Body

Response

Reject Booking

Endpoint

Request Body

Response

Cancel Booking

Endpoint

Request Body

Response

Get Driver Bookings

Endpoint

Query Parameters

Response

Build docs developers (and LLMs) love

Overview

Identity Service

Users Service

Trips Service

Wallet & Payments

Admin APIs

Notifications

​Book Seat (Driver Trip)

​Endpoint

​Request Body (JSON Version)

​Request Body (Form Data Version)

​Response

​Create Company Trip Booking

​Endpoint

​Request Body (Form Data)

​Response

​Accept Booking

​Endpoint

​Request Body

​Response

​Reject Booking

​Endpoint

​Request Body

​Response

​Cancel Booking

​Endpoint

​Request Body

​Response

​Get Driver Bookings

​Endpoint

​Query Parameters

​Response

Build docs developers (and LLMs) love

Book Seat (Driver Trip)

Endpoint

Request Body (JSON Version)

Request Body (Form Data Version)

Response

Create Company Trip Booking

Endpoint

Request Body (Form Data)

Response

Accept Booking

Endpoint

Request Body

Response

Reject Booking

Endpoint

Request Body

Response

Cancel Booking

Endpoint

Request Body

Response

Get Driver Bookings

Endpoint

Query Parameters

Response