Insurance Menu

The Insurance product in the panel's left menu contains the following screens:

Viewing the screens requires the insurance view permission; making changes requires the insurance management permission: Provider Connection › Permissions.

General

You manage whether insurance is on, the surfaces where it is offered and what happens after a policy. Changes apply to new offers once saved; issued policies are not affected.

Insurance status

The Insurance on setting is off by default. While it is off, no insurance offer is shown on any surface; your connections and settings are kept and your payments are not affected.

Usage mode

You choose the surfaces where insurance is offered. At least one mode is required while insurance is on.

• On a surface that is not selected, the eligibility list is empty and insurance is not offered.
• If you query eligibility in the API by payment id (paymentIntentId), the API — linked to a Lunixi payment mode must be selected. For a query with basket items, either API mode is enough: Eligibility.

Flows: Checkout Form Path, API Path.

If the policy cannot be issued

The Start the premium refund automatically setting decides what happens when the premium has been collected but the policy definitively cannot be issued. The setting is off by default.

If you collected the premium outside Lunixi, you always refund it through your own channel and report it: Cancellation and Premium Refund.

Policy notification to the buyer

When this setting is on, Lunixi notifies your buyer:

• when a policy is issued, with the document link,
• when a policy cannot be issued and the premium will be refunded,
• when a policy is cancelled.

Rules:

• The setting is off by default. While it is off, you inform your buyer yourself; you can use the webhook events for this.
• The notification is sent through the Email channel to the buyer email address provided in the insurance request. The SMS channel shown on the screen cannot be selected at the moment.
• Notifications are sent only for policies issued through a Live connection. Orders on a test connection do not notify the buyer.

Webhook events

This section shows the insurance events and how many of your endpoints are subscribed to each. With the Environment selector you see your test and live endpoints separately.

• Insurance events are sent to the endpoints you open with the insurance product on the My Account > Webhooks screen. The endpoint's subscriptions decide which events are delivered; no events are selected on this screen.
• Events marked Critical are events with a monetary outcome; if you do not subscribe to them, you miss these outcomes.
• The Not in your plan mark shows that the event is not included in your plan. If your plan does not include webhook delivery in that environment, a warning is shown; events are not delivered even if subscribed.
• Manage webhook endpoints takes you to the My Account > Webhooks screen.

Events and subscription: Webhook Events.

Insurance Types

You manage the insurance types open to you, the connections used for each type, display priority and eligibility rules.

Types and priority

The list shows the types of the products on your insurance connections. If you have no connection yet, no type appears in the list.

• A type is offered only if it is enabled. Types are off by default; enable the type you will offer and save.
• Priority is the display order of the types when more than one type is offered for a basket.
• If an enabled type has no active connection with an enabled product of that type, a warning appears on the row and the type is not offered. Enable the product in the connection details.
• Once saved, enabled types and their order apply to new offers.

Which connection is used first for the same type is decided by the order of the product on the connection, not by this list: Provider order for the same type.

Eligibility rules

You limit the item amounts a type is offered for. A scope without a rule has no amount limit.

• The amount is the insured value of one unit of the item: the item's insuranceValueAmount if present, otherwise its unit price. On the screen you enter the amount in the main currency unit (e.g. 1250.50); at most two decimals are allowed. Field: Basket Items › Insurance fields.
• Only one rule is allowed for the same type, surface and currency. You can write at most 200 rules.
• The minimum cannot be greater than the maximum.
• Save writes the whole list: a rule you remove from the list is deleted.

The Platform rules section shows, read-only, the rules Lunixi applies to all merchants. All platform rules and your rules that match a scope must be met:

• Your rule can only narrow a platform rule. If your range goes beyond the platform range, a warning appears on the row; the overlap of the two ranges applies.
• If the platform turns a type off in a scope, your rule cannot turn it on in that scope.

If a rule is not met, the type is not offered for that item and the eligibility list may be empty: Eligibility › Empty list.

API Usage

Brings together what you need to offer insurance in your own interface through the API. The screen is read-only; the settings are on the General and Provider Connections screens.

The insurance endpoints only accept requests signed with your API key; a panel session is not valid on these endpoints. Details: API Path, Testing.

Requests

You track your insurance requests and the calls your connection makes to the provider. The newest record is on top; records are kept for 60 days. Personal data is shown masked.

List

Filters

• From and To: without dates the last 7 days are shown; the range can be at most 60 days.
• Surface, Direction (Incoming request or Provider call) and Endpoint.
• Request ID: find a request with the requestId value of an error response.
• Insurance order: the order id starting with inso_.
• Payment intent: the payment id (UUID).

Request details

Clicking a row opens the details:

• Request and response (masked): Card data, credentials and personal data are masked before the record is written; unmasked values are not stored.
• Validation result: If the request was rejected by validation, the rejected fields are listed with their field path and reason. If the request ended with an error, the error code and response body show the reason.
• No insurance was offered for this request: Shown when the eligibility list is empty, listing the possible reasons. Checklist: Testing › If insurance is not offered.
• Retry history and provider calls: The attempts of the same request, the incoming request that started a provider call and the calls the request made to the provider through your connection.
• Related insurance order: The order's overall status and four axes, its policies and background operations. Open in Policies opens the order on the Policies screen; Requests of this order filters the list to that order.

Policies

You track your insurance orders and their policies: status, provider connection, collection, document, cancellation and premium refund.

Views and filters

Filters: Insurance type, Policy status, Your order number (at most 128 characters) and Payment intent (UUID).

Refund required

This view lists orders whose refund status is Refund required (REQUIRED), Refund in progress (PENDING) or Refund failed (FAILED). An order whose premium was collected but whose policy definitively could not be issued appears here as Refund required until the refund is started. You start the refund from the order's details and track its result in this list: Premium refund.

If you turned on the automatic refund, the refund of a premium in a Lunixi payment starts by itself: If the policy cannot be issued.

List

Each row in the list is an order: creation time, policy number (with the number of additional policies when there are several), insurance type, premium, provider and who collected the premium, payment intent, your order number, policy and refund status, and the overall status.

Statuses

The panel shows the order's overall status and its four axes with labels. The API values of the labels:

What the statuses mean and how the overall status is derived from the axes: Concepts and Statuses.

Policy details

Clicking a row opens the details:

• Order details: insurance type, premium, provider connection, who collected the premium, payment (Lunixi payment or Paid outside Lunixi), payment intent, your order number, channel, insurance order and quote id, refund time.
• Policies: A separate policy is issued for each insured item; each policy shows its policy number and basket item.
• Actions: cancellation request and premium refund (below).
• Order history: background operations (offer creation, payment notification, policy issuance, cancellation, premium refund), attempt counts, status transitions and who made each transition (System, Buyer, You, Platform team, Provider).

If an action is awaiting its result, the status refreshes automatically while the details are open. Failed attempts are retried automatically; if the result stays unknown, the operation goes to platform team review, automatic retries stop and an information note appears in the details. Platform team actions are also listed in the history.

Policy document

Download the document with Download PDF on the policy.

• Documents are not stored by Lunixi; each download is fetched from the provider.
• The document can be downloaded once the policy is issued. The document of a cancelled policy cannot be downloaded.
• If the provider cannot deliver the document at that moment, a warning appears. Your policy remains valid; try again shortly.

The API equivalent: Policy Document.

Cancellation request

Request cancellation opens a cancellation request with the provider for every issued policy of the order.

• It is available only for an issued policy (policy Issued or Partially issued).
• The provider settles the request and it cannot be undone. Until the result is final, the policy shows Cancellation in progress.
• Cancelling does not refund the premium. If needed, start a premium refund separately after the cancellation.

Premium refund

Start premium refund is available only when you collected the premium, the premium was collected and no policy is in force. Otherwise the reason is shown instead of the button:

The refund follows how the premium was collected:

• Premium collected with a Lunixi payment: The premium amount is returned as a partial refund of the buyer's Lunixi payment. The result comes from the bank.
• Premium collected outside Lunixi: You refund it through your own channel, then report it with Your refund id (1-128 characters, no spaces) and Refunded at. The refund time is sent in your browser's time zone; it cannot be before the payment or in the future.

Starting the refund does not mean it is complete. Track the result on the Refund axis: Refund in progress, Refunded or Refund failed. If the refund failed, review the error code and try again with Restart the refund.

The API equivalent: Cancellation and Premium Refund.

Reconciliation

You get a policy and premium report per connection for reconciling with your provider. The figures are read from the order records.

Period and filters

• The From and To days are required. The period is cut by order creation day in Istanbul time; the end day is included; at most 366 days.
• Optional filters: Provider connection, Insurance type, Currency (three-letter ISO code, e.g. TRY).
• Statuses are as of the moment you run the report.

Summary

The summary is shown as a separate card per connection, currency and premium collector. Each card has a count and a premium total:

Collection and refund measures are per order; policy measures are per policy.

CSV export

Download CSV downloads the report rows for the selected period and filters.

• Each policy is one row. Order columns repeat on every policy row of the order; an order without a policy yet is a single row with empty policy columns.
• Amounts are in minor units. For the order total, sum orderPremiumAmountMinor once per orderId; for the policy total, sum policyPremiumAmountMinor.
• A file holds at most 20,000 orders. When the limit is reached a warning appears; use Download the rest for the remaining orders.
• If the export is interrupted, a warning appears and the downloaded file is incomplete; download it again.

The status columns hold the API values in the Statuses table.

Related

• Provider Connection: connection, products and order
• Form Settings > Insurance: where insurance appears in the Checkout Form
• Concepts and Statuses: order statuses
• Webhook Events: insurance events