Journey planning flow

This page describes the end-to-end flow of a full Platform API integration (integration option 3): user registration, a binding ride request, booking, payment, and live-position updates.

The flow involves four systems—the passenger, your MaaS app, your MaaS backend, and the ioki backend—plus your payment service provider (PSP) for payment.

User data

Your MaaS backend owns user administration: it handles registration and verifies the authenticity of the data. Each user is then created at ioki with:

• a unique identifier—mobile phone number or MaaS ID (mandatory)
• first name and surname
• email (optional)

A mobile phone number is strongly recommended, as it enables communication between the driver and the passenger.

The pricing model is configured in the ioki system, and the price for each ride is reported back to your app.

Registration

There are two options for when the user is created at ioki.

Option 1: Register on the first ride request

The user is created when the passenger makes their first ride request. The first request is non-binding and needs no user.

sequenceDiagram
    autonumber
    participant P as Passenger
    participant MA as MaaS app
    participant MB as MaaS backend
    participant IO as ioki backend
    P->>MA: First non-binding ride request (no user required)
    MA->>IO: Ride inquiry
    IO-->>MA: Ride offer and price
    MA->>MB: Is the required user data available?
    MB-->>MA: Collect any missing data
    MB->>IO: Create user
    P->>MA: Binding ride request
    MA->>IO: Create ride
    IO-->>MA: Ride offer and price

Option 2: Register at app registration

The user is created at ioki when the passenger registers in your app, before any ride request.

sequenceDiagram
    autonumber
    participant P as Passenger
    participant MA as MaaS app
    participant MB as MaaS backend
    participant IO as ioki backend
    P->>MA: Register in the MaaS app
    MA->>MB: Create account
    MB->>IO: Create user
    P->>MA: Binding ride request
    MA->>IO: Create ride
    IO-->>MA: Ride offer and price

Booking, payment, and live-position updates

After a binding offer is returned, the passenger books and pays in your app. Payment runs through your own PSP; the payment process and PSP integration are handled entirely on your side. The contract and fees of the connected PSP are agreed independently between you and the PSP.

sequenceDiagram
    autonumber
    participant P as Passenger
    participant MA as MaaS app
    participant IO as ioki backend
    participant PSP as Payment service provider
    P->>MA: Book the offered ride
    MA->>IO: Create booking
    P->>MA: Pay the displayed price
    MA->>PSP: Process payment
    MA->>IO: Report payment status
    opt Public transport ticket
        IO-->>MA: Passenger receives ticket
    end
    opt Live position
        IO-->>MA: Vehicle position and ride information
    end
    IO->>MA: Report end of ride
    IO->>MA: Report final price
    MA->>PSP: Charge final price
    opt Receipt
        IO-->>P: Send email receipt
    end

Notes on this flow:

• Vouchers: when promo or voucher codes are used, your app must be able to process the codes from the ioki system.
• Tickets: ticket sales are handled through your platform.
• Final price: the final price is reported back to you at the end of the ride, and you charge it to the PSP.
• Receipt: an email with a receipt can optionally be sent to the passenger.

For the concrete Platform API calls behind ride creation, booking, and payment reporting, see the Ride creation flow and External payment.