Sell products in your client
This guide is for clients who want to sell shared mobility through their own channels using the Shared Mobility API.
assetId (the TOMP id for a product), vehicleId, and bike_id (both GBFS ids
for a product) all refer to the same id.
Before you begin
Before you start your implementation, make sure you have the following in place.
Agreement with the transport operators
- You must have permission to sell products on behalf of a transport operator.
- You must send the documentation Entur needs for settlement.
Show available products on a map
To find and display available shared mobility products, use the Mobility API. It provides the real-time GBFS data you need — typically price, battery status, location, and range.
Authenticate with the Shared Mobility API by sending an OAuth 2.0 bearer token in the Authorization header. See Authentication.
Sales flow
Once you have integrated with the Mobility API, you can use the Shared Mobility API to book products.
You can book a product in two ways:
- Select a product from the map. Use the GBFS data from the Mobility API to
show product information, check that you are allowed to sell the product, and
use the
assetIdto create a booking. - Scan a QR code. First call the QR endpoint to retrieve the
assetId/vehicleId/bike_idfrom the scanned code.
Payment
This section describes the payment flow for shared mobility bookings.
Recurring payment
A recurring payment must be set up before a booking can be made. See the Recurring payments API for how to set one up. It is used to pay for the bookings the user makes — send the recurring payment id when you create a booking.
Finalising payment
The final amount is calculated when the booking finishes (booking state
FINISHING / FINISH). The user is charged the final amount asynchronously when
the booking state changes to FINISHING / FINISH.
Failed payments
If a charge fails, the current handling is:
- We retry the charge up to three times, about one minute between each attempt.
- If it still fails, the booking is marked as payment failed and we retry up to around ten more times — the first retry at the next midnight, then roughly every three days (bounded by the payment provider's limit of about 15 attempts per month).
- If it still fails, the trip stays unpaid and the user cannot start a new trip
until it is settled. The next time they try to book, we charge the outstanding
amount using the recurring payment supplied for that new booking. If that
charge also fails, the new booking is rejected with
CouldNotStartTripMissingPaymentException(402, see Error handling), and the outstanding amount is returned in the message.
Retry a failed payment manually
Instead of waiting for the automatic retries or the next booking, you can trigger
a new charge attempt yourself with
PUT /bookings/{bookingId}/retry-failed-payment/{recurringPaymentId}, passing the
booking to settle and the recurring payment to charge.
Check availability
Check whether you can sell a product chosen from the map or scanned from a QR
code. The endpoint returns the transport operators you can sell on behalf of. If
a vehicle's operator id (vehicle.system.operator.id in the Mobility API) is in
this list, you can book it with the Shared Mobility API.
Example response
Code
Get a vehicle from a QR code
Retrieve the assetId / vehicleId / bike_id for a scanned QR code before you
start the sales flow.
Example request
Code
Example response
Code
Create a booking
Create a one-stop booking. Set autoStart to true if you want the trip to
start immediately.
You book either a specific vehicle or a vehicle from a station — you must supply
either assetId or stationId. For a station booking you can also narrow the
choice with vehicleTypeId. customerNumber, recurringPaymentId, and
coordinates are always required; pricingPlan and priceAdjustments are
optional.
Example request
Code
Example response
Code
Add a discount to a booking
To apply a discount, add it as a price adjustment when you create the booking. The adjustment is added to both the current amount and the final amount of the booking, so a discount must be a negative amount.
If the final amount is negative after the adjustment, it is set to 0. The price
adjustment itself stays as it was when the booking was created, so take that into
account when you show it to the user.
You can add one or more price adjustments to a booking; their amounts are summed. Each adjustment is always invoiced to you as the client, and you can choose whether to pass the discount on to the user in your app. Always agree with the transport operator on how discounts are handled before you use this.
Example request
Code
Change the booking state
Use this endpoint to change the state of a booking:
Example request
Code
When finishing a trip where a picture of the product is mandatory, also send
fileName, fileType, and fileData:
Code
START— start the trip.PAUSE— pause the trip.RESUME— resume the trip after a pause.START_FINISHING— typically used when the operator wants the user to take a picture of the vehicle. The traveller stops paying for the trip after this step.FINISH— finish the trip. If a picture of the product is mandatory when finishing, setfileName,fileType, andfileData.CANCEL— cancel the trip.
Example response
The updated booking is returned, in the same shape as
Create a booking — with the new state (and, once finished,
arrivalTime, finalAmount, and distanceTravelled set).
Get a customer's active bookings
Get the active bookings for a customerNumber — the bookings that are not in the
FINISHED or CANCELLED state. This is useful for recovering an active booking
when the user reopens your app mid-trip.
The older getBookings endpoint (GET /bookings, with an active query
parameter) is deprecated. Use getActiveBookings instead.
Get a single booking
Get one booking by its bookingId.
Create a support case
Create a support case for a booking or asset — typically when an end user has a
problem during a trip, such as a vehicle that will not unlock, a missing vehicle,
or an accident. The case is routed to the correct transport operator based on the
Operator-Id header. Send both the Entur-Distribution-Channel and Operator-Id
headers with the request.
Request body (SupportRequest):
supportType(required) — the type of issue. One ofBROKEN_DOWN,NOT_AT_LOCATION,MISSING_AFTER_PAUSE,NOT_CLEAN,NOT_AVAILABLE,UNABLE_TO_OPEN,UNABLE_TO_CLOSE,API_TECHNICAL,API_FUNCTIONAL,ACCIDENT, orOTHER.contactInformationEndUser(required) — contact details for the end user; include at least anemailor aphone.- One of
bookingId,stationId, orassetId(required) — what the case is about.bookingIdis the booking UUID. comment(optional) — free-text description of the issue.place(optional) — where the issue occurred.files(optional) — attached files, for example a photo.customerNumber(optional) — the customer the case concerns.
Example request
Code
Example response
Code
Real-time updates over Kafka
This section is for clients — in particular those with mobile ticket-selling apps — who consume messages from our Kafka queue. It covers what the queue is for and the kind of data it carries. Technical details such as integration steps, authentication, and protocols are covered separately.
Purpose of the Kafka queue
The Kafka queue is a distributed messaging system for real-time data exchange between systems and clients. It reliably distributes critical updates and event data so your application can show accurate, up-to-date information to end users.
For ticket-selling apps, the queue delivers real-time updates such as battery status and current trip price directly to users, so you can keep the experience timely and accurate.
Data transmitted
Messages are Avro-serialised objects. They are self-describing and carry the details of an event or update. There are two event types, each published to its own topic:
SharedMobilityBookingEvent— real-time updates for a booking. It wraps atimestampand abookingUpdatedKafkaEventobject.SharedMobilityNotificationEvent— a free-text notification tied to a booking. It wraps atimestampand abookingNotificationKafkaEventobject withschemaVersion,bookingId, andmessage.
In both events the top-level timestamp is a long in milliseconds since
1 January 1970 (UTC).
The key fields of bookingUpdatedKafkaEvent are:
- Identifiers —
bookingId,orderId,customerNumber, and the operator'stransportOperatorBookingId/transportOperatorLegId. - State — one of
NOT_STARTED,PREPARING,IN_USE,PAUSED,FINISHING,FINISHED, orCANCELLED. - Pricing plan (
pricingPlan) — currency, base price, and per-minute pricing for transparent cost estimation. - Pricing (
pricing) —currentAmount,finalAmount, anypriceAdjustments,originalAmount, andsurcharge. - Vehicle and operator —
operator,propulsionType,stateOfCharge,currentRangeKm/currentRangeMeters, andcoordinates. - Metadata —
departureTime,arrivalTime, andcomment.
Why use the Kafka queue
- Real-time information for users — access up-to-date booking and service data so you can notify users of price changes or show the live battery status of a rented vehicle.
- Decentralised processing — consume and process the data independently, so each application focuses on its own needs.
- Reliability and scalability — Kafka is built for high throughput and reliable delivery, even under heavy traffic.
- Standardised data — Avro serialisation means every message follows a standard schema, which reduces compatibility issues.
Example event
Example SharedMobilityBookingEvent
Code
Example SharedMobilityNotificationEvent
Code
Error handling
All error responses follow the same application/problem+json structure:
Code
detail is human-readable text, translated into Norwegian Bokmål (NOB),
Norwegian Nynorsk (NNO), or English (ENG); the language is chosen from the
Accept-Language header in the request. type carries the exception name listed
in the table below.
For backward compatibility the response also still includes the deprecated
aliases exception (= type), error (= title), message (= detail), and
path (= instance). Prefer the canonical fields.
The full list of error messages:
| When | What | Exception | Code | Message |
|---|---|---|---|---|
| Scan QR code | Find operator and vehicle for a QR code | CouldNotFindAssetException | 422 | NOB: Kunne ikke finne kjøretøy. NNO: Kunne ikkje finne køyretøy. ENG: Could not find asset. |
| Create booking | Get operator information | UnknownOperatorException | 400 | NOB: Operatør av kjøretøy ukjent. NNO: Operatør av køyretøy ukjent. ENG: Operator of vehicle unknown. |
| Create booking | Check recurring payment agreement | PaymentAgreementMissingException | 402 | NOB: Kunne ikke starte tur. Vi fant ingen gyldig betalingsmetode. Prøv igjen med et annet kort. NNO: Kunne ikkje starte tur. Vi fann ingen gyldig betalingsmetode. Prøv igjen med eit anna kort. ENG: Could not start trip. We could not find a valid payment method. Try again with a different card. |
| Create booking | Check recurring payment agreement | PaymentAgreementTooOldException | 402 | NOB: Kunne ikke starte tur. Den lagrede betalingsavtalen din er for gammel til å brukes for denne typen reise. Legg inn betalingskortet ditt på nytt for å fortsette. NNO: Kunne ikkje starte tur. Den lagra betalingsavtalen din er for gammal til å brukast for denne typen reise. Legg inn betalingskortet ditt på nytt for å halde fram. ENG: Could not start trip. Your saved payment agreement is too old to be used for this type of trip. Please register your payment card again to continue. |
| Create booking | Create order | CouldNotStartTripException | 500 | NOB: Kunne ikke starte tur. Prøv igjen eller velg et annet kjøretøy. NNO: Kunne ikkje starte tur. Prøv igjen eller vel eit anna køyretøy. ENG: Could not start trip. Try again or choose another vehicle. |
| Create booking | Active booking already exists | ActiveBookingAlreadyExistsException | 409 | NOB: Du har allerede en aktiv tur. Du kan bare ha én aktiv tur om gangen. NNO: Du har allereie ein aktiv tur. Du kan berre ha éin aktiv tur om gongen. ENG: You already have an active trip. You can only have one active trip at a time. |
| Create booking | Retry payment for a previous unpaid trip | CouldNotStartTripMissingPaymentException | 402 | NOB: Vi klarte ikke å trekke deg for den forrige turen din. Utestående beløp er {amount} {currency}. Sjekk at betalingskortet ditt har dekning, eller prøv igjen med et annet kort. NNO: Vi klarte ikkje å trekkje deg for den førre turen din. Uteståande beløp er {amount} {currency}. Sjekk at betalingskortet ditt har dekning, eller prøv igjen med eit anna kort. ENG: We were unable to charge you for your previous trip. The outstanding amount is {amount} {currency}. Please check that your payment card has sufficient funds, or try again with a different card. |
| Create booking | Account blocked by the operator for too many penalty points | MaxPenaltyPointsReachedException | 403 | NOB: Operatøren har utestengt kontoen din fordi en av retningslinjene deres er brutt. For å gjenåpne kontoen må du ta kontakt med operatøren via vårt kontaktskjema. NNO: Operatøren har utestengt kontoen din fordi du har brote ein av retningslinjene deira. For å opne kontoen igjen må du ta kontakt med operatøren via kontaktskjemaet vårt. ENG: The operator has blocked your account because one of their policies has been broken. To reopen your account, you need to contact the operator through our contact form. |
| Create booking | Operator is closed | OperatorClosedException | 409 | NOB: Operatøren er stengt på dette tidspunktet. NNO: Operatøren er stengd på dette tidspunktet. ENG: The operator is closed at this time. |
| Create booking | No available vehicle at station | NoAvailableVehicleAtStationException | 409 | NOB: Fant ingen tilgjengelige kjøretøy på stasjonen. NNO: Fann ingen tilgjengelege køyretøy på stasjonen. ENG: No available vehicle found at the station. |
| Start trip | Change trip state | TompCreateOneStopBookingEventException | 500 | NOB: Kunne ikke endre tilstanden på turen. Leverandøren avslo forsøket. Prøv igjen eller velg et annet kjøretøy. NNO: Kunne ikkje endre tilstanden på turen. Leverandøren avslo forsøket. Prøv igjen eller vel eit anna køyretøy. ENG: Could not change state of trip. The provider refused the attempt. Try again or choose another vehicle. |
| Finish trip | Change trip state | TompCreateOneStopBookingEventException | 500 | NOB: Kunne ikke avslutte tur. Leverandøren avslo forsøket. Prøv igjen eller ta kontakt med {operator}. NNO: Kunne ikkje avslutte tur. Leverandøren avslo forsøket. Prøv igjen eller ta kontakt med {operator}. ENG: Could not end trip. The provider declined the attempt. Try again or contact {operator}. |
| Finish trip | Change trip state | InvalidParkingZoneException | 422 | NOB: Ugyldig parkeringsområde. NNO: Ugyldig parkeringsområde. ENG: Invalid parking zone. |
| Finish trip | Illegal image type | IllegalImageTypeException | 400 | NOB: Ulovlig format på bildet. NNO: Ulovleg format på bildet. ENG: Illegal image type. |
| Change trip state | Illegal event | IllegalEventException | 400 | NOB: Ulovlig hendelse i gjeldende tilstand. NNO: Ulovleg hending i gjeldande tilstand. ENG: Illegal event in current state. |