Insurance
Insurance lets your buyer add cover to the product they are purchasing, in the same checkout. For example, if you sell tickets, your buyer can add ticket cancellation insurance to the ticket. You can also sell insurance that is not tied to a product (such as personal accident) on its own.
The insurance is offered by the insurance provider you have an agreement with. Lunixi provides the quote, order, policy and tracking infrastructure and works according to the agreement between you and your provider.
Two ways to use insurance
You can offer insurance together with a Lunixi payment, or on its own without a Lunixi payment. Pick one based on how you take the payment.
| With a Lunixi payment | Insurance only | |
|---|---|---|
| When | You take the payment with Lunixi. | You take the payment outside Lunixi, or you sell insurance only. |
| Required on your account | The payment product and the insurance product | The insurance product only |
| How you integrate | Checkout Form: you turn insurance on in the panel and the buyer selects it in the form. Or through the API: you get the quote and the order from the API and add the premium to your payment's basket as a separate item. | Through the API only: you get the quote and the order from the API, then collect the premium through your own channel and report it, or have your provider charge it. |
| Premium | Charged in the same transaction as the product. | Charged through your channel or by the provider's charge. |
Payments without insurance are not affected in either way. If the basket carries no insurance details, no insurance is offered and the payment proceeds as usual.
Where to start
| What you want to do | Page |
|---|---|
| Integrate insurance through the API only, without a Lunixi payment | Insurance-Only Integration |
| Offer insurance in the Lunixi payment form | Checkout Form Path |
| Offer insurance in your own form with a Lunixi payment | API Path |
| See every endpoint in one table | Endpoint Reference |
| Connect your provider and enable products | Provider Connection |
| Learn the fields of the insurance types | Insurance Types and Schemas |
| Send the quote details with the basket | Basket details and pre-fill data |
| Try insurance | Testing |
How it works
Connect your provider
In the Lunixi panel, you connect the provider you have an agreement with, from the providers listed in the catalog. In the connection, you specify which insurance products you offer and who collects the premium.
Insurance is resolved from the basket
Which insurance is offered is resolved from the insurance details in your basket items; insurance that is not tied to a product is offered without a basket item. If no insurance is eligible, the buyer does not see insurance.
The buyer selects a quote
The buyer sees your provider's quote: premium, coverage summary and terms. Insurance is never preselected; the buyer's explicit consent is required.
The premium is collected
The premium is collected according to your collection method (see below).
The policy is issued
The policy is issued after the premium is collected. You follow the outcome through webhooks and in the panel.
Basket details and pre-fill data
When you send the product to be insured as a basket item, you add the insurance fields too. All fields and their rules: Basket Items › Insurance fields.
| Field | What it carries |
|---|---|
insuranceCategory, insuranceTypes | The item's category and the insurance types to offer. |
insuranceValueAmount | The insured value of one unit. |
insuranceContext | Non-personal details: trip, device model, travel dates and so on. |
insuranceData | The other details the quote needs, personal data included: insured person, IMEI, booking code, plate and so on. |
With insuranceContext and insuranceData you provide the information the quote needs in advance; the buyer is not asked for the same details again. Depending on how much you send:
| What you send | In the Checkout Form | In the API |
|---|---|---|
| Nothing | As today: the buyer fills in the details in the form. | You send all fields in the quote request. |
| Part of the details | The fields you sent arrive filled in; personal ones are shown masked. The buyer fills in only the missing ones. | The Eligibility response shows which fields were provided; you send only the missing ones in the quote request. |
| Everything the quote needs | If the policy fields arrived too, the quote is obtained on its own when the form opens and shown with its price in the payment step. If only the quote fields arrived, the buyer fills in the policy fields and gets a quote. | The eligibility response returns quoteReady: true; you can get the quote without sending further fields. |
- Insurance is never added on its own. Even when the quote is ready, the buyer accepts the insurance and its terms themselves.
- Pre-fill data does not change your payment. If you do not send it, payment and insurance work as they do today.
- If an item's pre-fill data does not fit the type's rules, the payment does not stop; that item's pre-fill data is not used and the details are asked of the buyer.
Behaviour in the form: Behaviour Rules › Pre-filled details. In the API: Quote › Quote with pre-fill data.
Personal data
insuranceData carries personal data. Lunixi handles it as follows:
| Topic | Behaviour |
|---|---|
| Where it goes | It is used only for insurance and passed to the provider of your connection when a quote is obtained. It is not passed to the payment or to your payment provider. |
| How it is stored | Pre-fill data you send with the payment request (POST /payments/intents) is stored encrypted. Pre-fill data you send in insurance API requests (context.items) is not stored separately; it is used only in that request. |
| When it is deleted | Pre-fill data you send with the payment request is deleted within at most one hour after the payment is 24 hours old, whether or not the payment was completed. |
| Once a quote is obtained | The details used for the quote are kept encrypted inside the quote, like the details the buyer enters in the form; the policy is issued with these details. |
| Where it appears | In the eligibility response personal values are masked (***). In request logs the insuranceData field of the payment request is hidden entirely, and personal values in insurance requests are masked. Error responses carry only the field path. |
Provider connection and agreement
- The insurance agreement is between you and your provider. A provider connection introduces your own agreement with the provider to Lunixi; you enter your connection details in the panel.
- Lunixi does not collect the premium in its own name and does not transfer money to the provider.
- Your integration is not tied to a provider. Insurance types, fields, statuses and error codes are the same whichever provider you work with. When you change providers, you change your connection in the panel; your code does not change.
- You can see which of your connections issued a policy in responses and in the panel. You reconcile with your provider using this information; report: Reconciliation Report.
Who collects the premium
Your agreement with your provider determines who collects the premium. You specify this for each insurance product you enable in your connection; Lunixi does not choose on your behalf.
You collect the premium. The premium is part of your sale:
- If you take the payment with Lunixi, the premium is added to the payment as a separate item and the buyer pays for the product and the insurance in a single charge. The premium appears as a separate item in your payment record.
- If you take the payment outside Lunixi, you tell the API that the payment was received; Lunixi forwards the notification to your provider through your connection: Insurance-Only Integration.
You transfer the premium you collected to your provider according to your agreement. If a premium refund is needed, it is also made from your payment.
The provider collects the premium. The premium is not added to your payment; your provider takes it with a separate charge:
- If you have a payment of your own, it is taken first. Then the premium is charged, depending on the provider's product, to the buyer's card or on the provider's payment page. Only PCI-DSS certified merchants may send card details.
- If the premium cannot be charged, your payment stays valid.
- This method is available through the API only; it works both with a Lunixi payment and without one: Provider Collection.
You can offer an insurance product only if one of the collection methods the provider supports for that product matches your agreement.