> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handle.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Flight Offers

> Search multi-carrier flight routes, live availability, and airfares across domestic and regional airlines.

Search domestic and regional flights directly through Handle's aggregated flight engine.

### Flight Search Flow

**1. 1. Search Routes**

Send `GET /api/v1/bill-payment/flights/search` specifying `origin` (e.g. `LOS`), `destination` (e.g. `ABV`), and `departureDate` (e.g. `2026-10-15`).

**2. 2. Lock Fare**

Call `POST /api/v1/bill-payment/flights/lock-rate` to guarantee fare pricing and hold seat reservations with the airline.

**3. 3. Issue Ticket**

Execute `POST /api/v1/bill-payment/purchase` with the locked offer ID to debit the user's account and issue the e-ticket.


## OpenAPI

````yaml openapi.json GET /bill-payment/flights/search
openapi: 3.0.3
info:
  title: Handle Merchant Payment Gateway API
  description: >-
    Developer API specification for accepting cardless, instant
    Account-to-Account (A2A) payments via Handle.
  version: 1.0.0
  contact:
    name: Handle Developer Support
    email: support@handle.ng
    url: https://handle.ng
servers:
  - url: https://api-local.handle.ng/api/v1
    description: Local Development (SSL)
  - url: https://api.handle.ng/api/v1
    description: Production Live Gateway
security:
  - BearerAuth: []
paths:
  /bill-payment/flights/search:
    get:
      tags:
        - Travel & Flights
      summary: Search Flight Offers
      description: Search multi-carrier flight routes and live pricing.
      parameters:
        - name: origin
          in: query
          required: true
          schema:
            type: string
            default: LOS
          example: LOS
        - name: destination
          in: query
          required: true
          schema:
            type: string
            default: ABV
          example: ABV
        - name: departureDate
          in: query
          required: true
          schema:
            type: string
            default: '2026-10-15'
          example: '2026-10-15'
      responses:
        '200':
          description: Available flight itineraries
          content:
            application/json:
              schema:
                type: object
                properties:
                  origin:
                    type: string
                    example: LOS
                  destination:
                    type: string
                    example: ABV
                  departureDate:
                    type: string
                    example: '2026-10-15'
                  offersCount:
                    type: integer
                    example: 2
                  offers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: flt_air_peace_los_abv_001
                        airline:
                          type: string
                          example: Air Peace
                        flightNumber:
                          type: string
                          example: P47120
                        departureTime:
                          type: string
                          example: '08:30'
                        arrivalTime:
                          type: string
                          example: '09:45'
                        duration:
                          type: string
                          example: 1h 15m
                        cabinClass:
                          type: string
                          example: ECONOMY
                        price:
                          type: number
                          example: 85000
                        currency:
                          type: string
                          example: NGN
              example:
                origin: LOS
                destination: ABV
                departureDate: '2026-10-15'
                offersCount: 2
                offers:
                  - id: flt_air_peace_los_abv_001
                    airline: Air Peace
                    flightNumber: P47120
                    departureTime: '08:30'
                    arrivalTime: '09:45'
                    duration: 1h 15m
                    cabinClass: ECONOMY
                    price: 85000
                    currency: NGN
                  - id: flt_ibom_air_los_abv_002
                    airline: Ibom Air
                    flightNumber: QI0202
                    departureTime: '11:15'
                    arrivalTime: '12:30'
                    duration: 1h 15m
                    cabinClass: ECONOMY
                    price: 92000
                    currency: NGN
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Supply your secret API key (e.g. `sk_live_...` or `sk_test_...`) in the
        Authorization header.
      x-default: sk_test_handle_master_key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.