Entur Developer
Shared mobility

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 assetId to create a booking.
  • Scan a QR code. First call the QR endpoint to retrieve the assetId / vehicleId / bike_id from 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:

  1. We retry the charge up to three times, about one minute between each attempt.
  2. 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).
  3. 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
JSONCode
{ "operatorIds": ["ENT:Operator:ENT"] }

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
GET /qr-code?qrCodeUrl=https://some-operator.com/vehicleCode%3D1234ABCD&longitude=10.7532&latitude=59.9115
Example response
JSONCode
{ "operator": { "id": "ENT:Operator:ENT", "name": "Entur AS" }, "id": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000", "stationId": null, "formFactor": "SCOOTER", "stateOfCharge": 95, "currentRangeKm": 25, "vehicleCode": "1234ABCD", "coordinates": { "longitude": 10.7532, "latitude": 59.9115 }, "propulsionType": "ELECTRIC" }

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
JSONCode
{ "customerNumber": 123456, "recurringPaymentId": 123456, "coordinates": { "longitude": 0, "latitude": 0, "altitude": 0 }, "assetId": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000", "autoStart": true }
Example response
JSONCode
{ "bookingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "transportOperatorBookingId": "TST:Booking:ea110245-131d-3109-ba91-b5bd57701934", "transportOperatorLegId": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "IN_USE", "orderId": "ABCD1234", "pricingPlan": { "currency": "NOK", "price": 10, "perMinPricing": [{ "start": 0, "end": 60, "interval": 1, "rate": 1.5 }] }, "departureTime": "2024-08-12T10:31:17.878Z", "arrivalTime": null, "distanceTravelled": 0, "pricing": { "currentAmount": 100.0, "originalAmount": 100.0, "finalAmount": null, "priceAdjustments": [], "paymentStatus": "UNPAID", "surcharge": null }, "asset": { "operator": { "id": "ENT:Operator:ENT", "name": "Entur AS" }, "id": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000", "formFactor": "SCOOTER", "stateOfCharge": 50, "currentRangeKm": 20, "vehicleCode": "ABCD1234", "coordinates": { "longitude": 10.7532, "latitude": 59.9115 }, "propulsionType": "ELECTRIC" }, "comment": null }

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
JSONCode
{ "customerNumber": 123456, "recurringPaymentId": 123456, "coordinates": { "longitude": 0, "latitude": 0, "altitude": 0 }, "assetId": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000", "priceAdjustments": [ { "description": "20.00 NOK off", "amount": -20.00 } ] }

Change the booking state

Use this endpoint to change the state of a booking:

Example request
JSONCode
{ "event": "START" }

When finishing a trip where a picture of the product is mandatory, also send fileName, fileType, and fileData:

JSONCode
{ "event": "FINISH", "fileName": "parking.jpg", "fileType": "image/jpeg", "fileData": "<base64-encoded image>" }
  • 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, set fileName, fileType, and fileData.
  • 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.

Example response

An array of booking objects, each in the same shape as Create a booking:

JSONCode
[ { "bookingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "transportOperatorBookingId": "TST:Booking:ea110245-131d-3109-ba91-b5bd57701934", "transportOperatorLegId": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "IN_USE", "orderId": "ABCD1234", "pricing": { "currentAmount": 100.0, "originalAmount": 100.0, "finalAmount": null, "priceAdjustments": [], "paymentStatus": "UNPAID", "surcharge": null }, "asset": { "operator": { "id": "ENT:Operator:ENT", "name": "Entur AS" }, "id": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000", "formFactor": "SCOOTER", "stateOfCharge": 50 } } ]

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.

Example response

A single booking object, in the same shape as Create a booking:

JSONCode
{ "bookingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "transportOperatorBookingId": "TST:Booking:ea110245-131d-3109-ba91-b5bd57701934", "transportOperatorLegId": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "FINISHED", "orderId": "ABCD1234", "pricingPlan": { "currency": "NOK", "price": 10, "perMinPricing": [{ "start": 0, "end": 60, "interval": 1, "rate": 1.5 }] }, "departureTime": "2024-08-12T10:31:17.878Z", "arrivalTime": "2024-08-12T10:49:21.512Z", "distanceTravelled": 2400, "pricing": { "currentAmount": 127.0, "originalAmount": 127.0, "finalAmount": 127.0, "priceAdjustments": [], "paymentStatus": "PAID", "surcharge": null }, "asset": { "operator": { "id": "ENT:Operator:ENT", "name": "Entur AS" }, "id": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000", "formFactor": "SCOOTER", "stateOfCharge": 44, "currentRangeKm": 18, "vehicleCode": "ABCD1234", "coordinates": { "longitude": 10.7612, "latitude": 59.9201 }, "propulsionType": "ELECTRIC" }, "comment": null }

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 of BROKEN_DOWN, NOT_AT_LOCATION, MISSING_AFTER_PAUSE, NOT_CLEAN, NOT_AVAILABLE, UNABLE_TO_OPEN, UNABLE_TO_CLOSE, API_TECHNICAL, API_FUNCTIONAL, ACCIDENT, or OTHER.
  • contactInformationEndUser (required) — contact details for the end user; include at least an email or a phone.
  • One of bookingId, stationId, or assetId (required) — what the case is about. bookingId is 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
JSONCode
{ "bookingId": "89ea38c3-af79-4892-bd21-8bb077b4609a", "supportType": "UNABLE_TO_OPEN", "contactInformationEndUser": { "email": "user@example.com", "phone": "+4799999999" }, "comment": "Unable to unlock the vehicle. The app returns an error.", "place": { "name": "Oslo Central Station", "coordinates": { "longitude": 10.7532, "latitude": 59.9115 } }, "customerNumber": 123456 }
Example response
JSONCode
{ "status": "RECEIVED", "timeToResolution": 30 }

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 a timestamp and a bookingUpdatedKafkaEvent object.
  • SharedMobilityNotificationEvent — a free-text notification tied to a booking. It wraps a timestamp and a bookingNotificationKafkaEvent object with schemaVersion, bookingId, and message.

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's transportOperatorBookingId / transportOperatorLegId.
  • State — one of NOT_STARTED, PREPARING, IN_USE, PAUSED, FINISHING, FINISHED, or CANCELLED.
  • Pricing plan (pricingPlan) — currency, base price, and per-minute pricing for transparent cost estimation.
  • Pricing (pricing) — currentAmount, finalAmount, any priceAdjustments, originalAmount, and surcharge.
  • Vehicle and operator — operator, propulsionType, stateOfCharge, currentRangeKm / currentRangeMeters, and coordinates.
  • Metadata — departureTime, arrivalTime, and comment.

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
JSONCode
{ "timestamp": 1726748821000, "bookingUpdatedKafkaEvent": { "schemaVersion": "1.0", "bookingId": "123e4567-e89b-12d3-a456-426614174000", "customerNumber": 123456, "state": "IN_USE", "orderId": "ORD123456", "pricingPlan": { "currency": "NOK", "price": 150.0, "perMinPricing": [ { "start": 0, "end": 60, "interval": 15, "rate": 2.5 } ] }, "departureTime": 1726748821000, "arrivalTime": 1726750800000, "operator": { "id": "op123", "name": "SharedMobility Operator" }, "propulsionType": "ELECTRIC", "stateOfCharge": 80, "currentRangeKm": 120, "currentRangeMeters": 120000, "coordinates": { "longitude": 10.7532, "latitude": 59.9115, "altitude": 0 }, "pricing": { "currentAmount": 100.0, "finalAmount": 150.0, "originalAmount": 150.0, "priceAdjustments": [ { "amount": -20.0, "description": "20.00 NOK off" } ], "surcharge": null }, "transportOperatorBookingId": "op-booking-123", "transportOperatorLegId": "op-leg-123", "comment": "Real-time booking update for the user." } }
Example SharedMobilityNotificationEvent
JSONCode
{ "timestamp": 1726748821000, "bookingNotificationKafkaEvent": { "schemaVersion": "1.0", "bookingId": "123e4567-e89b-12d3-a456-426614174000", "message": "Your trip is about to reach the edge of the parking zone." } }

Error handling

All error responses follow the same application/problem+json structure:

JSONCode
{ "type": "ActiveBookingAlreadyExistsException", "status": 409, "title": "Conflict", "detail": "You already have an active trip. You can only have one active trip at a time.", "instance": "/bookings/one-stop", "timestamp": "2024-09-17T08:49:33.814422231+02:00" }

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:

WhenWhatExceptionCodeMessage
Scan QR codeFind operator and vehicle for a QR codeCouldNotFindAssetException422NOB: Kunne ikke finne kjøretøy.
NNO: Kunne ikkje finne køyretøy.
ENG: Could not find asset.
Create bookingGet operator informationUnknownOperatorException400NOB: Operatør av kjøretøy ukjent.
NNO: Operatør av køyretøy ukjent.
ENG: Operator of vehicle unknown.
Create bookingCheck recurring payment agreementPaymentAgreementMissingException402NOB: 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 bookingCheck recurring payment agreementPaymentAgreementTooOldException402NOB: 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 bookingCreate orderCouldNotStartTripException500NOB: 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 bookingActive booking already existsActiveBookingAlreadyExistsException409NOB: 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 bookingRetry payment for a previous unpaid tripCouldNotStartTripMissingPaymentException402NOB: 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 bookingAccount blocked by the operator for too many penalty pointsMaxPenaltyPointsReachedException403NOB: 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 bookingOperator is closedOperatorClosedException409NOB: Operatøren er stengt på dette tidspunktet.
NNO: Operatøren er stengd på dette tidspunktet.
ENG: The operator is closed at this time.
Create bookingNo available vehicle at stationNoAvailableVehicleAtStationException409NOB: 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 tripChange trip stateTompCreateOneStopBookingEventException500NOB: 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 tripChange trip stateTompCreateOneStopBookingEventException500NOB: 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 tripChange trip stateInvalidParkingZoneException422NOB: Ugyldig parkeringsområde.
NNO: Ugyldig parkeringsområde.
ENG: Invalid parking zone.
Finish tripIllegal image typeIllegalImageTypeException400NOB: Ulovlig format på bildet.
NNO: Ulovleg format på bildet.
ENG: Illegal image type.
Change trip stateIllegal eventIllegalEventException400NOB: Ulovlig hendelse i gjeldende tilstand.
NNO: Ulovleg hending i gjeldande tilstand.
ENG: Illegal event in current state.
Last modified on
Did you find what you were looking for?