Book On Hold

This flow applies when a guest selects Book on Hold as their payment method. The guest secures a reservation without making any payment upfront. The booking is held pending further action — either payment confirmation or check-in, depending on the hotel's policy.

payMethodId: 1

Flow Diagram

Overview

1. Load Reference Data   →  Countries, States, Room Types, Payment Methods
2. Check Availability    →  Confirm rooms are available for chosen dates
3. Create Reservation    →  Submit booking with no payment reference
4. Confirm Booking       →  Retrieve and display booking details

✅ No payment initialization or verification steps required. The reservation is created directly and held in a pending state.

Step 1 — Load Reference Data

Fetch the data needed to populate your booking form dropdowns. These can be loaded in parallel.

1a. Get Countries

Returns a list of countries. Use id as countryId in the reservation payload.

1b. Get States (after country is selected)

Returns states for the selected country. Use id as stateId in the reservation payload.

1c. Get Room Types

Returns all configured room types with names, rates, and images — useful for building a room catalogue page.

1d. Get Active Payment Methods

Response:

{
    "items": [
        { "id": 1, "name": "Book On Hold" },
        { "id": 2, "name": "Pay at the Hotel" },
        { "id": 4, "name": "Paystack" }
    ]
}

💾 Store the payment method id values — you'll need payMethodId in Step 3.

1e. Get Hotel Rules (optional but recommended)

Returns check-in/out times, min/max stay length, and advance booking windows. Display these constraints in your UI to prevent invalid bookings.

Step 2 — Check Availability

Once the guest has selected dates and guest count, confirm rooms are available and retrieve current rates.

Request:

Response:

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

💾 Store roomTypeId and rate for each room the guest selects — both are required in Step 3.

⚠️ Only display rooms where available > 0.

Step 3 — Create the Reservation

Submit the reservation payload. Since this is a hold with no payment, leave the reference and transaction fields empty and set amount to 0.00.

Request:

Response — Success:

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

💾 Store the bookingRef — the guest will need it to retrieve, confirm, or cancel the reservation.

Step 4 — Confirm the Booking

Retrieve and display the full reservation summary to the guest.

Request:

Response:

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

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.

Payment Object Reference

Field	Value	Description
`payTypeId`	`1`	Hold / pending payment
`payMethodId`	`1`	Book on Hold
`reference`	`""`	Leave empty — no transaction initiated
`transaction`	`""`	Leave empty — no transaction initiated
`amount`	`0.00`	No payment collected at this stage

Difference Between Book on Hold and Pay at the Hotel

	Book on Hold	Pay at the Hotel
Payment timing	Undecided — to be arranged	Confirmed at check-in
Amount collected online	None	None
Room status	Held, pending confirmation	Held, confirmed on arrival
`payMethodId`	`1`	`2`
Typically used for	Corporate accounts, VIP guests, reservations pending approval	Walk-in style online bookings

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.

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

Flow Diagram#

Overview#

Step 1 — Load Reference Data#

1a. Get Countries#

1b. Get States (after country is selected)#

1c. Get Room Types#

1d. Get Active Payment Methods#

1e. Get Hotel Rules (optional but recommended)#

Step 2 — Check Availability#

Step 3 — Create the Reservation#

Step 4 — Confirm the Booking#

Payment Object Reference#

Difference Between Book on Hold and Pay at the Hotel#

Important Notes#

Flow Diagram

Overview

Step 1 — Load Reference Data

1a. Get Countries

1b. Get States (after country is selected)

1c. Get Room Types

1d. Get Active Payment Methods

1e. Get Hotel Rules (optional but recommended)

Step 2 — Check Availability

Step 3 — Create the Reservation

Step 4 — Confirm the Booking

Payment Object Reference

Difference Between Book on Hold and Pay at the Hotel

Important Notes