# 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.

:::note
`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](/docs/open-services/mobility). 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](/docs/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](/apis/payment-partner/recurring-payments) 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](#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.

::endpoint[shared-mobility/getAvailability]

<details>
<summary>Example response</summary>

```json
{
  "operatorIds": ["ENT:Operator:ENT"]
}
```

</details>

## Get a vehicle from a QR code

Retrieve the `assetId` / `vehicleId` / `bike_id` for a scanned QR code before you
start the sales flow.

::endpoint[shared-mobility/getQrCodeInfo]


<details>
<summary>Example request</summary>

```http
GET /qr-code?qrCodeUrl=https://some-operator.com/vehicleCode%3D1234ABCD&longitude=10.7532&latitude=59.9115
```

</details>

<details>
<summary>Example response</summary>

```json
{
  "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"
}
```

</details>

## 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.

::endpoint[shared-mobility/createOneStopBooking]

<details>
<summary>Example request</summary>

```json
{
  "customerNumber": 123456,
  "recurringPaymentId": 123456,
  "coordinates": { "longitude": 0, "latitude": 0, "altitude": 0 },
  "assetId": "ENT:Vehicle:00000000-abcd-abcd-abcd-00000000",
  "autoStart": true
}
```

</details>

<details>
<summary>Example response</summary>

```json
{
  "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
}
```

</details>

### 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.

<details>
<summary>Example request</summary>

```json
{
  "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
    }
  ]
}
```

</details>

## Change the booking state

Use this endpoint to change the state of a booking:

::endpoint[shared-mobility/oneStopEvent]

<details>
<summary>Example request</summary>

```json
{
  "event": "START"
}
```

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

```json
{
  "event": "FINISH",
  "fileName": "parking.jpg",
  "fileType": "image/jpeg",
  "fileData": "<base64-encoded image>"
}
```

</details>

- `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.

<details>
<summary>Example response</summary>

The updated booking is returned, in the same shape as
[Create a booking](#create-a-booking) — with the new `state` (and, once finished,
`arrivalTime`, `finalAmount`, and `distanceTravelled` set).

</details>

## 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.

::endpoint[shared-mobility/getActiveBookings]

<details>
<summary>Example response</summary>

An array of booking objects, each in the same shape as
[Create a booking](#create-a-booking):

```json
[
  {
    "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 }
  }
]
```

</details>

:::note
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`.

::endpoint[shared-mobility/getBooking]

<details>
<summary>Example response</summary>

A single booking object, in the same shape as
[Create a booking](#create-a-booking):

```json
{
  "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
}
```

</details>

## 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.

::endpoint[shared-mobility/createSupportCase]

**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.

<details>
<summary>Example request</summary>

```json
{
  "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
}
```

</details>

<details>
<summary>Example response</summary>

```json
{
  "status": "RECEIVED",
  "timeToResolution": 30
}
```

</details>

## 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

<details>
<summary>Example SharedMobilityBookingEvent</summary>

```json
{
  "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."
  }
}
```

</details>

<details>
<summary>Example SharedMobilityNotificationEvent</summary>

```json
{
  "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."
  }
}
```

</details>

## Error handling

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

```json
{
  "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:

| 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. <br/> **NNO**: Kunne ikkje finne køyretøy. <br/> **ENG**: Could not find asset. |
| Create booking | Get operator information | `UnknownOperatorException` | 400 | **NOB**: Operatør av kjøretøy ukjent. <br/> **NNO**: Operatør av køyretøy ukjent. <br/> **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. <br/> **NNO**: Kunne ikkje starte tur. Vi fann ingen gyldig betalingsmetode. Prøv igjen med eit anna kort. <br/> **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. <br/> **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. <br/> **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. <br/> **NNO**: Kunne ikkje starte tur. Prøv igjen eller vel eit anna køyretøy. <br/> **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. <br/> **NNO**: Du har allereie ein aktiv tur. Du kan berre ha éin aktiv tur om gongen. <br/> **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. <br/> **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. <br/> **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. <br/> **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. <br/> **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. <br/> **NNO**: Operatøren er stengd på dette tidspunktet. <br/> **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. <br/> **NNO**: Fann ingen tilgjengelege køyretøy på stasjonen. <br/> **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. <br/> **NNO**: Kunne ikkje endre tilstanden på turen. Leverandøren avslo forsøket. Prøv igjen eller vel eit anna køyretøy. <br/> **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}. <br/> **NNO**: Kunne ikkje avslutte tur. Leverandøren avslo forsøket. Prøv igjen eller ta kontakt med {operator}. <br/> **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. <br/> **NNO**: Ugyldig parkeringsområde. <br/> **ENG**: Invalid parking zone. |
| Finish trip | Illegal image type | `IllegalImageTypeException` | 400 | **NOB**: Ulovlig format på bildet. <br/> **NNO**: Ulovleg format på bildet. <br/> **ENG**: Illegal image type. |
| Change trip state | Illegal event | `IllegalEventException` | 400 | **NOB**: Ulovlig hendelse i gjeldende tilstand. <br/> **NNO**: Ulovleg hending i gjeldande tilstand. <br/> **ENG**: Illegal event in current state. |
