Book Hotel Room Tickets

Purchase hotel accommodation. Allows your customers to book rooms at available hotels, apartments, or resorts.

Important: MERPI only creates transactions for successful bookings. If the booking fails for any reason (unavailable room, payment issue, etc.), no transaction record is created.

POST /v2/merpi/hotels/buy

Request Body

{
    "room_id": 10,
    "number_of_guests": 1,
    "number_of_rooms": 1,
    "checkin_date": "2026-02-03",
    "checkout_date": "2026-02-04",
    "customer_info": {
        "name": "John Doe",
        "email": "[e-mail]",
        "phone_number": "[phone]",
        "dob": "1990-01-01"
    }
}

Request Fields

Field	Type	Required	Description
room_id	number	Yes	Room identifier from hotel rooms endpoint
number_of_guests	number	Yes	Total number of guests (must not exceed max_occupancy)
number_of_rooms	number	Yes	Number of rooms to book (of the same type)
checkin_date	string	Yes	Check-in date (YYYY-MM-DD format)
checkout_date	string	Yes	Check-out date (YYYY-MM-DD format)
customer_info	object	Yes	Guest information

Customer Info Object

Field	Type	Required	Description
name	string	No	Full name of primary guest
email	string	Yes	Guest email address
phone_number	string	No	Guest phone number (format: +234XXXXXXXXXX)
dob	string	No	Date of birth (YYYY-MM-DD format)

Header Parameters

Parameter	Type	Required	Description
X-API-KEY	string	Yes	Your API key to access this endpoint
TransactionMedium	string	Yes	Transaction medium: Web, Mobile, or POS
Content-Type	string	Yes	Must be application/json

Code Examples

JavaScript - Fetch

const bookingData = {
  room_id: 10,
  number_of_guests: 2,
  number_of_rooms: 1,
  checkin_date: "2026-03-15",
  checkout_date: "2026-03-17",
  customer_info: {
    name: "Chidinma Okafor",
    email: "[e-mail]",
    phone_number: "[phone]",
    dob: "1988-05-20"
  }
};

const response = await fetch('{{url}}/v2/merpi/hotels/book', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'TransactionMedium': 'Web',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(bookingData)
});

const result = await response.json();
console.log(result);

JavaScript - Axios

const axios = require('axios');

const bookingData = {
  room_id: 10,
  number_of_guests: 1,
  number_of_rooms: 1,
  checkin_date: "2026-02-03",
  checkout_date: "2026-02-04",
  customer_info: {
    name: "John Doe",
    email: "[e-mail]",
    phone_number: "[phone]",
    dob: "1990-01-01"
  }
};

const response = await axios.post('{{url}}/v2/merpi/hotels/book', bookingData, {
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'TransactionMedium': 'Web',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

cURL

curl -X POST "{{url}}/v2/merpi/hotels/book" \
  -H "X-API-KEY: your_api_key_here" \
  -H "TransactionMedium: Web" \
  -H "Content-Type: application/json" \
  -d '{
    "room_id": 10,
    "number_of_guests": 1,
    "number_of_rooms": 1,
    "checkin_date": "2026-02-03",
    "checkout_date": "2026-02-04",
    "customer_info": {
      "name": "John Doe",
      "email": "[e-mail]",
      "phone_number": "[phone]",
      "dob": "1990-01-01"
    }
  }'

Response

Success Response (201)

{
    "success": true,
    "status": 201,
    "message": "Hotel Booking Purchased Successfully",
    "data": {
        "reference": "TR182685730",
        "invoice_id": 20210003,
        "booking_number": "HYAVOSPRRC",
        "name": "John Doe",
        "email": "[e-mail]",
        "phone_number": "[phone]",
        "hotel": {
            "id": 16,
            "name": "Grand Paradise Hotel",
            "location": "Downtown City"
        },
        "room": {
            "id": 10,
            "room_name": "Basic",
            "number_of_rooms": "22"
        },
        "checkin_date": "2026-02-03",
        "checkout_date": "2026-02-04",
        "number_of_nights": 1,
        "number_of_guests": 1,
        "number_of_rooms": 1,
        "amount": 25650
    }
}

Error Response (400/422)

{
    "success": false,
    "status": 422,
    "message": "Room is no longer available for selected dates",
    "errors": {
        "room_id": ["The selected room is not available for the specified dates"]
    }
}

Response Fields

Success Response (201)

Field	Type	Description
success	boolean	Indicates if the booking was successful
status	number	HTTP status code (201 for successful creation)
message	string	Success message
data	object	Booking details

Error Response (400/422)

Field	Type	Description
success	boolean	Always false for errors
status	number	HTTP error code (400 for bad request, 422 for validation errors)
message	string	Error message describing what went wrong
errors	object	Detailed validation errors (when applicable)

Data Object (Success Only)

Field	Type	Description
reference	string	Unique transaction reference number
invoice_id	number	Invoice identifier for this booking
booking_number	string	Unique booking confirmation number (use for check-in)
name	string	Guest name
email	string	Guest email
phone_number	string	Guest phone number
hotel	object	Hotel information
room	object	Room details
checkin_date	string	Check-in date (YYYY-MM-DD)
checkout_date	string	Check-out date (YYYY-MM-DD)
number_of_nights	number	Total number of nights
number_of_guests	number	Total number of guests
number_of_rooms	number	Number of rooms booked
amount	number	Total booking amount in Naira

Hotel Object

Field	Type	Description
id	number	Hotel identifier
name	string	Hotel name
location	string	Hotel location/address

Room Object

Field	Type	Description
id	number	Room type identifier
room_name	string	Room category name (e.g., Basic, Deluxe)
room_number	string	Number of rooms available in this category

Example:

• Room price: ₦25,650/night

• Number of nights: 1 (Feb 3 - Feb 4)

• Number of rooms: 1

• Total: ₦25,650

For multi-night stays:

• Room price: ₦25,650/night

• Number of nights: 3 (Feb 3 - Feb 6)

• Number of rooms: 2

• Total: ₦153,900

Important Notes

Transaction Creation: Transactions are ONLY created for successful bookings. Failed bookings do not create transaction records in the system.

Date Format: Always use YYYY-MM-DD format for dates (e.g., "2026-02-03").

Number of Nights Calculation: The system automatically calculates nights based on check-in and check-out dates. Check-out date is exclusive.

Booking Number: The booking_number field is what guests should present at hotel check-in. Make sure to display this prominently in confirmation emails/screens.

Reference Number: The reference field is the unique transaction identifier. Use this for tracking, customer support, and transaction queries.

Availability Check: Always verify room availability immediately before calling this endpoint by checking is_available in the rooms response.

Occupancy Validation: Ensure number_of_guests does not exceed the room's max_occupancy.

Phone Number Format: Use international format with country code: +234XXXXXXXXXX

Common Errors

Error Code	Error Message	Cause	Solution
422	Room is no longer available	Room already booked or unavailable	Check availability before booking
422	Invalid dates	Check-out before check-in or past dates	Ensure checkout_date > checkin_date and dates are in future
422	Exceeds occupancy	Too many guests for room type	Select larger room or book multiple rooms
400	Invalid phone format	Wrong phone number format	Use +234XXXXXXXXXX format
400	Invalid email	Malformed email address	Verify email format is correct
401	Unauthorized	Invalid or missing API key	Check X-API-KEY header

Complete Booking Flow Example

// 1. Get hotels in Lagos
const hotelsResponse = await fetch('{{url}}/v2/merpi/hotels?city=Lagos');
const hotelsData = await hotelsResponse.json();
const selectedHotel = hotelsData.data.hotels[0]; // User selects first hotel

console.log(`Selected: ${selectedHotel.name}`);

// 2. Get rooms for selected hotel
const roomsResponse = await fetch(`{{url}}/v2/merpi/hotels/${selectedHotel.id}/rooms`, {
  headers: {
    'X-API-KEY': 'sk_test_...',
    'TransactionMedium': 'Web'
  }
});
const roomsData = await roomsResponse.json();

// 3. User selects "Basic" room
const selectedRoom = roomsData.data.rooms.find(r => r.room_name === 'Basic');

console.log(`Room: ${selectedRoom.room_name}, Price: ₦${selectedRoom.price}/night`);

// 4. Verify room is available
if (!selectedRoom.is_available) {
  alert('Sorry, this room is no longer available');
  return;
}

// 5. Check occupancy
const guestCount = 2;
if (guestCount > selectedRoom.max_occupancy) {
  alert(`This room can only accommodate ${selectedRoom.max_occupancy} guests`);
  return;
}

// 6. Calculate and display total price
const checkinDate = '2026-03-15';
const checkoutDate = '2026-03-17';
const numberOfNights = 2; // Calculate based on date difference
const numberOfRooms = 1;
const totalPrice = selectedRoom.price * numberOfNights * numberOfRooms;

console.log(`Total: ₦${totalPrice.toLocaleString()} for ${numberOfNights} nights`);

// 7. Complete booking
const bookingResponse = await fetch('{{url}}/v2/merpi/hotels/book', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'sk_test_...',
    'TransactionMedium': 'Web',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    room_id: selectedRoom.id,
    number_of_guests: guestCount,
    number_of_rooms: numberOfRooms,
    checkin_date: checkinDate,
    checkout_date: checkoutDate,
    customer_info: {
      name: 'Ada Nwosu',
      email: '[e-mail]',
      phone_number: '[phone]',
      dob: '1992-06-15'
    }
  })
});

const bookingResult = await bookingResponse.json();

if (bookingResult.success) {
  console.log('✅ Booking confirmed!');
  console.log('Booking Number:', bookingResult.data.booking_number);
  console.log('Reference:', bookingResult.data.reference);
  console.log('Hotel:', bookingResult.data.hotel.name);
  console.log('Room:', bookingResult.data.room.room_name);
  console.log('Amount Paid: ₦' + bookingResult.data.amount.toLocaleString());
  
  // Display confirmation to user with booking_number
  showConfirmation(bookingResult.data);
} else {
  console.error('❌ Booking failed:', bookingResult.message);
  // Handle error - show user-friendly message
  alert(bookingResult.message);
}

Verifying Booking Status

After successful booking, you can verify the transaction using the reference number:

const reference = bookingResult.data.reference;
const verificationResponse = await fetch(`{{url}}/v2/merpi/transactions/${reference}`, {
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'TransactionMedium': 'Web'
  }
});

const transactionData = await verificationResponse.json();
console.log('Transaction Status:', transactionData);

See Transaction Query documentation for complete details on verifying transactions.