{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"title":"Payments API 3.0","version":"3.0.0"},"tags":[{"name":"Payments","description":"Payments API"},{"name":"Loyalty","description":"Loyalty API"}],"paths":{"/providers":{"get":{"tags":["Payments"],"description":"This call returns the ID of the payment provider for the demand partner. In addition the response payload contains the list of the loyalty programmes that the demand partner offers to pay trips with loyalty points.\n","summary":"Payment providers and loyalty programmes\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentProvidersResponse"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"406":{"description":"Returned when JWT payload is wrong, or user doesn't have access to resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}},"security":[{"JWT":[]}]}},"/loyalty/programmes/{id}/balance":{"get":{"tags":["Loyalty"],"description":"This call returns the user's balance for the given loyalty programme ID. The response payload contains the amount of points the user can burn if the user can burn points. The user is identified by the 'upstream' token embedded in the authentication JWT. This is only possible if users are using a third party authentication to use the platform (see https://developer.karhoo.com/docs/how-to-integrate-third-party-auth-system).\n","summary":"Loyalty points user's balance","parameters":[{"name":"id","in":"path","required":true,"description":"ID of the loyalty programme.\n","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetLoyaltyBalanceResponse"}}}},"400":{"description":"Partner Traveller ID not provided in the JWT token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"424":{"description":"Failed to contact loyalty partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}},"security":[{"JWT":[]}]}},"/loyalty/programmes/{id}/rates":{"get":{"tags":["Loyalty"],"description":"This call returns conversion rates for the given loyalty programme ID. The response contains a list of conversion rates to allow the client to compute the amount of points is equivalent to a specific amount of money in a particular currency.\n","summary":"Loyalty points conversion rates","parameters":[{"name":"id","in":"path","required":true,"description":"ID of the loyalty programme.\n","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRatesResponse"}}}},"400":{"description":"Demand Traveller ID not provided in the JWT token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"424":{"description":"Failed to contact loyalty partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}},"security":[{"JWT":[]}]}}},"servers":[{"url":"http://rest.sandbox.karhoo.com/v3/payments/"},{"url":"https://rest.sandbox.karhoo.com/v3/payments/"}],"components":{"securitySchemes":{"JWT":{"description":"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"GetPaymentProvidersResponse":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/ProviderResponseObject"},"loyalty_programmes":{"type":"array","items":{"$ref":"#/components/schemas/LoyaltyProgrammeObject"}}}},"LoyaltyProgrammeObject":{"type":"object","description":"The list of available loyalty programmes supported by the demand partner\n","properties":{"id":{"type":"string","format":"uuid","description":"The ID of the loyalty programme offerd by the demand partner to allow users to pay by burning loyalty points\n"},"name":{"type":"string","example":"Amazing Loyalty Programme","description":"The name of the loyalty programme offerd by the demand partner to allow users to pay by burning loyalty points\n"}}},"ProviderResponseObject":{"type":"object","properties":{"id":{"type":"string","enum":["Braintree","Adyen"],"description":"ID of the PSP for this organisation"}}},"GetLoyaltyBalanceResponse":{"type":"object","properties":{"points":{"type":"integer","format":"int64","minimum":0,"example":120000,"description":"The amount of points that the user can burn"},"can_burn":{"type":"boolean","description":"This flag specifies if the user is elegible to burn points"}}},"GetRatesResponse":{"required":["version","rates"],"type":"object","properties":{"version":{"type":"string","example":"20200312","description":"Version of the current conversion rates"},"rates":{"type":"array","items":{"$ref":"#/components/schemas/RateObject"}}}},"RateObject":{"type":"object","required":["currency","points"],"properties":{"currency":{"type":"string","description":"The ISO 4217 code for currency used. This represents the smallest unit of the currency_code","example":"GBP"},"points":{"type":"string","description":"the number of loyalty points equal to the smallest unit of the currency. This is a string as the value can have decimals for some currencies for example 1 COP= 0.037 points","example":"114.58"}}},"ServiceError":{"type":"object","properties":{"code":{"type":"string","enum":["K0004","K0005"],"description":"Error code"},"message":{"type":"string","description":"Textual error description"}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}