Payment Flow — Book on Hold#

payMethodId: 1

Page Flow Overview#

#

🏠 Home Page (Loading Reference Data)#

API Calls#

Load All Room Types#

Load Hotel Details#

Load Hotel Rules#

📅 Booking Page (Checking Room Availability)#

API Call#

Check Availability#

{
    "errorCode": 0,
    "errorMessage": "Successfully retrieved available rooms.",
    "types": [
        {
            "roomTypeId": 2,
            "roomType": "Business Suite",
            "rate": 50000,
            "available": 1,
            "currencySymbol": "₦"
        }
    ]
}

💾 Store roomTypeId and rate for the room the guest selects — both are required on the Checkout Page.

⚠️ Only display rooms where available > 0.

👤 Guest Detail Page (Entry for Guest Details)#

API Call#

Look Up Existing Guest#

{
    "detail": {
        "title": "Dr",
        "firstName": "Emeka",
        "lastName": "Okafor",
        "phone": "08050000002",
        "email": "emeka.okafor@example.com",
        "sex": "Male",
        "occupation": "Consultant",
        "country": "Nigeria",
        "state": "Rivers",
        "address1": "12, Palm Close",
        "address2": "GRA Phase 2",
        "city": "Port Harcourt"
    },
    "errorCode": 0,
    "errorMessage": "Guest detail retrieved successfully."
}

{
    "detail": null,
    "errorCode": -200,
    "errorMessage": "Guest not found."
}

💡 If errorCode is -200, the guest is new — display a blank form for them to fill in their details manually.

💾 Store all guest details — they are required in the reservation payload on the Checkout Page.

Supporting Reference Data#

📋 Booking Preview (Review and Confirm Details Filled)#

Data Displayed#

✅ This is the guest's last chance to review and edit before checkout. Provide a Back button to return to the Guest Detail Page if needed.

💳 Checkout Page (Choose Method of Payment)#

API Call#

Load Active Payment Methods#

{
    "items": [
        { "id": 1, "name": "Book On Hold" },
        { "id": 2, "name": "Pay at the Hotel" },
        { "id": 4, "name": "Paystack" }
    ],
    "errorCode": 0,
    "errorMessage": "Successfully retrieved payment methods."
}

💾 Store the selected id as payMethodId — required in the reservation payload.

Add Reservation#

{
    "bookingRef": "T7XNQ2",
    "errorCode": 0,
    "errorMessage": "Reservations made successfully"
}

{
    "bookingRef": "",
    "errorCode": -100,
    "errorMessage": "Validation failed. Guest first name is required."
}

💾 Store the bookingRef — used on the next page to retrieve and display the booking confirmation.

✅ Payment Success Page (Reservation Confirmed)#

API Call#

Get Booking Detail#

{
    "guest": {
        "firstName": "Emeka",
        "lastName": "Okafor",
        "email": "emeka.okafor@example.com"
    },
    "reservations": [
        {
            "roomType": "Business Suite",
            "bookingRef": "T7XNQ2",
            "checkInDate": "2025-09-15",
            "checkOutDate": "2025-09-17",
            "arrivalTime": "01:00 PM",
            "quantity": 1,
            "rate": 50000
        }
    ],
    "errorCode": 0,
    "errorMessage": "Reservation details retrieved successfully."
}

📋 Display the bookingRef prominently. The guest will need it to look up or cancel their reservation.

🔒 Inform the guest that their room is held but not fully confirmed until payment is received or they check in, depending on the hotel's policy.

📩 Send a confirmation email to the guest with their bookingRef, hold status, check-in/out dates, and instructions on what to do next.

Payment Object Reference#

Field Sources — Quick Reference#

Important Notes#

💡 A Book on Hold reservation does not guarantee the room indefinitely. The hotel may release held bookings that are not confirmed within a set window. Check GET /Rule/Detail for the minCheckInWindow to understand the hold expiry policy.

⚠️ If the guest later decides to pay online, a Paystack transaction can be initiated separately and the reservation updated accordingly.