Concepts and Statuses
The concepts and statuses on this page are the same on the Checkout Form path and on the API path.
Core concepts
| Concept | Meaning |
|---|---|
| Insurance type | Lunixi's provider-independent insurance code. Example: TICKET_CANCELLATION (ticket cancellation). A published type code never changes. Each type has a schema; the schema version is given by schemaVersion. |
| Option | The concrete insurance offered to the buyer in a quote: the provider's name and logo, the premium, a coverage summary and the terms. |
| Quote | The price given for a specific basket and insured details. A quote has a validity period. If the basket changes, the quote becomes invalid and a new quote is obtained. |
| Selection | The quote the buyer selected in the Checkout Form and the consent they gave. The selection is validated again when the payment is submitted. Insurance is never preselected. On the API path, you create the order directly from the quote. |
| Order | The purchase of the selected quote. Premium collection, policy, refund and document processes are tracked on the order. If you take the payment with Lunixi, the ID of the premium item is the order ID. |
| Policy | The insurance issued by the provider. Insurance is per unit: each unit in the basket is insured separately, so an order can have more than one policy. The policy number is the number printed on the policy document. |
| Premium | The amount the buyer pays for the insurance. |
| Provider connection | The representation in Lunixi of your agreement with your provider. You decide which provider is used through your connections, not through your requests. |
| Collection method | Who collects the premium. Your agreement with your provider determines it; you specify it for each product in your connection. |
IDs
Lunixi IDs are prefixed and opaque. The prefix shows the type of the ID.
| Prefix | ID | Format |
|---|---|---|
insq_ | Quote | insq_ + 32 hexadecimal digits |
inss_ | Selection | inss_ + 32 hexadecimal digits |
inso_ | Order | inso_ + 32 hexadecimal digits |
insp_ | Policy | insp_ + 32 hexadecimal digits |
inspay_ | Provider premium charge attempt | inspay_ + 32 hexadecimal digits |
insclm_ | Claim | insclm_ + 32 hexadecimal digits |
insl_ | Lead | insl_ + 32 hexadecimal digits |
- Store IDs as they are and send them back unchanged; do not attach meaning to their contents.
- An ID of one type is not accepted where another type is expected. For example, an order ID sent where a quote ID is expected is treated like an ID that does not exist.
- Responses contain only Lunixi IDs. The provider's own references are not included in responses.
Order statuses
The status of an order is tracked on four independent axes: collection, policy, refund and document. The axes do not erase each other's information. For example, if the premium was collected but the policy could not be issued, collection stays COLLECTED, policy FAILED_FINAL and refund REQUIRED.
Collection
| Value | Meaning |
|---|---|
NOT_STARTED | Collection has not started yet. |
PENDING | Collection is in progress. |
ACTION_REQUIRED | The buyer needs to take a step to complete the collection. |
COLLECTED | The premium was collected. |
FAILED | The premium could not be collected. |
UNKNOWN | The outcome of the collection is not final yet. The record stays in this state until the outcome is verified. |
Policy
| Value | Meaning |
|---|---|
NOT_REQUESTED | The policy has not been requested yet. |
PENDING | The policy is being issued. |
PARTIALLY_ISSUED | Some of the policies in the order were issued. |
ISSUED | All policies in the order were issued. |
FAILED_RETRYABLE | The policy could not be issued for a temporary reason; it is retried until the product's deadline. |
FAILED_FINAL | The policy definitively could not be issued. |
UNKNOWN | The outcome of the policy request is not final yet. |
CANCEL_PENDING | Cancellation was requested for the policy; the outcome is pending. |
CANCELLED | The policy was cancelled. |
PARTIALLY_ISSUED appears when only some units of the order are issued. While the axis is PENDING, FAILED_RETRYABLE or UNKNOWN, do not start the same operation again. An issued policy is cancelled through CANCEL_PENDING.Refund
| Value | Meaning |
|---|---|
NONE | No refund. |
REQUIRED | A premium refund is required. |
PENDING | The premium refund is in progress. |
REFUNDED | The premium was refunded. |
FAILED | The premium refund failed. |
Document
| Value | Meaning |
|---|---|
NOT_AVAILABLE | No document yet. |
PENDING | The document is being prepared. |
AVAILABLE | The policy document can be retrieved. |
FAILED | The document could not be retrieved. |
The policy document is not stored at Lunixi; it is retrieved from the provider on each request. An issued policy stays valid even if the document cannot be retrieved.
Overall status
The panel and the API also show an overall status for the order. The overall status is not stored separately; it is derived from the four axes on every read. The conditions are evaluated from top to bottom and the first matching row gives the overall status.
| Overall status | Condition |
|---|---|
REFUNDED | Refund is REFUNDED |
CANCELLED | Policy is CANCELLED |
FAILED | Collection is FAILED or policy is FAILED_FINAL |
ACTION_REQUIRED | Collection is ACTION_REQUIRED |
PROCESSING | Collection or policy is one of: PENDING, UNKNOWN, FAILED_RETRYABLE, CANCEL_PENDING |
PARTIALLY_ACTIVE | Policy is PARTIALLY_ISSUED |
ACTIVE | Policy is ISSUED |
CREATED | None of the above |
The document status does not affect the overall status: once the policy is issued, the order is ACTIVE even if the document is not ready yet.
The overall status is a summary. When you need to understand what happened in detail, look at the axes. For example, the axes show whether a FAILED overall status comes from the collection or from the policy.
Processing (PROCESSING)
The outcome of some work is not final yet: the collection or the policy is in progress, being verified, being retried or awaiting cancellation. In this state, do not start the same operation again. The order status is updated once the outcome is final.
Refund required
If the premium was collected but the policy definitively could not be issued, the policy becomes FAILED_FINAL, the refund becomes REQUIRED and the overall status shows FAILED. In this case the premium must be refunded to the buyer. When the refund starts, the refund axis becomes PENDING; when it completes, REFUNDED.
If the policy is issued after all once the refund has started, the refund is not reversed; cancellation is requested for the policy automatically and the policy becomes CANCEL_PENDING.
Data formats
| Data | Format | Example |
|---|---|---|
| Amount | Integer in minor units (kuruş). No decimals, strings or currency symbols. | 12500 = 125.00 TRY |
| Currency | ISO 4217 | TRY |
| Timestamp | ISO 8601, time zone required | 2025-12-23T12:50:00+03:00 |
| Date | ISO 8601 YYYY-MM-DD | 1990-01-31 |
| Empty value | If there is no value, the field is not sent at all; do not send an empty string or a placeholder such as "none". | — |
A timestamp without a time zone (such as 2025-12-23T12:50) is not accepted. The values in the table are examples.