Premium and Payment

This page is for orders whose premium you collect (premiumCollectedBy: MERCHANT). The premium is either an item of your Lunixi payment or a payment you take outside Lunixi. The policy is issued after the premium is collected.

If your provider collects the premium (premiumCollectedBy: PROVIDER), use Provider Collection instead of this page.

With a Lunixi payment

The buyer pays for the product and the insurance in one payment. The premium is a separate item in your payment's basket; the item's ID is the insurance order's ID.

Premium item

• The premium item carries no insurance fields. If an item with an inso_ ID carries insurance fields, the payment request is rejected with 400 VALIDATION_ERROR.
• The basket contains a single premium item per order.
• The sum of the items' price values must equal the payment request's amount field. So the payment amount is the sum of your items and the premium. Rule: Basket Items.

A payment request for a basket with two tickets and insurance with a premium of 39.80 TRY. The amounts are examples:

{
  "amount": 103980,
  "currency": "TRY",
  "orderId": "order-1001",
  "callbackUrl": "https://example.com/payments/callback",
  "basketItems": [
    {
      "id": "ticket-1",
      "name": "Izmir-Ankara train ticket",
      "price": 50000,
      "category1": "ticket",
      "itemType": "VIRTUAL",
      "insuranceCategory": "TICKET",
      "insuranceTypes": ["TICKET_CANCELLATION"]
    },
    {
      "id": "ticket-2",
      "name": "Izmir-Ankara train ticket",
      "price": 50000,
      "category1": "ticket",
      "itemType": "VIRTUAL",
      "insuranceCategory": "TICKET",
      "insuranceTypes": ["TICKET_CANCELLATION"]
    },
    {
      "id": "inso_<32 hex characters>",
      "name": "Ticket cancellation insurance",
      "price": 3980,
      "category1": "insurance",
      "itemType": "VIRTUAL"
    }
  ]
}

Binding the order to the payment

• When you bind with bind-payment, the rules are checked right away and an error is returned in the response. This is the recommended way.
• If you do not call bind-payment, the order is matched by the premium item in the basket and bound to the payment when the payment is captured. If the matching rules are not met, the order is not bound and no policy is requested; the captured amount stays in your payment and the order stays open. You cannot see this through an error response; so use bind-payment.
• Bind before the option expires: bind-payment returns 409 insurance.quote.expired for an expired option.
• If the payment's insured items differ from the quoted items (id, amount or insured value), binding returns 409 insurance.quote.stale. Get a new quote and create the order with the new option.

When the premium counts as collected

• The premium counts as collected when the captured amount of the payment reaches the premium: collection becomes COLLECTED and the policy is requested as PENDING.
• In a pre-authorized payment, the authorization is not enough; a capture is needed. With partial captures, the premium first rule applies: the premium counts as collected when the total captured amount reaches the premium. Until then collection stays PENDING.
• If the payment is cancelled, expires or definitively fails before it is captured, collection becomes FAILED, errorCode becomes insurance.premium.not_captured and no policy is requested.
• The policy is attempted until the product's deadline. If it definitively cannot be issued, the policy becomes FAILED_FINAL and the refund REQUIRED: Cancellation and Premium Refund › Refund required.

The premium in your payment record

• The premium reaches you with your payment as an item of your sale. You transfer the premium to your provider according to your agreement; Lunixi does not hold the premium on its own behalf.
• An amount refund you make from your payment yourself is not linked to the insurance and does not cancel the policy. To cancel the policy and refund the premium, use the insurance endpoints: Cancellation and Premium Refund.

Premium collected outside Lunixi

If you collected the premium through your own payment channel, you report the payment to Lunixi. Lunixi forwards the notification to your provider through your connection; it does not ask for a document or proof.

• The amount and currency you report must equal the order's premium.
• In this flow, refunds, chargebacks and disputes are between you and your provider. When you refund the premium, you report the refund to the API: Cancellation and Premium Refund › Refund outside Lunixi.

Related

• Orders and Payment Binding: bind-payment, confirm-payment, issue-policy
• Basket Items: item fields and the basket total rule
• Concepts and Statuses: collection and policy axes
• Provider Collection: orders whose premium the provider collects
• Insurance-Only Integration: the end-to-end flow without a Lunixi payment