Booking Flow

This guide walks through the complete end-to-end flow for creating a reservation using the Roomability Guest API. Follow the steps in order — each step depends on data returned from the previous one.

Flow Overview

1. Load Reference Data   →  Countries, States, Room Types, Payment Methods
2. Check Availability    →  Confirm rooms are available for chosen dates
3. Initialize Payment    →  (Paystack only) Get payment URL
4. Guest Pays            →  Redirect to Paystack checkout
5. Verify Payment        →  (Paystack only) Confirm transaction succeeded
6. Create Reservation    →  Submit booking with all collected data
7. Confirm Booking       →  Retrieve and display booking details

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": 4, "name": "Paystack" }
    ]
}

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

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": 4,
            "roomType": "Economy",
            "rate": 35000,
            "available": 2,
            "currencySymbol": "₦"
        }
    ]
}

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

⚠️ Only display rooms where available > 0.

Step 3 — Initialize Payment (Paystack only)

Skip this step if the guest chooses Book On Hold (payMethodId: 1).

If the guest selects Paystack, initialize a transaction to get the payment URL.

💡 Amount must be in kobo (NGN × 100). For example, ₦35,000 = 3500000 kobo.

Request:

Response:

{
    "status": true,
    "data": {
        "authorization_Url": "https://checkout.paystack.com/kfx4ota680ptmpd",
        "access_Code": "kfx4ota680ptmpd",
        "reference": "sti58qbn3w"
    },
    "errorCode": 0
}

💾 Store the reference — you'll need it in Steps 5 and 6.

Step 4 — Guest Completes Payment (Paystack only)

Redirect the guest to data.authorization_Url. Paystack handles the payment UI. After the guest completes or abandons payment, Paystack redirects them back to your configured callback URL.

Step 5 — Verify Payment (Paystack only)

On the callback, verify the transaction before creating the reservation. Do not proceed to Step 6 if verification fails.

Request:

Response — Success:

{
    "data": {
        "status": "success",
        "reference": "sti58qbn3w",
        "amount": 3500000
    },
    "errorCode": 0,
    "errorMessage": "Transaction verified successfully."
}

Response — Abandoned/Failed:

{
    "data": {
        "status": "abandoned"
    },
    "errorCode": -314,
    "errorMessage": "Transaction abandoned!"
}

`data.status`	`errorCode`	Action
`"success"`	`0`	✅ Proceed to Step 6
`"abandoned"`	`-314`	❌ Prompt guest to retry payment
`"failed"`	non-zero	❌ Prompt guest to retry or use different method

Step 6 — Create the Reservation

Submit the full reservation payload. Combine all data collected in the previous steps.

Request:

Response — Success:

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

Response — Validation Error:

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

💾 Store the bookingRef — guests will need this to retrieve or cancel their reservation.

Step 7 — Confirm the Booking

Retrieve and display the full booking summary to the guest.

Request:

Response:

{
    "guest": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com"
    },
    "reservations": [
        {
            "roomType": "Economy",
            "bookingRef": "F8AUA6",
            "checkInDate": "2025-09-15",
            "checkOutDate": "2025-09-16",
            "quantity": 1,
            "rate": 35000
        }
    ],
    "errorCode": 0,
    "errorMessage": "Reservation details retrieved successfully."
}

Display the booking reference prominently. Guests will need it to look up or cancel their reservation.

Field Sources — Quick Reference

Use this table to trace where each field in POST /Reservation/Add comes from:

Field	Source
`guest.countryId`	`GET /Country/GetSelectList` → `id`
`guest.stateId`	`GET /State/GetSelectList` → `id`
`reservations[].roomTypeId`	`POST /Reservation/Availability` → `types[].roomTypeId`
`reservations[].rate`	`POST /Reservation/Availability` → `types[].rate`
`reservations[].checkInDate`	Guest input (format: `YYYY-MM-DD`)
`reservations[].arrivalTime`	Guest input (format: `HH:MM AM/PM`)
`payment.payMethodId`	`GET /Paymode/ActiveList` → `items[].id`
`payment.reference`	`POST /Paystack/Initialize` → `data.reference` (Paystack only)
`payment.amount`	Calculated: `rate × nights × quantity` per room

Payment Method Decision Tree

Guest selects payment method
        │
        ├── Book On Hold (payMethodId: 1)
        │       │
        │       └── Skip Steps 3, 4, 5
        │           Go directly to Step 6
        │           Leave reference & transaction empty
        │
        └── Paystack (payMethodId: 4)
                │
                ├── Step 3: Initialize → get reference + authorization_Url
                ├── Step 4: Redirect guest to Paystack checkout
                ├── Step 5: Verify on callback
                │       ├── status = "success" → proceed
                │       └── status = "abandoned" / "failed" → stop, retry
                └── Step 6: Create reservation with reference

Common Mistakes to Avoid

Mistake	Correct Approach
Using `rate` from `RoomType/DetailList` instead of `Availability`	Always use the rate from `POST /Reservation/Availability` — it reflects real-time pricing
Sending `adultNo` / `childNo` as strings (`"2"`)	Send as integers (`2`)
Setting `arrivalTime` with a range (`"02:00 PM → 03:00 PM"`)	Use a single time value: `"02:00 PM"`
Creating the reservation before verifying Paystack payment	Always call `GET /Paystack/Verify` first and check `errorCode === 0`
Not storing `bookingRef` after successful reservation	Always persist `bookingRef` — it's the only way to retrieve or cancel the booking
Sending `amount` in kobo in the reservation payload	`payment.amount` in `Reservation/Add` is in naira (e.g. `35000.00`), not kobo

Flow 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 — Initialize Payment (Paystack only)#

Step 4 — Guest Completes Payment (Paystack only)#

Step 5 — Verify Payment (Paystack only)#

Step 6 — Create the Reservation#

Step 7 — Confirm the Booking#

Field Sources — Quick Reference#

Payment Method Decision Tree#

Common Mistakes to Avoid#

Flow 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 — Initialize Payment (Paystack only)

Step 4 — Guest Completes Payment (Paystack only)

Step 5 — Verify Payment (Paystack only)

Step 6 — Create the Reservation

Step 7 — Confirm the Booking

Field Sources — Quick Reference

Payment Method Decision Tree

Common Mistakes to Avoid