BikeKit

How riders pay is up to you: passes, single-ride tickets, a prepaid wallet, deposits or a direct debit, vouchers and points. BikeKit ships with the prices of a typical scheme, which you change on the Settings pages. Managers own the rules; Marketing owns passes, prices and vouchers.

How riders pay

A pass or ticket to ride. Riding needs an active pass or a ticket with rides left. There's no trial, no grace period and no automatic renewal.
A ride's charge. Each pass has a tariff: the first period (45 minutes by default) is free, and longer rides cost by the period, up to a cap per ride. The charge comes out of the wallet when the ride ends.
The wallet. Riders top it up by card, Multibanco, PayPal, Apple Pay or Google Pay (at least €10 by default). Passes can be paid from it. A ride can take it below zero; a negative wallet blocks the next unlock until a top-up covers it.
Points. Riders on passes that earn them get points for every ride, and bonus points for helping balance the city: taking a bike from a nearly full station or returning one to a nearly empty one. Points pay for a ride's charge within a day of the ride, and for nothing else.

The prices that come with BikeKit:

Pass	Price	Lasts	Paid	Deposit	Earns points	After the first 45 minutes
Annual	€25	a year	wallet or card	none	yes	€1 for the second period, €2 each after, at most €10 a ride
Annual, student	€15	a year	wallet or card	none	yes	the same. Needs a verified student card
Monthly	€15	30 days	wallet or card	none	yes	the same
Day	€2	24 hours	card only	€300 held on the card	no	€2 each period, at most €10 a ride
1, 3 or 5 rides	€1, €2.50, €4	rides within 30 days	wallet or card	none	no	as the day pass

A rider holds one time pass at a time; buying the same one again renews it from its end. Tickets can be held beside anything, and are used only when no time pass is running.

Deposit or direct debit. The day pass holds a deposit on the rider's card while it lasts, released five days after it ends. A rider with a verified identity document can sign a SEPA direct debit mandate instead, and buy without the deposit; Support can then collect what the deposit would have covered.

Payment providers

BikeKit takes payments through one provider at a time, chosen with the PAYMENT_PROVIDER setting:

mock, the default: a test gateway that takes test tokens only. Fine for a demo, never for real riders.
stripe: Stripe. Cards, Apple Pay, Google Pay and Multibanco top up the wallet and buy passes; the day pass's deposit is a hold on the card that Support can capture in part; a payout to a rider's bank is a refund of their own top-up, back to the card it came from; and direct debits go through SEPA mandates kept at Stripe.
http: any other provider, through a small adapter you write against BikeKit's HTTP contract (PAYMENT_GATEWAY_URL).

Card numbers never reach BikeKit: the rider app collects them with the provider's own form, and BikeKit only keeps a reference, the brand, the last four digits and the expiry.

Payments that finish later. Some payments can't finish at once. A card may ask the rider to confirm in their bank's app (3-D Secure), and a SEPA debit takes the bank a few days. BikeKit then waits: nothing is credited or collected until the provider says it's done, and then it is, by itself. A rider who doesn't confirm within 15 minutes (PAYMENT_ACTION_TIMEOUT) is charged nothing, and the payment is cancelled at the provider. A direct debit Support collects shows in the rider's record once the bank pays it; one the bank refuses leaves nothing collected, and Support can charge the wallet instead.

Payouts with Stripe. A payout is refunded to the card of one of the rider's top-ups, the newest with enough left on it. If no single top-up covers the amount (say, three top-ups of €10 and a payout of €25), BikeKit refuses it: pay it out in two parts.

Rules

Settings → Rules holds the numbers that run the scheme. Each change is saved as a new version, so you always know which rules a ride was charged under.

Group	Rules
Rides	Longest billable ride (24 hours); wait between rides (5 minutes); false start window (3 minutes); free false starts per hour (3); longest pause with the e-lock (20 minutes); when to tell the rider a ride is long (40 minutes)
Balancing stations	Nearly empty below (10%) and nearly full above (90%), which decide the bonuses and which stations need rebalancing; the bonus for taking from a full station and for returning to an empty one (100 points each)
Points	Points for every ride (10); points for €1 off a ride (500); time to use points on a ride (24 hours)
Alerts	The thresholds of the alerts
Wallet	Smallest top-up (€10); how long a deposit is kept after a pass ends (5 days)

To change them:

Change the numbers. Each changed field shows Restore to put back its old value.
Review shows what changed, then Save version. New rides use the rules at once; rides in progress keep theirs.

Versions lists every earlier set, and Use these rules brings one back as a new version.

Passes and prices

Settings → Passes and prices lists every pass and ticket, with its price, how long it lasts, how it can be paid, its deposit, whether it earns points, and its tariff.

To change a price, open the pass and save: the change is a new version of it. New sales use it at once. Passes already sold keep the price and tariff they were bought under, and so do their rides.

To add a pass or ticket, New pass or ticket, then:

Give it a code (lower case, for the system), a Portuguese name and optionally an English one.
Set its price and how long it lasts. For a ticket, set how many rides it holds.
Choose how it can be paid (From the wallet or by card, or By card only), any deposit, and whether it earns points.
Set its tariff: the first period's length, the first period's price for classic and electric bikes, the second period, each later period, and the most one ride can cost.
Choose On sale, or Voucher only for a pass riders can only get with a voucher, such as a free pass for public transport season-ticket holders.
Add pass.

Vouchers

A voucher is a code a rider types in the app for wallet credit or a pass.

On Settings → Vouchers, New voucher: choose the code, what it gives (an amount of credit, or a pass), the most times it can be used (empty for no limit) and its last day (empty for no end), then Create voucher. Each rider can use a voucher once. Disable stops it at once. Voucher credit is a gift: it isn't invoiced and can't be paid out to a bank.

Invoices

Every sale produces an invoice, and every refund a credit note, automatically and without gaps in the numbering:

Sale	Document
A wallet top-up	An invoice-receipt for prepaid credit, outside VAT (VAT is charged when the credit is spent)
A ride's charge, a pass, a charge by Support	An invoice-receipt with VAT at the standard rate (`VAT_STANDARD_PCT`, 23% by default), included in the price
A deposit kept, or collected by direct debit	An invoice-receipt outside VAT (compensation)
A pass refund, points redeemed, a refund to the wallet, a payout to the bank	A credit note against the original

Documents follow Portuguese invoicing law: the series and numbering, the ATCUD code, the chained signature and the QR code. Each names the seller set in INVOICE_ISSUER_* (see Settings). An issued document never changes: it keeps its seller and its VAT rate after either setting changes, and a credit note against it gives back VAT at its rate. Riders read theirs in the app, as a PDF in their language. The city's accounting system can read every document as it is issued through an API client.

The built-in invoicing provider is a stand-in: it signs with a test key, and its documents say they are not valid tax documents. Before charging real riders, connect a certified invoicing provider.

Riders → Invoices finds documents by number or ATCUD, filters by type, sale and dates, totals what it lists (invoiced, credited and VAT net of credit notes), and opens each one as a web page or PDF. A rider's Money tab lists theirs.