Payment for rides

Payment for rides is a provider feature that refers to the process of handling payments for rides. If activated, users can select a payment method in ioki Passenger App or in ioki Web Booking.

In the provider settings, you can define the accepted payment methods for all purchasable objects, such as rides, service credits, and personal discounts.

By default, the options Cash payment and Service Credits are available and can be activated. Additional payment methods such as credit cards, SEPA direct debit, PayPal, Apple Pay, or Google Pay can be enabled through an external payment service provider (PSP). Provider-specific Stripe and LogPay settings are managed on dedicated provider pages in Control Center: Manage Stripe account and LogPay credentials.

Cash payment can only be used for rides, while service credits can only be purchased with a digital payment method provided by a PSP or in other forms offered by the provider.

It’s also possible to restrict one or more of the available payment methods to administrators only.

Payment must be enabled within the section Payment in the management settings of the corresponding product.

Payment states

Each ride has a payment state, which can have the following values.

  • payment not initiated. Payment not requested (ride probably not finished).
  • payment pending. Payment is being processed.
  • payment succeeded. Payment was successful.
  • payment failed. Payment failed.
  • payment refunded. Payment was successful, but has been fully refunded to the passenger.
  • payment partially refunded. Payment was successful, but part of it has been refunded to the passenger.
  • payment forfeited. Payment failed and marked as not retrievable.
  • payment manually retrieved. Payment was manually retrieved (that is, bank transfer).
  • no payment. No payment.

The payment states payment forfeited and payment manually retrieved can be set only by an administrator when handling failed payments.

A ride payment that ends in payment failed stays open as an outstanding claim, because the ride is a service that was provided and is still expected to be paid. The same applies to a cancellation fee or a no-show fee: if the fee cannot be settled, it also becomes an outstanding payment failed and is handled through failed payments, not only ride fares. An outstanding balance can be settled in one of the following ways:

  • The passenger settles it in ioki Passenger App by choosing a digital payment method, where the provider accepts one. See Pay an outstanding balance.
  • An administrator handles it in Control Center by setting it to payment manually retrieved or payment forfeited.

Only ride payments, including their fees, can end in payment failed and be recovered this way. Payments for tips, service credits, and personal discounts are settled at the moment of purchase. If one of these payments fails, the whole purchase fails and is not kept as an outstanding balance, so there is no failed-payment recovery for them.

The following diagram shows the payment states:

flowchart TD
    classDef iokiBerry color:#d11064,stroke:#d11064,stroke-width:2px
    classDef iokiGrey stroke-width:2px

    A[Ride created]:::iokiBerry --> B[no payment]:::iokiGrey
    A[Ride created] --> C[payment not initiated]:::iokiGrey
    C[payment not initiated] --> D[payment pending]:::iokiGrey
    D[payment pending] --> E[payment failed]:::iokiGrey
    D[payment pending] --> F[payment succeeded]:::iokiGrey
    E[payment failed] -.-> G[payment forfeited]:::iokiGrey
    E[payment failed] -.-> H[payment manually retrieved]:::iokiGrey
    F[payment succeeded] -.-> I[payment refunded]:::iokiGrey
    F[payment succeeded] -.-> J[payment partially refunded]:::iokiGrey

The process of charging is handled differently for the different payment options.

Cash payment

To offer cash, a Super Admin selects Cash payment under Accepted payment methods for rides in the provider payment settings. Cash is available for rides only, and no payment service provider is required for it.

Cash payment is handled differently depending on the version of ioki Vehicle App.

ioki Vehicle App

Before v1.13.1

  • The payment state is initialized as payment not initiated when the ride is offered.
  • The state remains the same until the ride is dropped off.
  • The driver can submit whether the payment was successful or not, setting the state to payment succeeded or payment failed.
  • If the fare for the ride is zero, the state is set to no payment.

ioki Vehicle App

v1.13.1 and newer

  • The payment state is initialized as payment not initiated when the ride is offered.
  • In contrast to all other offered payment methods, cash payment is handled upfront when the passenger is picked up.
  • Through ioki Vehicle App, the driver reports whether the payment is successful or cancels the ride if the passenger doesn’t have enough cash. If payment is successful, the driver confirms that the user is picked up, and the payment state is set to payment succeeded. If the passenger doesn’t have enough cash to pay for the ride, the driver cancels the ride with the cancellation reason Passenger did not have cash, which sets the state to no payment.
  • If the fare for the ride is zero, the state is set to no payment.

Because cash payment is handled upfront, using a final price adapter that changes the fare after the ride is finished is not recommended. This setting also triggers a warning for the operator.

Cancellation and no-show fees with cash

Because cash is collected in person at pickup, a fee that arises from a canceled ride cannot be collected in cash: the passenger is not in the vehicle when a cancellation fee or a no-show fee is due. When a ride paid with cash, or with card in the vehicle, is canceled and a cancellation fee or no-show fee applies, no in-vehicle collection is attempted and the fee becomes an outstanding payment failed instead. It is then handled like any other failed payment: the passenger can settle it in ioki Passenger App with a digital payment method where the provider accepts one, or an administrator can set it to payment manually retrieved or payment forfeited.

Service credits

If a passenger chooses to pay with service credits, the fare is reserved when the ride is booked, that is, when it reaches the state passenger accepted and payment is initiated with the state payment pending. The amount is then charged after the ride is over, that is, when the state becomes dropped off or if the ride is cancelled. The fare, cancellation fee, or no-show fee is then charged against the reserved service credits, as applicable. If no payment is due, for example because the driver does not accept the ride, the reserved credits are released.

External payment

If the ride is booked from another system and payment is handled there, the payment method external is assigned. ioki Platform assumes that external payments have been processed successfully and does not track them further. This payment method is assigned only at the time of booking.

For rides, this payment method is assigned only at the time of booking. The option to use external payment can be turned on or off by setting a flag on the corresponding client. This ensures that ioki internal apps still have to send valid payment methods, while external apps can be allowed to use external payment.

For external payments, receipts are not created or sent to users.

External payment can run alongside the product’s internal payment setup in the same product. This means an external client can use external payment while internal apps continue to use the configured payment service provider. However, LogPay and Stripe cannot be used side by side in the same product.

Payment service provider

When a ride is created, ioki Platform saves all payment-related information, including the fare amount and the payment method chosen by the user. The initial payment state is payment not initiated.

For LogPay, ioki Platform also checks whether a user’s LogPay account is locked as soon as the booking is created. This is because LogPay stores information on clients across applications. The check prevents users with too many failed payments in other applications from booking a ride.

If a LogPay customer has too many failed payments in another application and attempts to book a ride, their account is locked and the ride is canceled immediately.

After the ride is dropped off or canceled, ioki Platform initiates a payment intent by connecting to the corresponding PSP and sets the state to payment pending. The PSP responds with either payment succeeded or payment failed. Failed payments are listed in the failed payments section in Control Center and can be handled automatically via automated failed payment handling.

For PayPal payments processed via LogPay, fare reservations are made based on the ride’s timing:

  • If the ride occurs within 24 hours of booking, the reservation is made at the time of booking. If it fails, the booking is rejected, and the user must provide an alternative payment method.
  • If the ride occurs more than 24 hours after booking, the reservation is scheduled as a background job, triggered 24 hours before the planned drop-off time. If the reservation fails, the ride is canceled with the cancellation reason payment reservation failed.

Refunds

Refunds can be made for payments processed through payment service providers, but not for service credits or cash payments.

To refund the fare of a ride, go to the detailed view of the corresponding ride and navigate to the Payments section. If the ride is refundable, select Refund payment, provide a reason, and start the refund process. By entering an amount, it is possible to refund rides partially.

Refunds cannot be higher than the calculated final fare.

Refunds are possible only for succeeded payments in Stripe and confirmed payments in LogPay. Refunds have states: for LogPay, they are simply succeeded or failed. A Stripe refund is initially marked as pending and is later updated, after calling the Stripe API, to succeeded, failed, or cancelled based on the response from Stripe.

Once a refund has been successfully processed, the user receives a receipt via email. Moreover, Control Center displays it as a message and lists it as a refund under Payments.

Permissions: create_refunds