Buy Bus Ticket Endpoint (DEPRECATED - V1)

⚠️ DEPRECATION NOTICE: This endpoint is deprecated and supports only Timed Schedules. Please use the new V2 endpoint which supports both Timed Schedules and Random Schedules.

Overview

This endpoint handles transport ticket purchase for Timed Schedules only. When your customers call this endpoint through your platform, transport tickets for their selected route (Lagos→Abuja, etc.) are created and sent to their email. You can track all purchases from your MERPI dashboard.

Important Notes

• Timed Schedules Only: This endpoint only works with routes that have fixed departure times

• Random Schedules Not Supported: For Random Schedule routes (flexible timing), you must use the V2 endpoint

• Email Delivery: Providing the correct customer email is critical because tickets are delivered by mail. Wrong email = tickets go to the wrong person

• Seat Selection Required: You must provide specific seat IDs from the schedule response

Migrating to V2

The V2 endpoint supports both Timed and Random schedules with a unified interface. Key differences:

Feature	V1 (This Endpoint)	V2(New Endpoint)
Schedule Support	Timed only	Both Timed and Random
Required Fields	schedule_id, seats	Varies by schedule_type
Random Schedule Support	❌ Not supported	✅ Fully supported

📘 See V2 Documentation: Link to V2 endpoint documentation

API Reference

Endpoint

POST /api/v1/merpi/transport/buy/tickets

Request Body Parameters

Parameter	Type	Required	Description
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")

Response Fields

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.seat	Array	Array of booked seat objects with details
data.seat[].id	Integer	Seat ID
data.seat[].name	String	Seat name/position (e.g., "1-1" for row 1, column 1)
data.seat[].row	Integer	Row number
data.seat[].column	Integer	Column number
data.bus	Object	Complete bus information
data.bus.seat_grid	Array	2D array showing all seats and their availability
data.schedule	Object	Schedule information for the booked trip

Buy Bus Tickets

post

Endpoint to purchase bus tickets for a specific schedule and seats.

Body

application/json

schedule_idintegerRequired

Unique identifier for the bus schedule being booked.

seatsinteger[]Required

List of seat ID’s being booked (e.g., [9, 4, 3] indicates seats with ID 9, 4, and 3).

departure_datestring · date-timeRequired

Date and time of the bus departure in YYYY-MM-DD HH:MM format (e.g., "2024-07-23 20:21").

Responses

200

Successful purchase of bus tickets.

application/json

successbooleanOptionalExample: true

statusintegerOptionalExample: 201

messagestringOptionalExample: Bus Tickets Purchased Successfully

400

Bad Request - Invalid input

application/json

500

Internal Server Error

application/json

post

/api/v1/merpi/transport/buy/tickets

HTTPcURLJavaScriptPython

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

{
  "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"
    }
  }
}

{
  "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
      }
    ],
    "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"
    }
  }
}

Key Differences from V2

What V1 Does Not Support (Use V2 Instead):

1. Random Schedules: Cannot purchase tickets for routes with flexible timing.

2. No Seat Selection for Random Routes: V2 handles seat assignment automatically for Random schedules as random schedules don't need seat selection.

3. Different Request Structure: V2 has dynamic request structure based on schedule_type .

V1 vs V2 Request Comparison

V1 (Timed Only):

{
  "schedule_id": 5,
  "seats": [9, 4, 3],
  "departure_date": "2024-07-23 20:21",
  "customer_info": { ... }
}

V2 (Random Schedule):

{
  "schedule_type": "random",
  "bus_id": 9,
  "route_id": 28,
  "no_of_passengers": 1,
  "departure_date": "2025-12-09",
  "departure_time": "23:50",
  "customer_info": { ... }
}

V2 (Timed Schedule):

{
  "schedule_type": "timed",
  "schedule_id": 5,
  "seats": [9, 4, 3],
  "departure_date": "2024-07-23 20:21",
  "customer_info": { ... }
}

Important Implementation Notes

For Timed Schedules (This Endpoint)

1. Get Available Seats First: Call the Get Schedules endpoint to retrieve available seats

2. Show Seat Selection UI: Display the seat grid to customers and let them choose specific seats(If you don't pass seats, we'll automatically assign random seat(s) from the available ones in the bus)

3. Send Seat IDs: Include the selected seat IDs in the seats array

4. Fixed Departure Time: The departure time is predetermined by the schedule

Why You Need to Migrate to V2

• Unified Interface: Handle both Timed and Random schedules with one endpoint

• Better Support: Future updates and improvements will focus on V2

• Complete Coverage: Access all route types in the system and more routes generally.

• Flexibility: Adapt to different schedule types dynamically

Common Use Cases

Timed Schedule Example: Lagos to Abuja

• Customer selects a long-distance route with fixed 6 AM departure

• System shows available seats using seat grid

• Customer chooses seats 9, 4, and 3

• Ticket is purchased with exact seats and fixed departure time

• Customer receives ticket via email with seat assignments