# TRIPS API   Airline & Road Ticketing   Vending System

## Hash Key to Enhance API Security

{% stepper %}
{% step %}

### How to validate the "Hash" property

1. Combine MerchantKey, ConfirmationCode and NewPriceWhole in this exact format: {MerchantKey}*{ConfirmationCode}*{NewPriceWhole}
2. Hash the concatenated string using the SHA-512 algorithm.
3. Convert the resulting hash to a hexadecimal string.
4. Compare your calculated hex string with the "Hash" property in the API response. If they match, the response integrity is verified.

Note: Your MerchantKey is confidential and only known to you — you are solely responsible for validation.
{% endstep %}

{% step %}

### Quick example

Concatenation format example (replace values with real ones):

WXqeiqqK4tNurxy\_36083|3757BA45\_2860

You can test at: <https://sha512.online/> (do not change the URL or its query params).
{% endstep %}
{% endstepper %}

***

## International Flights

Base Flight Search API (all environments referenced in this doc use the same Search endpoint): <https://api.staging.trips.ng/api/Flight/SearchFlight>

Below are samples for One-Way, Round-Trip and Multi-City flows: search → confirm price → ticket issue.

### International Flight (One-Way)

Sample request headers: Authorization: Bearer 194E1578816955B8DB4602383D32947C1E5ED1730F83BDF479D9829921139CA73B6765F3BE79CE107A2E7E8707B4D0AD502B9BD693E00FC7E070369FEB49096A\
Content-Type: application/json\
MerchantCode: ACCESS

Sample Flight Search request payload:

```json
{
  "FlightRoutes": [
    {
      "DepartureDate": "2023-07-28",
      "OriginLocationCode": "LOS",
      "DestinationLocationCode": "LHR"
    }
  ],
  "FlightPassengers": [
    { "Code": "ADT", "Quantity": 1 },
    { "Code": "CHD", "Quantity": 0 },
    { "Code": "INF", "Quantity": 0 }
  ],
  "FlightClasses": [{ "Name": "Economy" }],
  "Currency": "NGN",
  "EnsureAgentUnicityForRoutes": false,
  "OrderbyFlightTime": "asc",
  "OrderbyPrice": "asc",
  "PageSize": 50,
  "From": 0
}
```

Sample (truncated) response excerpt (search returns itineraries, prices, properties such as SessionId, AgentId, GdsId, CombinationID and RecommendationID — use these in price confirmation):

```json
{
  "SessionId": "0cfb0155d1d1461ca4cc4753a17d4b68",
  "TotalCount": 50,
  "ResultList": [
    {
      "FlightDetails": [ /* ... */ ],
      "AgentId": 5,
      "GDSId": 2,
      "Currency": "NGN",
      "BaseFare": 585008.0,
      "TotalFare": 844519.0,
      "Properties": {
        "CombinationID": 0,
        "RecommendationID": 0,
        "TripsSessionId": "0cfb0155d1d1461ca4cc4753a17d4b68",
        "GdsSessionId": "a34ac44c18a94ddc874b863543c061dd"
      }
    }
  ]
}
```

#### Confirm Ticket Price (One-Way)

Price Confirmation API: <https://api.staging.trips.ng/api/Flight/ConfirmTicketPrice>

Sample request (use SessionId, AgentID, GdsID, CombinationID, RecommendationID to identify itinerary):

```json
{
  "CombinationID": 0,
  "RecommendationID": 6,
  "FlightRouteIndex": 0,
  "AgentID": 5,
  "GdsID": 2,
  "SessionID": "b05dfe9cdebc4f5eb2269d35ec5215e4",
  "BillingAddress": {
    "ContactName": "Azee AsimI",
    "ContactEmail": ["amakao@qa.team"],
    "ContactMobileNo": "08034030758",
    "AddressLine1": "Airport",
    "AddressLine2": "",
    "City": "Lagos",
    "CountryCode": "KE"
  },
  "AirTravellers": [
    {
      "Gender": "Male",
      "PassengerTypeCode": "ADT",
      "LastName": "Obiseh",
      "FirstName": "Emman",
      "BirthDate": "1990-01-01",
      "NamePrefix": "MR",
      "Email": ["mail@mymail.com"],
      "Address": {
        "ContactName": "sssss",
        "AddressLine1": "30, Ishola Daniel Street",
        "AddressLine2": "",
        "City": "Oshodi",
        "CountryCode": "NG"
      },
      "Documents": [
        {
          "DocType": "DOCS",
          "DocID": "1111111111",
          "EffectiveDate": "2010-02-02",
          "ExpiryDate": "2030-02-02",
          "InnerDocType": "PASSPORT",
          "IssueLocation": "NG",
          "BirthCountryCode": "NG",
          "IssueCountryCode": "NG",
          "BirthDate": "2000-07-22"
        },
        {
          "DocType": "DOCO",
          "DocID": "2222222222",
          "EffectiveDate": "2010-02-02",
          "ExpiryDate": "2030-02-02",
          "InnerDocType": "VISA",
          "IssueLocation": "NG",
          "BirthCountryCode": "NG",
          "IssueCountryCode": "NG",
          "BirthDate": "2000-07-22"
        }
      ]
    }
  ]
}
```

Sample success response (relevant fields):

```json
{
  "ConfirmationCode": "37269|5K5JRW",
  "TicketTimeLimit": "2023-09-08T06:09:46+01:00",
  "OldPrice": 2031364.0,
  "NewPrice": 2031364.0,
  "OldPriceWhole": 2031364,
  "NewPriceWhole": 2031364,
  "Errors": [],
  "Warnings": [],
  "PassengerDetails": { /* ... */ },
  "Hash": "64fd876238ceff4081d03ca68b30cb45845559abe761e3d086f7e2c8908c63d9f734c941d37a9e7eae02384e03bef2ec9f25f05c078d401ec685747c043cbb6b"
}
```

* Use NewPriceWhole when creating the string to hash (MerchantKey\_ConfirmationCode\_NewPriceWhole).
* If confirm returns null ConfirmationCode (failed), check Errors array.

#### Ticket Issue (One-Way)

Ticket Issue API: <https://api.staging.trips.ng/api/v2/ticketing/issue>

Request example (use SessionId from PassengerDetails in confirm response):

```json
{
  "SessionId": "8646790ccb9a4d0997a6b52693287256",
  "TripType": "International",
  "TripMode": "Flight"
}
```

Sample response:

```json
{
  "Pnr": "RE6MIK",
  "IsSuccessful": true,
  "Message": "Successful",
  "BookingStatus": "TicketPending"
}
```

***

### Check Booking & Re-query

MyBooking API (GET):\
<https://api.staging.trips.ng/api/Flight/MyBookings?pnr=ZZZKJE\\&from=0\\&pageSize=10>

Parameters: pnr, email, phone, from (default 0), pageSize (default 10).

Re-query / Check Booking Status API: <https://api.staging.trips.ng/api/Flight/GetBookingStatus>

Sample request:

```json
{
  "ConfirmationCode": "36516|12QFDT",
  "Surname": "Adama"
}
```

Sample success response when found:

```json
{
  "StatusCode": 3,
  "StatusDescription": "TicketPending",
  "ErrorList": []
}
```

If booking not found:

```json
{
  "StatusCode": 100,
  "StatusDescription": "Error",
  "ErrorList": ["No Valid booking found for the given record"]
}
```

Business reversal rules:

* Reverse payment only when response is 200 OK and status = 0 or 1 or 11.
* Reverse payment also when response is 400 Bad Request AND GetBookingStatus shows status = 0 or 1 or 11.

<details>

<summary>Status codes</summary>

* 0 — Booking
* 1 — Cancelled
* 2 — TicketIssued
* 3 — TicketPending
* 11 — CancellationFailed
* 100 — Error

</details>

***

### International Flight (Round-Trip)

Use the same Search endpoint as One-Way. Example request includes two flight routes (outbound and return) and similar request body structure. ConfirmTicketPrice and ticketing flows are identical to One-Way but may include multiple FlightRoutes.

Confirm Ticket Price endpoint (same): <https://api.staging.trips.ng/api/Flight/ConfirmTicketPrice>

Sample success response includes NewPriceWhole and Hash — validate with MerchantKey as described earlier.

Ticket Issue API: <https://api.staging.trips.ng/api/v2/ticketing/issue>

***

### International Flight (Multi-City)

Search endpoint supports multiple FlightRoutes (multi-city). The flow remains:

* Search → ConfirmTicketPrice (use CombinationID, RecommendationID, SessionId etc.) → Ticket Issue.

Confirm and Ticket Issue responses include Hash values — validate as above.

***

## Domestic Flights

Domestic search and flows use separate endpoints under /api/Flight/Domestic.

Domestic Search API: <https://api.staging.trips.ng/api/Flight/Domestic/SearchFlight>

Domestic Confirm Ticket Price: <https://api.staging.trips.ng/api/Flight/Domestic/ConfirmTicketPrice>

Notes:

* SelectedFlights array may contain more than one item (e.g., round-trip or different airlines).
* FlightRouteIndex indicates leg: going = 1, return = 2 (where applicable).
* Confirm responses frequently return an array of confirmations (one per selected flight); each item includes NewPriceWhole and Hash — validate each using your MerchantKey and corresponding ConfirmationCode.

Domestic Ticket Issue API: <https://api.staging.trips.ng/api/v2/ticketing/issue>

Example ticket issue request:

```json
{
  "SessionId": "f542ee09fc7b49fdbaf94fc67b11a113",
  "TripType": "Domestic",
  "TripMode": "Flight"
}
```

Response example:

```json
{
  "Pnr": "JVAEJR-BOBKZH",
  "IsSuccessful": true,
  "Message": "Successful",
  "BookingStatus": "TicketIssued"
}
```

***

## Flight Rules API

Endpoint: <https://api.staging.trips.ng/api/Flight/FlightRules>

Sample request:

```json
{
  "AgentId": 25,
  "GDSId": 41,
  "CombinationID": 0,
  "RecommendationID": 0,
  "PassengerTypeCode": "ADT",
  "SessionId": "90533405d1724503a85290009"
}
```

Response contains FlightRules, FlightRulePenalties and TermsAndConditions (some HTML content).

***

## Road Transport (Bus) — Vendor Integration

Vendors receive a MerchantKey and MerchantCode. Authentication uses a bearer token which is SHA512(MerchantKey:MerchantCode). The API requires the following headers:

* Authorization: Bearer {SHA512(MerchantKey:MerchantCode)}\
  (you can generate/test hashes at <https://passwordsgenerator.net/sha512-hash-generator/> — do not change the URL)
* MerchantKey: {merchantkey}
* MerchantCode: {merchantcode}
* Content-Type: application/json

BUS Search API: <https://api.staging.trips.ng/api/Bus/SearchBus>

Sample request:

```json
{
  "Parameter": {
    "TravelRoute": {
      "DepartureId": 72,
      "ArrivalId": 51,
      "DepartureDate": "2024-08-30"
    },
    "PassengerTypes": [{ "Code": "ADT", "Quantity": 1 }],
    "IsRoundTrip": false,
    "Currency": "NGN",
    "OrderbyDepartureTime": "ASC",
    "OrderByPrice": "ASC"
  },
  "PageSize": 5000,
  "From": 0
}
```

Sample response contains FirstLeg, SecondLeg (for round trips), SessionId (TripsSessionId), CombinationId, RecommendationId, AvailableBuses and seat inventories. Selected items return ReservationId, AvailableSeats, SeatNumbers and pricing.

### Bus Price Confirmation

BUS Price Confirmation API: <https://api.staging.trips.ng/api/Bus/ConfirmTicketPrice>

Sample request (one-way):

```json
{
  "SessionId": "25fe6b49e3794f4585a0ba4c6f40f2a5",
  "Travellers": [
    {
      "PassengerTypeCode": "ADT",
      "FirstName": "Francis",
      "LastName": "Ibeh",
      "NamePrefix": "Mr",
      "SeatNumbers": ["11"]
    }
  ],
  "NumberOfSeats": 1,
  "IsRoundTrip": false,
  "SelectedBuses": [
    {
      "RecommendationID": 0,
      "CombinationID": 1,
      "GdsId": 103,
      "AgentId": 169,
      "BusRouteIndex": 0
    }
  ],
  "BillingAddress": {
    "ContactName": "Francis Ibeh",
    "ContactEmail": ["samuelineh@mail.com"],
    "ContactPhoneNumber": "+2348098988789",
    "AddressLine1": "",
    "NextOfKinDetails": {
      "Name": "Daniel Ibeh",
      "Email": ["ibehsamuel@mail.com"],
      "PhoneNumber": "+2348097889877"
    }
  }
}
```

Sample Price Confirmation response (includes ConfirmationCode, NewPriceWhole and Hash):

```json
[
  {
    "ConfirmationCode": "37656|6C6E44D1AGEJ",
    "TicketTimeLimit": "2024-08-28T13:40:09+01:00",
    "OldPrice": 21678.0,
    "NewPrice": 21678.0,
    "OldPriceWhole": 21678,
    "NewPriceWhole": 21678,
    "PassengerDetails": { /* ... */ },
    "Hash": "bd8c260d1e327cfad1811b068926b0dfbb94d65ef44463a325825701579fb18c6aa32f7227e346c4dbd87fca333fff247548f896dd451d831058a48e1ecd6c31"
  }
]
```

* Validate Hash using MerchantKey\_ConfirmationCode\_NewPriceWhole and SHA-512 hex string comparison.

### Bus Ticket Issue

Ticket Issue API (bus): <https://api.staging.trips.ng/api/v2/ticketing/issue>

Request example:

```json
{
  "SessionId": "25fe6b49e3794f4585a0ba4c6f40f2a5",
  "TripType": "Domestic",
  "TripMode": "Road"
}
```

Sample response:

```json
{
  "Pnr": "6C6E44D1AGEJ",
  "IsSuccessful": true,
  "Message": "Successful",
  "BookingStatus": "TicketPending"
}
```

### Cancel Ticket Booking (Bus)

Cancel API: <https://api.staging.trips.ng/api/Bus/CancelTicketBooking>

Request payload:

```json
{
  "PNRNumber": "94674A93AGEJ",
  "Surname": "Mike",
  "CancelType": 0
}
```

Sample response:

```json
{
  "WarningMessageList": ["Booking Cancelation Successful"],
  "IsSuccess": true
}
```

### My Reservation (Bus)

Endpoint: <https://api.staging.trips.ng/api/Bus/MyReservation>

Sample request:

```json
{
  "BookingReferenceId": "1EA30721AGEJ",
  "BookingReferenceType": 10,
  "Surname": "Mike",
  "ETicketNumber": ""
}
```

Sample response includes travellers, seats, totals and booking status.

### Fare/Travel Rules (Bus)

Endpoint: <https://api.staging.trips.ng/api/Bus/TravelRules>

Request example:

```json
{
  "AgentId": 168,
  "GDSId": 102,
  "CombinationID": 0,
  "RecommendationID": 0,
  "SessionId": "717d0f85a4d44e269cb87ea979a529af"
}
```

Response includes HTML Terms and Conditions and textual rules.

***

## Notes & Reminders

* Always use the exact concatenation format: {MerchantKey}*{ConfirmationCode}*{NewPriceWhole} when computing the SHA-512 hash.
* Do not share your MerchantKey. Hash validation occurs on your backend.
* All URLs in this document must be used verbatim (do not modify query params or endpoints).
* Many confirmation endpoints return arrays (especially domestic multi-leg or round-trip scenarios); validate the Hash for each returned confirmation entry independently.
