Guia do BikeKit

The rider app

Iniciar sessão

Por enquanto, este guia está só em inglês.

Riders use a phone app. BikeKit's rider app is built on Gira+, an open-source app made for Lisbon's riders, adapted to talk to the BikeKit server. It runs on Android and in a web browser, has an iOS project, and is published under the GNU GPL version 3, like Gira+, so you may adapt it and publish it for your scheme under the same licence. It lives in its own repository.

Any other app can do the same: the rider interface is a documented HTTP API (plan.md §8.1), and live updates come over one stream (GET /v1/live).

What riders can do

  • Account. Sign up with a name, email and password, accept the terms, choose whether to receive marketing, and enter a friend's referral code. Reset a forgotten password with a code sent by email.
  • The map. Every station live, with its bikes and free docks, updating as bikes come and go: virtual stations with their zones, stations reserved for a company, closures, and the control room's notices on a station. Each bike shows its dock, type, battery and any fault reported.
  • Unlock a bike (below).
  • During a ride: pause and resume with the e-lock, call for help, report a fault with photos, say a bike was docked but the ride didn't end, or report it lost or stolen.
  • After a ride: its time, distance and charge; a rating from one to five stars, with tags and a comment; and paying the charge with points.
  • History: past rides with their routes, export to GPX for Strava and similar apps, rating and fault reports.
  • Wallet: balance, top-ups, saved cards, vouchers and every movement.
  • Passes: the current pass and those on sale, with their prices and terms, bought from the wallet or by card.
  • Rewards: points and their history, badges and progress towards the next, and the rider's referral code to share.
  • Messages: service messages (unread ones pop up), and notification settings.
  • Account page: profile, riding statistics and CO₂ avoided, invoices as PDF, and privacy requests: a copy of their data or closing the account.
  • Language: Portuguese or English. The server writes to the rider in the app's language.

Unlocking

To unlock, a rider needs:

  • an active pass, or a ticket with rides left;
  • a wallet that isn't negative;
  • no other ride open, and at most one open report of a lost bike or a missed return;
  • five minutes since their last ride ended (the wait between rides), so the same bike can't be ridden for free forever by re-docking it.

Then, at a station:

  1. Choose a bike on the map, or scan the QR sticker on the bike, or type its code.
  2. The dock (or the bike's own lock, at a virtual station) opens. The rider has 30 seconds to take the bike.
  3. The ride starts when the bike leaves the dock. If they don't take it, nothing is charged.

If the app refuses, it says why: no pass, a negative balance, a ride already open, waiting between rides, a station closed or reserved for a company, or a bike that isn't available.

A bike taken and returned to the same station within three minutes is a false start: free, and it doesn't start the wait between rides. A rider may have three an hour; it is how they swap a bike they find faulty.

Pausing

Bikes with an e-lock (a lock on the bike itself) can be paused mid-ride, to stop for a coffee and keep the bike:

  1. Pause locks the bike where it stands. The ride carries on: paused time costs what riding would.
  2. Resume unlocks it and the rider rides on.

A pause longer than 20 minutes sends the rider a reminder and alerts the control room. Nothing unlocks a bike by itself.

Returning

  1. Ride to any station with a free dock and push the bike in until it locks. At a virtual station, lock the bike inside the marked area.
  2. The ride ends the moment the station reports the bike, and the rider gets a receipt.

If the station is full, the app lists the nearest stations with a free dock, virtual stations included.

If the bike was docked but the ride is still running, the rider says so in the app (docked, but the ride didn't end) and names the station: the ride's charge stops there, and Support checks it. Likewise for a bike lost or stolen. A rider can have one such report open at a time.

A ride that runs long sends the rider a reminder just before the free period ends (40 minutes), and after six hours a push and an email that the bike hasn't been returned. A ride is never charged for more than 24 hours, nor more than the pass's cap.

Paying

  • Top up the wallet by card, Multibanco, PayPal, Apple Pay or Google Pay, from €10. Cards can be saved, up to five, with one as the default. The app never sees the card number: the payment provider keeps it.
  • Buy a pass from the wallet or by card. The day pass is paid by card only and holds a deposit on it, unless the rider signed a direct debit mandate.
  • Ride charges come out of the wallet when the ride ends.
  • Points pay for a ride's charge within 24 hours of the ride: 500 points take €1 off.
  • Vouchers add credit or a pass.

Every payment and refund gets an invoice or credit note, which the rider downloads from the app.

For the app's developers, with Stripe (the full contract is in plan.md §6.6):

  1. GET /v1/payments/provider answers { "provider": "stripe", "publishable_key": "pk_…" }; start Stripe's SDK with that key.
  2. Collect the card, Apple Pay or Google Pay with the SDK, which gives a PaymentMethod. Send its id (pm_…) as payment_token, with an Idempotency-Key header made up once for this payment.
  3. If BikeKit answers 409 with code: "PAYMENT_PENDING", the bank wants the rider to confirm. Hand details.client_secret to the SDK's handleNextAction, then send the same request again with the same key: it answers the payment once Stripe has it. A client_secret of null means a bank is clearing it, with nothing for the rider to do.
  4. Saving a card works the same way: post the pm_… to /v1/me/cards; if it is PAYMENT_PENDING, confirm the SetupIntent with the SDK and post its id (seti_…, the part of the secret before _secret_).

Trying 3-D Secure without Stripe. On the test gateway (PAYMENT_PROVIDER=mock, the default), pay with the test card "Asks for 3-D Secure" (tok_3ds). The app then shows a stand-in bank sheet: approve, fail or close it. "Bank clears it later" (tok_processing) shows the "your bank is processing it" state, and the money arrives about 30 seconds later. A card saved as "Visa with 3-D Secure" asks again each time it pays. The sheet answers through POST /v1/payments/mock/challenge, which only the test gateway serves (plan.md §16 385).

Trying the app

To try the app against a demo city on a laptop, see Ride a bike yourself. In a simulated city, the app can ride the bike for you: after unlocking, pick a station and the simulator rides it there along real streets and docks it, and the server sees a real ride.