Brand Loyalty Programs
Allow your users to use their loyalty points in your systems to pay for Karhoo rides by implementing the Loyalty API endpoints.
Giving your loyalty members the ability to earn points or use their points to book in the global Karhoo Marketplace will increase member engagement and demonstrate the value of your brand.
Below are the topics that detail what's involved whether you use the Mobile or Web SDKs or the Bookings API.
Principles of Operation
- Fleet Suppliers will always be settled in their local currency.
- Customers will be offered flexible payment options using points to offset currency value.
- Loyalty points will be prepaid at time of booking and card payments will be pre-authed for the balance.
- You will need to implement the Loyalty API endpoints and host them within your platform to support the integration. We will ask you for the host so that we know where to send the requests to get exchange rates, get loyalty points balance, burn and refund points.
Let's get started!
Loyalty API flow
1) OAuth integration with Karhoo
This is the first step of your Loyalty integration. This will allow your users to be seamlessly integrated in the Karhoo platform. When your users will book trips we will record the traveller_id field - this is the id the user has in your system, allowing you to easily search all bookings performed by a specific user by calling our Search Bookings endpoint (step 7).
Exchange rates enable the Karhoo Marketplace to translate your points to an equivalent value in the currency fleets use. You will need to provide loyalty exchange rates for all supported currencies. If you don't support a currency you should not return an exchange rate for it and we will not allow using loyalty points for payments in that currency.
Security for this endpoint is provided by the X-API-KEY header and the value is the API Key issued by your system.
Karhoo will need a secure way to check the number of Loyalty points your user has in your system and if he can use (burn) them. Branded Karhoo products and the SDK will use this information to offer different payment options depending on the number of points available.
Security for this endpoint is provided by the Bearer Token issued to Karhoo as part of the OAuth flow. This allows Karhoo to check the points balance for only this particular user.
This is where the magic happens and your passengers ride off into the sunset.
Karhoo will call this endpoint when a booking is requested by your user and if your system returns a successful response we will go ahead and book the trip with the selected fleet.
Security for this endpoint is provided by the Bearer Token issued to Karhoo as part of the OAuth flow. This allows Karhoo to burn trips for only this particular user.
In the event that a fleet or the user cancels the trip the loyalty points we burned can completely or partially be refunded. In that case, Karhoo will call the refund endpoint on your system to refund the points to your user.
Security for this endpoint is provided by the X-API-KEY header and the value is the API Key issued by your system. We are not using a Bearer Token for this as the cancellation might happen weeks after the trip was booked and the Bearer Token might have already expired.
Once a trip is booked you can get updates and track the driver using the Booking API
Karhoo provides a flexible endpoint that can be used to retrieve the bookings performed by your users using Karhoo. Just use the traveller_id field (the id the user has in your system) and you will be able to see all his bookings and filter them based on state or date.
How loyalty points are converted to money
Karhoo will generate statements detailing the points used by your users and invoice you for their value on a periodic basis.
Karhoo always pays the fleets in the currency they operate, fleets will never receive information about loyalty points. Also as a Brand partner you don't need to worry about any interactions with the Fleets, Karhoo will take care of that.
Updated about 4 years ago