docs.us.megabus.com Open in urlscan Pro
3.161.213.68  Public Scan

Form analysis
1 forms found in the DOM

GET ./search.html

<form id="rtd-search-form" class="wy-form" action="./search.html" method="get">
  <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" title="Type search term here">
</form>

Text Content

Megabus API Documentation

 * Home
   * How the APIs are organised
     * SOAP based APIs
   * Typical usage scenario
     * A simple API flow - searching for and purchasing a journey (using search,
       book and basket APIs)
   * Frequently Asked Questions
   * Other information
   * Environments
   * API Security
   * API Body Header Information

 * Frequently Asked Questions

Search

 * Search overview
 * Region
 * Origin
 * Destination
 * Destination by stop
 * Journey
 * Search
 * ReturnJourney
 * WeekendJourney
 * Schedule
 * Transport
 * Travel Dates
 * Validate Promotion Code

Book

 * Book overview
 * RetrieveBasket
 * AddToBasket
 * BasketRemoveItem
 * CustomerContact
 * StoreVoucher
 * SaveBasketPassengers
 * BasketRemoveItem
 * BasketPrepareCheckout
 * CompleteOrder
 * ReleaseBasket

Basket

 * Basket overview
 * AddSalesClassToBasket
 * AddSeatToBasket
 * GetSeatSelections
 * AddRedemptionCode
 * Checkout
 * PrepareWorldpayCorporateCheckout
 * RetrieveBillingInformation
 * DirectPayment
 * Authorise3dSecure

Order

 * Order overview
 * RetrieveAllCustomerOrders
 * RetrieveCustomerOrder
 * RetrieveOrderByMerchantReference
 * RetrieveOrderDetailsByMerchantReference
 * RetrieveOrderByReservationDetailsReference

Reservation Management

 * Reservation overview
 * RetrieveOrder
 * AddOrderToBasket
 * CancelOrder
 * RetrieveReservationPassenger
 * SaveReservationPassenger
 * RetrieveReservationByReservationKey
 * RescheduleReservation
 * RefundReservation

Information

 * Information overview
 * ServiceInformation
 * CityInformation
 * JourneyInformation
 * RetrieveDocumentTypes
 * PassengerInformationEnforcement
 * RetrieveDisabilityTypes
 * RetrieveWebsiteTypes
 * Cities
 * SiteInformation

Seat Plan

 * Seat overview
 * GetSeatClassAvailability
 * GetSeatPlanAvailability

User Management

 * User overview
 * CreateAccount
 * CreateUserAccount [Deprecated]
 * ActivateAccount
 * ResendActivationEmail
 * AddUserFavouriteLocation
 * AssociateOrderToAccount
 * VerifyLoginDetails
 * VerifyFacebookAccount
 * AmendUserAccountDetails
 * RetrieveUserDetails
 * RetrieveUserReservations
 * UpdatePaymentToken
 * RetrievePaymentTokens
 * DeletePaymentToken
 * UnregisterAccount
 * ResetPassword
 * ChangePassword
 * ChangeEmailAddress
 * ActivateEmailAddress
 * RetrieveMarketingPreferences
 * SaveMarketingPreferences
 * SaveUserPassenger
 * RetrieveUserPassengerList
 * RetrieveUserPassenger
 * RemoveUserFavouriteLocation
 * RemoveUserPassenger

Agency

 * Agency overview
 * VerifyAgentLogin
 * RetrieveAgencyPaymentTypes
 * ForgottenAgentPassword
 * ForgottenAgentPasswordSelfService
 * AgentResetPassword
 * AgentChangePassword

Common XML Data Types

 * AddressInformationType
 * BasketType
 * BillingInformationType
 * CoordinatesType
 * EncryptedCardPaymentType
 * InformationType
 * LineItemType
 * LineItemTaxType
 * LocationType
 * OrderType
 * PassengerClassSelectionType
 * PassengerInfoType
 * PassengerSeatSelectionType
 * PaymentMethodType
 * PaymentTokenType
 * GooglePayPaymentType
 * RateCodeInformationType
 * SalesClassInformationType
 * SeatClassAvailabilityType
 * SearchResultType
 * RealtimeType
 * SingleSeatType
 * StoredTokenPaymentType
 * TaxType

Megabus API Documentation
 * 
 * Home
 * 

--------------------------------------------------------------------------------


WELCOME

This website is intended to provide documentation of all the Megabus APIs
required to support web and mobile applications.


HOW THE APIS ARE ORGANISED

The following systems / services expose APIs for use by the website
implementation.


SOAP BASED APIS

 * Search -- provides APIs relating to journey planning (Note: these APIs are
   the existing/old API for journey planning and search - a new, more flexible
   service is under construction - see 'JourneySearch' below)
 * Book -- APIs typically used on a "booking" page of the website (including
   adding journeys to the basket)
 * Basket -- APIs relating to the "basket" page of the website
 * Order -- APIs used to obtain items in a customer's order history
 * Information -- APIs to obtain information about services (service
   advisories), details of stop locations within cities, etc.
 * SeatPlan -- APIs to allow vehicle seating plans to be obtained
 * User management -- APIs to allow users to log in, manage passwords and email
   addresses, and save passenger profiles
 * Reservation Management -- APIs to support journey reservation updates
 * Agency -- APIs which will only apply to the Agent website


TYPICAL USAGE SCENARIO

The following diagram illustrates the rough flow of how the APIs are used by the
current website:



This doesn't show all APIs, and only relates to a "happy path" of a user
searching and booking travel on the current / old web site.


A SIMPLE API FLOW - SEARCHING FOR AND PURCHASING A JOURNEY (USING SEARCH, BOOK
AND BASKET APIS)

It is beyond the scope of this document to prescriptively list all the flows
related to the various possible scenarios, but the following overview of how the
APIs may be used is intended to give a flavour of how the APIs fit together (see
the individual reference pages for each API for details of how each one is
called and the data returned).

The flow diagram above shows at a conceptual level how the old Megabus website
presented the issue of finding a journey (by presenting the user with a region
menu, then a menu of towns/cities in the chosen region, then a choice of
destinations available which start in that location, then selecting a particular
journey from a list of available dates and times), then adding it to the basket
and going to checkout.

The simplest possible flow would be as follows:

 1. Obtain a set of possible journeys using the Search API.

 2. Call the AddToBasket API, passing the appropriate journey_id value obtained
    in the previous step.

 3. Complete the purchase by taking the basket through the checkout process. The
    exact APIs to be used will depend on the payment method to be used for the
    particular situation;
    
    * for cash payments (e.g., via Agency site or kiosk), use the CompleteOrder
      API.
    
    * otherwise the BasketPrepareCheckout API can be used, which will return a
      URL to take the user to the appropriate payment service provider's
      website, along with the data to be passed through to the payment provider
      (this may involve an extra step for Worldpay Corporate).

 4. In order to tidy up, the basket may be destroyed after use via the
    ReleaseBasket API.

Between steps 2 and 3 above, various other operations may be carried out:

 * passenger information may be added using SaveBasketPassengers

 * in some situations seat reservations or classes can be added to the basket
   before purchase (using (AddSeatToBasket or AddSalesClassToBasket, having
   first obtained information about available seats or seat classes on the
   journey in question using GetSeatPlanAvailability /
   GetSeatClassAvailability).

It possible to provide the ability for users to create an account and log in,
which gives regular users the ability to save their name and address details,
and also details of any passengers which they may regularly book journeys for
(this information can be used to pre-populate booking pages to save time when
booking). The APIs discussed in the User management section provide the
necessary functionality (in the case of an Agency website the login will be
slightly different - the Agency APIs are provided to enable agency login and to
enable queries about which payment types the agency in question supports).

It is also possible to provide service updates and other information about the
origins / destinations, stops, and journeys that the user is interested in
during the initial journey search flow - this functionality can be provided
using the Information APIs.

Finally, the APIs documented in the Order section may be used to view details of
orders once they have been placed, and the Reservation Management APIs can be
used if any amendments or cancellations to existing orders are required.


FREQUENTLY ASKED QUESTIONS

The FAQ section of this documentation site contains a number of questions and
answers covering topics which might otherwise be difficult to understand, and is
worth consulting if you cannot find what you need in the main reference
sections. This FAQ section is intended to grow over time as more questions come
up:

 * FAQ


OTHER INFORMATION

The following annotated WSDL documents can be viewed as html in a browser, which
describe the interfaces to the SOAP based APIs in more detail:

 * search wsdl
 * agent wsdl
 * basket wsdl
 * book wsdl
 * order wsdl
 * reservation wsdl
 * information wsdl
 * seat wsdl
 * user wsdl

(Note: these links may not work properly if you are viewing this documentation
as a set of html files on a drive, rather than hosted by a website. If so, you
will find the wsdl information in the wsdl_info folder of the .zip - go into
that folder and view the xxx-wsdl.xml file(s) in a browser - it should pick up
the associated stylesheet which makes the format more readable).

You may notice that some other links in this site don't work properly if viewing
from a local drive - however the contents pane along the left can still be used
for navigating.


ENVIRONMENTS

The APIs are available in two environments QA and Production. The endpoint for
each environment is as follows:

Environment API Gateway Endpoint QA https://api.qa.megabus.coachusa.com/v2
Production https://api.prod.megabus.coachusa.com/v2

NOTE - Your IP needs to be whitelisted before you can access API Gateway


API SECURITY

The SOAP web services are secured using WS-Security. Username and password
credentials are passed in the SOAP header. An example SOAP message is shown
below with the security header included:

<soapenv:Envelope xmlns:com="http://stagecoach.com/schemas/engine/common" xmlns:sear="http://stagecoach.com/schemas/engine/search" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
   <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsse:UsernameToken>
        <wsse:Username>USERNAME</wsse:Username>
        <wsse:Password>PASSWORD</wsse:Password>
      </wsse:UsernameToken>
   </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <sear:OriginRequest>
         <sear:header>
            <com:version>1.0</com:version>
            <com:retailOperation>US</com:retailOperation>
            <com:channel>DIGITAL</com:channel>
            <com:agentId>1</com:agentId>
         </sear:header>
      </sear:OriginRequest>
   </soapenv:Body>
</soapenv:Envelope>


If the security credentials aren't valid then the following SOAP fault is
returned:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">Bad authentication credentials provided</faultstring>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Access to each endpoint is controlled on the server by the access rights
assigned to the username included in the SOAP security header. Access to the
APIs is controlled at the endpoint level. For example, if a username has access
to the Search endpoint then it has access to all of the methods included at that
endpoint. The list of endpoints is as follows:

API End point Search /engine/services/search Book /engine/services/book Basket
/engine/services/basket Order /engine/services/order Information
/engine/services/information Seat Plan /engine/services/seat User Management
/engine/services/user Reservation Management /engine/services/reservation Agency
/engine/services/agent


API BODY HEADER INFORMATION

The SOAP web services have body header information. Please make sure to provide
the body header information on all api calls. An example SOAP message is shown
below with the body header included:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bas="http://stagecoach.com/schemas/engine/basket" xmlns:com="http://stagecoach.com/schemas/engine/common">
    <soapenv:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
    <wsse:Username>USERNAME</wsse:Username>
    <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
    </wsse:UsernameToken>
    </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <bas:DirectPaymentRequest>
         <bas:header>
            <com:version>1.0</com:version>
            <com:retailOperation>US</com:retailOperation>
            <com:channel>DIGITAL</com:channel>
            <com:visitorReference>a68c3450-b413-4f75-9db1-481fd584b621</com:visitorReference>
            <com:userAgent>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3</com:userAgent>
            <com:ipAddress>148.252.236.44</com:ipAddress>
            <com:sessionId>4887cbd9-caad-4e9f-937a-00971390512e</com:sessionId>
         </bas:header>
     <bas:basketId>1</bas:basketId>
         <bas:language>en</bas:language>
         <bas:encryptedCard>
            <bas:encryptedData>xxxxxxxxxxxxxxxxxxxxxxxxxxxx</bas:encryptedData>
            <bas:storeCard>false</bas:storeCard>
            <bas:setDefault>false</bas:setDefault>
            <bas:addressInformation>
               <com:firstName>test</com:firstName>
               <com:lastName>test</com:lastName>
               <com:addressLine1>test</com:addressLine1>
               <com:addressLine2>test</com:addressLine2>
               <com:addressLine3>test</com:addressLine3>
               <com:townCity>test</com:townCity>
               <com:region>test</com:region>
               <com:country>US</com:country>
               <com:postalCode>test</com:postalCode>
               <com:telephoneNumber>1234567890</com:telephoneNumber>
               <com:emailAddress>test@test.com</com:emailAddress>
            </bas:addressInformation>
            <bas:updateUserDetails>false</bas:updateUserDetails>
         </bas:encryptedCard>
      </bas:DirectPaymentRequest>
   </soapenv:Body>
</soapenv:Envelope>


Parameter Type Description retailOperation string The retailOperation relative
to the environment (US,CA,TC). channel string The channel describes the place
where the request is coming from. (DIGITAL,AGENT,AFFILIATE). visitorReference
string (Guid) The customers guid session that lasts a year. userAgent string The
full User-Agent sent from the client. ipAddress string The IP address of the
browser used by the customer. sessionId string (Guid) The customers guid session
that last only for the current browser history. This value should match the
session id value that is passed in the beacon JavaScript.

SessionId is passed to Riskified (our risk management provider as card_token
field).

If the userAgent and ipAddress fields are not provided in the body header the
following SOAP fault is returned:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns3:DirectPaymentResponse xmlns:ns2="http://stagecoach.com/schemas/engine/common" xmlns:ns3="http://stagecoach.com/schemas/engine/basket">
         <ns3:header>
            <ns2:version>1.0</ns2:version>
            <ns2:Error description="Both userAgent and ipAddress should be provided." id="1705"/>
            <ns2:Error description="Both userAgent and ipAddress should be provided." id="1705"/>
         </ns3:header>
      </ns3:DirectPaymentResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


if ipAddress field is not provided the following SOAP fault is returned:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns3:DirectPaymentResponse xmlns:ns2="http://stagecoach.com/schemas/engine/common" xmlns:ns3="http://stagecoach.com/schemas/engine/basket">
         <ns3:header>
            <ns2:version>1.0</ns2:version>
            <ns2:Error description="IpAddress should be provided." id="1706"/>
         </ns3:header>
      </ns3:DirectPaymentResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Next

--------------------------------------------------------------------------------

Copyright © 2018 Stagecoach Group plc.

Built with MkDocs using a theme provided by Read the Docs.
Next »