Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Mobility Service Provider (MSP)

This chapter describes TandemDrive services where you act as an MSP.

Subscription

A subscription represents an agreement between a Customer and a Seller, allowing the Customer to charge their vehicle using the Seller’s services. Each subscription is tied to a specific Subscription Plan, which outlines the financial terms and conditions of the agreement.

Every subscription has a defined start date and time and may optionally include an end date and time when the subscription expires. During the subscription period, one or more tokens (such as charge cards) can be linked to the subscription. Each token can have its own start and/or end validity period.

Token Validity

A token is considered valid (i.e., able to initiate a charge session) when all of the following conditions are met:

  • The token is linked to a subscription, and the token’s validity period is currently active. Additionally, the token link must not be marked as defunct.
  • The linked subscription is also within its validity period and is not marked as defunct.
  • The conditions set in the charge authorization rules must permit the token to initiate a charge session.

For more details, see “validity periods”.

A token can only be associated with one subscription at any given time, regardless of the subscription’s validity. To transfer a token from one subscription to another, the following steps must be taken:

  1. Set a valid_until date on the current token link.

    It’s recommended to choose a future date to avoid a brief period where the token becomes inactive.

  2. Create a new token link for the new subscription, using the same token, and set a valid_from date.

    To ensure a seamless transition, you can set the valid_until date of the old token link and the valid_from date of the new token link to the same value.

For corrections, including retroactive changes, use the /msp-token-subscription/{id}/plan-or-customer-correction endpoint. This handles subscription corrections, including moving tokens and repricing charge sessions, with minimal manual intervention.

Subscription plan

A subscription plan includes a name that should clearly reflect how the plan is marketed to customers.

The publishing period of a subscription plan indicates the intended timeframe for when new subscriptions can be initiated. However, TandemDrive does not enforce this property when creating new subscriptions.

Each subscription plan specifies the rate plan used to calculate the pricing for charge sessions.

Additionally, a subscription plan can include recurring costs, though this is optional.

Subscription plan: use customer reimbursement VAT

An MSP subscription plan includes a property called “Use Customer Reimbursement VAT”, which can be enabled to apply VAT exempt to charge sessions in certain cases. When this property is enabled, the following rules apply:

  1. For every charge sessions which is being priced (on the MSP side) we will check if a matching local EVSE can be found (on the CPO side). When no EVSE was found then the normal VAT determination will be used.

  2. Valid reimbursement arrangements for the identified EVSE are determined based on the charge session’s start date and time.

    • When exactly one arrangement was found, then the “reimbursement VAT” property of the customer of that arrangement will be used to determine the VAT. This property can have the following values:

      • Applies: The normal VAT determination applies.

      • Exempt: The charge session is exempt from VAT.

      • Unknown: The charge session will drop-out as VAT cannot be determined. This case can be solved by changing the “Reimbursement VAT” property of the customer to “Applies” or “Exempt”.

    • When no arrangement was found, then the “reimbursement mandatory” property of the EVSE will determine what happens. If the “reimbursement mandatory” is enabled then the charge session will drop-out. If this property is disabled then the charge session will have the normal VAT determination applied.

    • When multiple arrangements were found, then the charge session will drop-out because this situation is currently not supported by TandemDrive. With multiple arrangements it’s potentially confusing if VAT should be applied or not.

Rate plan

Rate plans define the pricing structure for charge sessions. Each rate plan is tied to a specific currency and can be shared across multiple administrations, as long as these administrations use the same currency. This allows businesses to use a consistent rate setup across administrations.

Key components of a rate plan:

  1. Rates:

    • Specify pricing for various components like energy consumption (kWh), charging time (minutes), or flat fees per session.

  2. Rate Rules:

    • Determine the conditions under which specific rates are applied.
    • Rules are sorted from most specific to most generic.
    • The first matching rule determines the rate used to price a charge session.

Advanced Pricing:

For complex pricing scenarios, scripts can be used to implement custom pricing logic. Scripts can be used to set annotations based on custom conditions, and scripts can be used to calculate subtotals for custom rate components. Contact TandemDrive support for assistance with script development.

Charge Sessions

Incoming charge sessions undergo basic validation checks to ensure data integrity. If a charge session fails these checks, it will be categorized as an Invalid charge session, along with the technical reason for its rejection.

If the session passes validation, it proceeds to the pricing phase. During this process, the system determines the applicable subscription and roaming partner, and the associated rate plan is used to calculate the appropriate rates.

Various pricing checks are applied, which can be customized based on administration settings and roaming partner configurations. If pricing is successful, a “pricing result” is generated for the charge session. If there are issues, the session is flagged in a drop-out case for further review.

Charge sessions can be repriced, where the original pricing result is preserved, and a new one is added. As a result, a single charge session may have multiple pricing results. The pricing result endpoint returns these records in chronological order, based on when each pricing result was created.

Each pricing result is assigned a version number. The first pricing result has version = 1, and subsequent results increment the version number for that specific charge session.

It’s important to note that a “pricing result” and a “charge session” are distinct entities, each with its own unique ID.

Drop-outs

Charge sessions that cannot be priced are stored in Drop-out Cases. Each case groups charge sessions together that failed for the same reason and share similar properties. The system allows for the reprocessing of these charge sessions, with the option to include additional processing instructions.

Resolving a drop-out case may require changes in the setup, such as adjusting a rate plan or creating a roaming agreement. In many instances, retrying the session after making these adjustments is sufficient. In other cases, it may be necessary to include specific instructions, such as bypassing certain checks or discarding the charge session entirely.

For traceability, resolved drop-out cases are retained for some time.

Charge credits

A token subscription can be assigned charge credits, which can be used to pay for charge sessions. These credits can be allocated either as monetary value or energy (kWh). Once credits are assigned, they will automatically be used for all charge sessions until the credits are fully depleted. After that, the customer is charged as usual. Currently, customers cannot be restricted to pay exclusively with credits (prepaid-only is not supported).

The way credits are applied depends on the components of the rate being charged. Some components, like parking fees, can be excluded from credit usage. Each component also specifies how credits are applied when the customer’s credit balance is insufficient to cover the full session.

Monetary credit values are calculated excluding VAT.