API Path

If you use your own payment form, you offer insurance to your buyer in your own interface. You get eligibility and quotes from the API and create an order with the option the buyer selected. The policy is issued after the premium is collected.

If you use the Lunixi payment form, use the Checkout Form path instead of this section. If you take the payment outside Lunixi, step-by-step guide: Insurance-Only Integration.

Before you start

• Insurance and the API path must be enabled on your account. Your API key must have access to the insurance product. The insurance-only flow does not require the payment product.
• Connect your provider in the panel. On the POS Center > Insurance page, add a connection for the provider you have an agreement with and enable the product you will offer in that connection.
• Turn insurance on and choose the type to offer. In the Insurance product in the panel's left menu, on the General screen, turn on Insurance on and select at least one API usage mode: API — linked to a Lunixi payment if you take the payment through Lunixi, API — external collection if you take it outside Lunixi. On the Insurance Types screen, enable the type you will offer and save. Details: Insurance Menu › General, Insurance Menu › Insurance Types.
• Choose who collects the premium. When enabling the product, answer Who collects the premium according to your agreement with your provider. The two flows below are for orders whose premium you collect (You collect). If the provider collects the premium (Provider collects): Provider Collection. Collection methods: Insurance › Who collects the premium.

Test connection and test key: Testing.

Two flows

You use one of two flows depending on how you collect the premium:

The quote and order steps are the same in both flows. They differ in how the premium is collected: Premium and Payment.

For insurance types not linked to a basket item, the quote is obtained without a basket item; steps and collection: Selling Without a Basket Item.

Insurance types that do not return a quote have no quote or order; you pass the buyer's details to your provider as a lead: Leads.

Flow linked to a Lunixi payment

Insurance-only flow

In this flow you report the payment to Lunixi; Lunixi forwards the notification to your provider through your connection. Then you request the policy. Details: Premium and Payment › Premium collected outside Lunixi. Every step including documents, cancellation, refunds and webhooks, with an end-to-end example: Insurance-Only Integration.

If you already have the buyer's details

You can send the details the quote needs (insured person, IMEI, booking code, plate and so on) in the basket item's insuranceData field, and the non-personal details in its insuranceContext field: Basket Items › Insurance pre-fill data.

• The eligibility response shows, per offer, which fields were provided (providedFields, personal values masked), what was filled from the context (prefill) and whether the quote can be obtained without further fields (quoteReady): Eligibility › Pre-fill data and the automatic quote.
• In the quote request you send only the missing fields; the body is completed from the items' details. In a quote taken with paymentIntentId the body may even be empty: Quote › Quote with pre-fill data.
• insuranceData in context.items is not stored; it is used only in that request.

Endpoints

The base address is https://api-gateway.lunixi.com. Authentication, request and response fields, errors and webhook events of each endpoint: Endpoint Reference.

Authentication

The insurance endpoints accept only requests signed with your API key. No Authorization header is needed; a Bearer access token or a panel session does not authenticate these endpoints. A request without the signature headers gets 401 AUTH_HEADERS_MISSING.

The only exception is the provider collection endpoint (/pay): because it can carry card data, it also requires a Bearer access token in addition to the signature. See Provider Collection › Authentication.

Canonical string and signing rules: Authentication. The second signed line is the full request path including the query string, if any. Send the body as compact JSON and compute Digest from the body you send.

The cURL examples in this section use the following shell helper:

# lunixi-sign.sh — requires OpenSSL 3.0+.
# Usage: source lunixi-sign.sh
#        lunixi_sign GET  "/api/v1/insurance/orders?limit=25"
#        lunixi_sign POST "/api/v1/insurance/quotes" "$BODY"
LUNIXI_KEY_ID="mk_test_..."
LUNIXI_KEY_FILE="lunixi-signing.key"
 
lunixi_sign() {
  local method="$1" req_path="$2" body="${3-}"
  DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  NONCE=$(openssl rand -hex 16)
  if [ -n "$body" ]; then
    DIGEST="SHA-256=$(printf '%s' "$body" | openssl dgst -sha256 -binary | base64)"
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s\nDigest:%s' "$method" "$req_path" "$DATE" "$NONCE" "$DIGEST" > canonical.txt
  else
    DIGEST=""
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s' "$method" "$req_path" "$DATE" "$NONCE" > canonical.txt
  fi
  SIGNATURE=$(openssl pkeyutl -sign -inkey "$LUNIXI_KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
}

Authentication and access errors:

Idempotency-Key

The endpoints that create an order or change its state make the Idempotency-Key header required: orders, confirm-payment, issue-policy, pay, cancel, refund-premium. The endpoint that files a claim (policies/{policyId}/claims) and the endpoint that submits a lead (leads) also require the key. quotes and bind-payment accept the header as optional.

• The key is a printable ASCII value of 8-200 characters without spaces. A missing or malformed key returns 400 VALIDATION_ERROR.
• Derive the key from your operation and, after a timeout or a 5xx, repeat the request with the same key and the same body. If the order was created on the first attempt, no second order is created; the recorded order is returned.
• If you use the same key with a different order request, you get 409 insurance.idempotency.conflict. Generate a new key for a new order.
• Operations on an order are also naturally repeatable: binding the same payment again, reporting the same payment ID again, or requesting the policy, the cancellation or the refund again returns the order as it is.

Responses and errors

A successful response body is under data. On list endpoints the pagination information is in pageInfo; see Pagination.

An error response carries status: "failure", code, message, requestId and details. Branch in your code on code, not on message; message depends on the language. Envelope details: Errors.

Codes that can be returned by every insurance endpoint:

Endpoint-specific codes are listed on each endpoint page. 4xx errors do not resolve by retrying the same request; fix the request first.

Personal data you send is not written to error responses. Responses contain only Lunixi IDs; the provider's references and error codes are not included.

Next