Buy Bus Ticket Endpoint (V2)

✅ CURRENT VERSION - This endpoint supports both Timed Schedules and Random Schedules.

This V2 endpoint handles transport ticket purchases for both Timed and Random schedules. When your customers call this endpoint through your platform, transport tickets for their selected route are created and sent to their email. You can track all purchases from your MERPI dashboard.

Key Features

• Unified Endpoint: Handles both Timed and Random schedule types

• Dynamic Request Structure: Request body adapts based on schedule_type

• Flexible Seat Handling:

  • Timed schedules: Customers select specific seats

  • Random schedules: No seat selection required (seats assigned automatically)

• Email Delivery: Tickets are automatically sent to the customer's email

• Next of Kin Information: Required for safety and emergency contact purposes

Understanding Schedule Types

Timed Schedules

• Fixed departure times (e.g., 6:00 AM)

• Requires seat selection - customers choose specific seats from available options

• Fixed pricing per seat

• Best for long-distance routes with predictable timing

Random Schedules

• Flexible departure within operating windows (e.g., 6:00 AM - 11:00 PM)

• No seat selection needed - seats assigned automatically upon boarding

• Number of passengers specified instead of seat IDs

• Best for short-distance routes with frequent departures

API Reference

Endpoint

POST /api/v2/merpi/transport/buy/tickets

Buy Bus Tickets (V2 - Supports both Timed and Random schedules)

post

Endpoint to purchase bus tickets for a specific schedule. This V2 endpoint supports both Timed Schedules (fixed departure times with seat selection) and Random Schedules (flexible timing with automatic seat assignment). The request structure varies based on the schedule_type field.

Body

application/json

or

Responses

201

Successful purchase of bus tickets.

application/json

400

Bad Request - Invalid input or validation errors

application/json

404

Not Found - Schedule, route, or bus not found

application/json

409

Conflict - Seats already booked (Timed schedules only)

application/json

500

Internal Server Error

application/json

post

/api/v2/merpi/transport/buy/tickets

HTTPcURLJavaScriptPython

POST /api/v2/merpi/transport/buy/tickets HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 380

{
  "schedule_type": "timed",
  "schedule_id": 5,
  "seats": [
    9,
    4,
    3
  ],
  "departure_date": "2024-07-23 20:21",
  "customer_info": {
    "name": "Victor Ebuka",
    "email": "[e-mail]",
    "phone_number": "08085825362",
    "dob": "01/12/2000",
    "username": "victor_ebuka",
    "kin": {
      "first_name": "Richard",
      "last_name": "Raymond",
      "phone_number": "08085825362",
      "email": "[e-mail]",
      "gender": "male",
      "relationship": "son"
    }
  }
}

Timed Schedule PurchaseRandom Schedule Purchase

{
  "success": true,
  "status": 201,
  "message": "Bus Tickets Purchased Successfully",
  "data": {
    "reference": "TR197016656",
    "invoice_id": 15939735,
    "name": "Victor Ebuka",
    "email": "[e-mail]",
    "phone_number": "08085825362",
    "departure_date": "2025-04-09 20:21",
    "seat": [
      {
        "id": 114,
        "name": "1-1",
        "row": 1,
        "column": 1
      },
      {
        "id": 116,
        "name": "1-3",
        "row": 1,
        "column": 3
      },
      {
        "id": 117,
        "name": "1-4",
        "row": 1,
        "column": 4
      }
    ],
    "bus": {
      "id": 9,
      "name": "Haice 2",
      "image": "storage/transport/buses/WKOnEqQT4vLWkZVhbdQdghwWm3CZKmObMbCMahfs.jpg",
      "seats": 16,
      "price": "0",
      "rows": 4,
      "columns": 4,
      "seat_grid": [
        [
          {
            "id": 114,
            "seat": true,
            "row": 1,
            "column": 1
          },
          {
            "id": 115,
            "seat": false,
            "row": 1,
            "column": 2
          },
          {
            "id": 116,
            "seat": true,
            "row": 1,
            "column": 3
          },
          {
            "id": 117,
            "seat": true,
            "row": 1,
            "column": 4
          }
        ]
      ]
    },
    "schedule": {
      "id": 9,
      "name": "Haice 2",
      "image": "storage/transport/buses/WKOnEqQT4vLWkZVhbdQdghwWm3CZKmObMbCMahfs.jpg",
      "seats": 16,
      "price": "0"
    },
    "schedule_type": "timed"
  }
}

Request Body - Timed Schedule

Parameter	Type	Required	Description
schedule_type	String	Yes	Must be "timed" for timed schedules
schedule_id	Integer	Yes	Unique identifier for the bus schedule being booked (from Get Schedules endpoint)
seats	Array[Integer]	Yes	List of seat IDs being booked (e.g., [9, 4, 3] indicates seats with ID 9, 4, and 3)
departure_date	String	Yes	Date and time of departure in format: YYYY-MM-DD HH:MM (e.g., "2024-07-23 20:21")
customer_info	Object	Yes	Customer information object
customer_info.name	String	No	Full name of the customer
customer_info.email	String	Yes	Email address (tickets will be sent here)
customer_info.phone_number	String	Yes	Customer's phone number
customer_info.dob	String	No	Date of birth in format: DD/MM/YYYY
customer_info.username	String	No	Username for the customer
customer_info.kin	Object	No	Next of kin information
customer_info.kin.first_name	String	No	First name of next of kin
customer_info.kin.last_name	String	No	Last name of next of kin
customer_info.kin.phone_number	String	No	Phone number of next of kin
customer_info.kin.email	String	No	Email of next of kin
customer_info.kin.gender	String	No	Gender of next of kin (e.g., "male", "female")
customer_info.kin.relationship	String	No	Relationship to customer (e.g., "son", "daughter", "spouse")

Request Body - Random Schedule

Parameter	Type	Required	Description
schedule_type	String	Yes	Must be "random" for random schedules
route_id	Integer	Yes	ID of the route being booked
bus_id	Integer	Yes	ID of the bus for this trip (from buses array in Get Schedules response)
no_of_passengers	Integer	Yes	Number of passengers traveling
departure_time	String	Yes	Preferred departure time in format: HH:MM (24-hour format)
departure_date	String	Yes	Date and time of departure in format: YYYY-MM-DD HH:MM (e.g., "2024-07-23 20:21")
customer_info	Object	Yes	Customer information object
customer_info.name	String	No	Full name of the customer
customer_info.email	String	Yes	Email address (tickets will be sent here)
customer_info.phone_number	String	Yes	Customer's phone number
customer_info.dob	String	No	Date of birth in format: DD/MM/YYYY
customer_info.username	String	No	Username for the customer
customer_info.kin	Object	No	Next of kin information
customer_info.kin.first_name	String	No	First name of next of kin
customer_info.kin.last_name	String	No	Last name of next of kin
customer_info.kin.phone_number	String	No	Phone number of next of kin
customer_info.kin.email	String	No	Email of next of kin
customer_info.kin.gender	String	No	Gender of next of kin (e.g., "male", "female")
customer_info.kin.relationship	String	No	Relationship to customer (e.g., "son", "daughter", "spouse")

Response Fields Comparison

Common Fields (Both Schedule Types)

Field	Type	Description
success	Boolean	Indicates if the request was successful
status	Integer	HTTP status code (201 for successful creation)
message	String	Human-readable message about the result
data.reference	String	Unique transaction reference (e.g., "TR197016656")
data.invoice_id	Integer	Invoice ID for the purchase(Customer can present this at the transport terminal)
data.name	String	Customer's name
data.email	String	Customer's email (where ticket was sent)
data.phone_number	String	Customer's phone number
data.departure_date	String	Confirmed departure date and time
data.bus	Object	Complete bus information
data.schedule	Object	Schedule information for the booked trip
data.schedule_type	String	Type of schedule: "timed" or "random"

Timed Schedule Specific Fields

Field	Type	Description
data.seat	Array[Object]	Array of booked seat objects with full details
data.seat[].id	Integer	Seat ID
data.seat[].name	String	Seat position (e.g., "1-1" for row 1, column 1)
data.seat[].row	Integer	Row number
data.seat[].column	Integer	Column number
data.bus.seat_grid	Array	2D array showing all seats and availability

Random Schedule Specific Fields

Field	Type	Description
data.seat	Array	Empty array - seats assigned automatically upon boarding
data.no_of_passengers	Integer	Number of passengers booked
data.route_id	Integer	Route ID for the trip
data.bus_id	Integer	Bus ID for the trip
data.schedule.start_time	String	Operating window start time
data.schedule.end_time	String	Operating window end time
data.schedule.price	Integer/Number	Price for the schedule

Key Differences Summary

Key Aspect	Timed Schedule	Random Schedule
Request Field	schedule_id + seats	route_id + bus_id + no_of_passengers
Seat Selection	Required - customer chooses seats. If not, available random seats are assigned.	Not required - auto-assigned upon boarding
Departure Time	Fixed time from schedule	Customer's preferred time within window
Response Seats	Array of seat objects with details	Empty array []
Use Case	Long-distance, fixed schedule	Short-distance, flexible timing

Implementation Guide

Determine Schedule Type

After calling the Get Schedules endpoint, check the schedule_type field:

const schedule = schedulesResponse.data.schedules[0];

if (schedule.schedule_type === 'timed') {
  // Show seat selection UI - if you want to. 
  // Require: schedule_id, seats, departure_date
} else if (schedule.schedule_type === 'random') {
  // Show passenger count selector
  // Show time selector within operating hours
  // Require: route_id, bus_id, no_of_passengers, departure_date, departure_time
}

Build Request Based on Schedule Type

For Timed Schedules:

const timedRequest = {
  schedule_type: 'timed',
  schedule_id: schedule.id,
  seats: selectedSeatIds, // From user selection
  departure_date: `${date} ${schedule.time.departure}`,
  customer_info: customerData
};

For Random Schedules:

const randomRequest = {
  schedule_type: 'random',
  route_id: schedule.route.id,
  bus_id: selectedBus.bus_id, // From buses array
  no_of_passengers: passengerCount,
  departure_date: selectedDate,
  departure_time: selectedTime, // Within operating_hours
  customer_info: customerData
};