{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"description":"The Karhoo fares API Gateway service","version":"v1.0","title":"Fares API 1.0","contact":{"email":"api@karhoo.com"},"x-hugo-values":{"tags":["api"],"categories":["fares"],"public":true}},"paths":{"/trip/{tripID}":{"get":{"tags":["final-fare"],"summary":"Get final fare from trip id","description":"Due to the asynchronous nature of the way our partners arrive at final fares, we sometimes can't provide you with a 'final fare' imeadiately, \nthis may be due to a number of reasons including the addition of extras, such as 'Waiting Time' that may be added to a journey after it has completed.  \nBecause of this, we provide the following endpoint, this will give you an expected time to a final fare, \na fare status and ultimately a fare breakdown that includes fares, services, extras and expenses.\nThe overall total is the sum of each fare components net_price and tax_amount\n","operationId":"finalFareGet","parameters":[{"name":"tripID","in":"path","required":true,"description":"trips id you want the final fare for","schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}}],"responses":{"200":{"description":"Returned final fare","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalFare"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"}},"security":[{"Bearer":[]}]}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/fares"}],"components":{"responses":{"400InvalidInput":{"description":"Bad Request. The request was invalid.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0002","description":"Error number"},"message":{"type":"string","example":"Invalid request payload","description":"Message of the error"},"details":{"type":"string","example":"Invalid request payload","description":"Details of the error"}}}}}},"401Unauthorized":{"description":"Unauthorized. The request requires user authentication (not logged in).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K6001","enum":["K6001","K0402"],"description":"Error number"},"message":{"type":"string","example":"Could not authenticate","description":"Message of the error"},"details":{"type":"string","example":"Could not authenticate","description":"Details of the error"}}}}}},"403Forbidden":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request. Please request access by emailing [API Support](api@karhoo.com?subject=API%20Access%20Request).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0005","description":"Error number"},"message":{"type":"string","example":"Missing required role for this request","description":"Message of the error"},"details":{"type":"string","example":"Missing required role for this request","description":"Details of the error"}}}}}},"404NotFound":{"description":"Not found.  Item not found, or following information is not available anymore.","content":{"*/*":{"schema":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error","example":"K4003","enum":["K4012","K4003"]},"message":{"type":"string","example":"System-generated error message","description":"Message of the error"},"details":{"type":"string","description":"Details of the actual error","example":"Item not found"}}}}}},"429RateLimit":{"description":"Error. Too Many Requests. Exceeded the rate limit for requests.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0006","description":"Error number"},"message":{"type":"string","example":"System-generated error message","description":"Message of the error"},"details":{"type":"string","example":"Rate limit exceeded","description":"Details of the error"}}}}}},"500InternalServerErr":{"description":"Internal server error. Something has gone wrong on the website's server, but the server could not be more specific on what the exact problem is.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0001","enum":["K0001","K0201","K0301"],"description":"Error number"},"message":{"type":"string","example":"System-generated error message","description":"Message of the error"},"details":{"type":"string","example":"General request error","description":"Details of the error"}}}}}},"502BadGateway":{"description":"Bad Gateway. The server, which was acting as a gateway or proxy, received an invalid response from the upstream server.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0000","description":"Error number"},"message":{"type":"string","example":"System-generated error message","description":"Message of the error"},"details":{"type":"string","example":"Bad Gateway error","description":"Details of the error"}}}}}}},"securitySchemes":{"Bearer":{"description":"For accessing the API a valid JWT token must be passed in all the queries in the 'Authorization' header.\nA valid JWT token is generated by the auth API.\nThe following syntax must be used in the 'Authorization' header :\nBearer: xxxxxx.yyyyyyy.zzzzzz","type":"apiKey","name":"authorization","in":"header"}},"schemas":{"FinalFare":{"type":"object","required":["state"],"properties":{"state":{"type":"string","description":"The current state of the fare.\nPENDING - the fare is not yet final and might be subject to change. It can not yet be charged.\nFINAL - the fare is final and its value is now chargeable\nCANCELLED - the trip has been cancelled (with trip statuses being amongst CANCELLED_BY_DISPATCH, CANCELLED_BY_KARHOO or CANCELLED_BY_USER) and will result in a CANCELLED fare.\n\n  A CANCELLED state implies that the cancellation should be handled offline.\n\nFAILED - something went wrong with the trip\n","example":"PENDING","enum":["PENDING","FINAL","CANCELLED","FAILED"]},"expected_final_time":{"type":"string","format":"date-time","description":"The expected timestamp in UTC for fare complete, ISO8601 /date-time / rfc3339","example":"2016-04-16T16:06:05Z"},"expected_in":{"type":"integer","format":"int32","description":"The number of seconds until current expected_final_time","example":"360"},"breakdown":{"$ref":"#/components/schemas/Breakdown"}}},"Breakdown":{"type":"object","description":"BASE - It’s the cost of the ride.\n  For metered fares it may include approach fee or waiting time incurred.\n  For fixed fares it might include the service fee.\nCOMMISSION - Amount to facilitate the transaction.\nEXPENSE - Expenses the driver may incur while executing the ride. eg. parking, tolls, cleaning fee, congestion charge, etc.\n  No commissions or taxes (as they’re already included in the expense) will be charged on expenses\nEXTRAS - Any addition to the base service that might affect the ride. eg. extra passenger, luggage, waiting time (for fixed fares), bike, child seat, etc.\n","properties":{"base":{"$ref":"#/components/schemas/BreakdownItem"},"commission":{"$ref":"#/components/schemas/BreakdownItem"},"extras":{"type":"array","description":"Extras contains a list of extras included in the fare","items":{"$ref":"#/components/schemas/BreakdownItem"}},"expenses":{"type":"array","description":"Expenses contains a list of expenses included in the fare","items":{"$ref":"#/components/schemas/BreakdownItem"}},"total":{"type":"number","description":"Total is the total price of the trip. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.\nThe overall total is the sum of each fare components net_price and tax_amount\n","format":"double"},"currency":{"type":"string","example":"EUR","description":"Currency of the fare. Format is ISO4217."}}},"BreakdownItem":{"type":"object","properties":{"tax_percentage":{"type":"number","description":"The percentage of tax applied to the item"},"discount_percentage":{"type":"number","description":"The percent of discount applied to the item"},"commission_percentage":{"type":"number","description":"The percent of commission applied to the item"},"tax_amount":{"type":"number","format":"double","description":"The amount of tax for the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence."},"list_price":{"type":"number","format":"double","description":"The list price of the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence."},"net_price":{"type":"number","format":"double","description":"The net price of the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence."}}},"Error":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error"},"message":{"type":"string","description":"Details of the actual error"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}}},"ErrorDetails":{"type":"object","description":"Additional information about the error (such as which field failed validation)","properties":{"message":{"type":"string","description":"Summary of additional information"},"detail":{"type":"string","description":"Actual detail of the error"}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}