Skip to main content

​
Overview

Masar Eagle integrates with Moyasar payment gateway to process online payments for trip bookings. The verification flow ensures payment authenticity before confirming bookings.
Moyasar is a Saudi Arabian payment gateway supporting credit cards, Apple Pay, and STC Pay.

​
Verify Company Trip Payment

Verify Moyasar payment for a company trip booking and update booking status. 
POST /api/company-bookings/{bookingId}/verify-payment

​
Path Parameters

​
bookingId
string
required
The booking ID to verify payment for

​
Request Body

​
moyasarPaymentId
string
required
The payment ID returned by Moyasar after payment completion

​
Response Fields

​
success
boolean
required
Indicates if payment verification succeeded
​
message
string
required
Status message in Arabic
​
bookingStatus
string
Current booking status after verification (Pending, Cancelled, etc.)
​
paymentStatus
string
Payment status (Completed, Failed, etc.)
​
amountPaid
decimal
Amount paid if payment succeeded
​
currency
string
Currency of the payment

​
Payment Verification Flow

  1. Payment Order Lookup: System retrieves payment order from database
  2. Moyasar Verification: Queries Moyasar API to verify payment status
  3. Status Check: Validates payment wasn’t already processed
  4. Booking Update: Updates booking and trip seat availability
  5. Notification: Sends confirmation to company

​
Example Request

curl -X POST "https://api.masareagle.sa/api/company-bookings/booking_abc123/verify-payment" \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "moyasarPaymentId": "pay_1a2b3c4d5e6f"
  }'

​
Success Response

{
  "success": true,
  "message": "تم التحقق من الدفع بنجاح. الحجز بانتظار موافقة الشركة",
  "bookingStatus": "Pending",
  "paymentStatus": "Completed",
  "amountPaid": 450.00,
  "currency": "SAR"
}

​
Failed Payment Response

{
  "success": false,
  "message": "فشل الدفع. يرجى المحاولة مرة أخرى",
  "bookingStatus": "Cancelled",
  "paymentStatus": "Failed"
}

​
Expired Payment Response

{
  "success": false,
  "message": "انتهت صلاحية عملية الدفع. يرجى إنشاء حجز جديد",
  "bookingStatus": "Cancelled",
  "paymentStatus": "Failed"
}

​
Already Verified Response

{
  "success": false,
  "message": "تم التحقق من هذا الدفع مسبقاً",
  "paymentStatus": "Completed"
}
Post-Verification Actions:
  • Successful payments increment trip booking count
  • Booking status changes to “Pending” awaiting company approval
  • Company receives notification of new booking
  • Wallet operations are deferred until company approval

​
Verify Public Trip Payment

Verify Moyasar payment for a public trip booking with seat reservation. 
POST /api/company-public-trips/bookings/{bookingId}/verify-payment

​
Path Parameters

​
bookingId
string
required
The public trip booking ID

​
Request Body

​
moyasarPaymentId
string
required
The payment ID returned by Moyasar

​
Response Fields

​
success
boolean
required
Indicates if payment verification succeeded
​
message
string
required
Status message in Arabic
​
bookingStatus
string
Booking status after verification
​
paymentStatus
string
Payment status
​
amountPaid
decimal
Amount paid
​
currency
string
Payment currency

​
Public Trip Verification Flow

  1. Payment Verification: Validates payment with Moyasar
  2. Seat Availability Check: Ensures requested seats are still available
  3. Seat Reservation: Reserves seats on the trip
  4. Booking Confirmation: Updates booking to Pending status
  5. Notification: Alerts company of new booking

​
Example Request

curl -X POST "https://api.masareagle.sa/api/company-public-trips/bookings/pub_booking_xyz/verify-payment" \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "moyasarPaymentId": "pay_9z8y7x6w5v4u"
  }'

​
Success Response

{
  "success": true,
  "message": "تم التحقق من الدفع بنجاح. الحجز بانتظار موافقة الشركة",
  "bookingStatus": "Pending",
  "paymentStatus": "Completed",
  "amountPaid": 300.00,
  "currency": "SAR"
}

​
Seats No Longer Available

{
  "success": false,
  "message": "عذراً، المقاعد لم تعد متاحة. سيتم استرداد المبلغ",
  "bookingStatus": "Cancelled",
  "paymentStatus": "Refunded"
}
Important: For public trips, seats are reserved AFTER successful payment verification. If seats become unavailable between payment and verification, the booking is cancelled and marked for refund.

​
Payment Verification States

​
Payment Order Not Found

{
  "success": false,
  "message": "طلب الدفع غير موجود"
}
Occurs when the payment order doesn’t exist in the system.

​
Booking Not Found

{
  "success": false,
  "message": "الحجز غير موجود"
}
The referenced booking ID doesn’t exist.

​
Booking Already Rejected/Cancelled

{
  "success": false,
  "message": "لا يمكن التحقق من الدفع لحجز مرفوض"
}
Cannot verify payment for bookings that were already rejected or cancelled.

​
Integration Notes

​
Frontend Integration

  1. Create Booking: Get booking ID from booking creation endpoint
  2. Initiate Moyasar Payment: Use booking ID as order reference
  3. Payment Callback: Receive Moyasar payment ID
  4. Verify Payment: Call verification endpoint with payment ID
  5. Handle Response: Show success/failure message to user

​
Transaction Safety

  • All payment verifications use database transactions
  • Failed verifications trigger automatic rollback
  • Duplicate verification attempts are detected and prevented
  • Payment status transitions are atomic

​
Notification Flow

EventRecipientNotification Type
Payment SuccessPassengerPayment confirmation
Payment SuccessCompanyNew booking alert
Payment FailedPassengerPayment failed notice
Seats UnavailablePassengerRefund notification
Always handle the verification response client-side to provide immediate feedback. Don’t rely solely on webhook notifications.

Build docs developers (and LLMs) love

Get started for freeTalk to us