Setup

Connect your provider

Open the POS Center > Insurance page in the panel. Add the connection with Activate on the card of the provider you have an agreement with:

• Choose Test or Live as the Environment and enter the credential your provider gave you. The credential is written to the secure vault and never shown again.
• In the connection's details, under Products on this connection, enable the insurance product you will offer.
• When you enable the product, answer Who collects the premium with You collect. In the Checkout Form the premium is added to your payment; so the form offers only products whose premium you collect.

Your agreement with your provider determines who collects the premium; see Insurance › Who collects the premium. Test connection and environments: Testing.

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 the Checkout form usage mode. If insurance is off or this mode is not selected, the form shows no insurance: Insurance Menu › General.
• On the Insurance Types screen, enable the type you will offer and save. Types are off by default: Insurance Menu › Insurance Types.

Choose where insurance appears in your form settings

In the panel, under Form Settings > Insurance, choose where insurance is shown in the form:

• Both settings are off by default. If both are off, the form shows no insurance at all and makes no request for insurance.
• If you have no active insurance connection, the section appears locked and read-only; your saved setting does not change. Complete step 1 first.
• You turn insurance on and off in the form only from the panel. The settings field of the payment request does not turn insurance on or off; if you send an insurance setting inside settings, the request is rejected with 400 VALIDATION_ERROR.

Add insurance fields to the basket items when you create the payment

Create the payment as usual with POST /payments/intents (Checkout Form). Add the insurance fields to the items you want to offer insurance for:

• Insurance is offered only on a payment where you send basketItems. On a payment without a basket the form shows no insurance.
• No insurance is offered for an item without insurance fields. At least insuranceCategory is required.
• Insurance is per unit: on an item that carries insurance fields, send each unit as a separate item and keep the item ids unique.
• With insuranceContext you can send non-personal details such as the trip. These details arrive filled in in the form.
• If you already have the buyer's details (insured person, booking code, IMEI, plate and so on), you can send them with insuranceData. It may be partial: the fields you send are shown masked in the form and the buyer fills in only the missing ones. If you send everything the quote and the policy need, the quote is obtained on its own when the form opens. Booking codes and personal details are not sent in insuranceContext.

All fields and their rules: Basket Items › Insurance fields. The format of the pre-fill data and examples per type: Basket Items › Insurance pre-fill data.

A payment request with two tickets. Each ticket carries the trip, its passenger (with contact details), the ticket amount, the booking code and the ticket number, so the quote is obtained on its own when the form opens. If you do not send insuranceData, the buyer fills in these details in the form. The values are examples; replace the values in angle brackets with your buyer's details:

{
  "amount": 100000,
  "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"],
      "insuranceContext": {
        "transportMode": "TRAIN",
        "departureAt": "2025-12-23T12:50:00+03:00",
        "originCity": "Izmir",
        "destinationCity": "Ankara",
        "carrier": "Example Carrier"
      },
      "insuranceData": {
        "insured": [
          { "identityType": "PASSPORT", "identityNumber": "<passport number>", "birthDate": "<YYYY-MM-DD>",
            "email": "<email>", "phone": "<phone with +90>" }
        ],
        "tickets": { "priceAmount": 50000, "pnr": "<booking code>", "ticketNumber": "<ticket number>" }
      }
    },
    {
      "id": "ticket-2",
      "name": "Izmir-Ankara train ticket",
      "price": 50000,
      "category1": "ticket",
      "itemType": "VIRTUAL",
      "insuranceCategory": "TICKET",
      "insuranceTypes": ["TICKET_CANCELLATION"],
      "insuranceContext": {
        "transportMode": "TRAIN",
        "departureAt": "2025-12-23T12:50:00+03:00",
        "originCity": "Izmir",
        "destinationCity": "Ankara",
        "carrier": "Example Carrier"
      },
      "insuranceData": {
        "insured": [
          { "identityType": "PASSPORT", "identityNumber": "<passport number>", "birthDate": "<YYYY-MM-DD>",
            "email": "<email>", "phone": "<phone with +90>" }
        ],
        "tickets": { "priceAmount": 50000, "pnr": "<booking code>", "ticketNumber": "<ticket number>" }
      }
    }
  ]
}

amount is the amount before the buyer selects insurance. You do not add the premium; if the buyer selects insurance, the premium is added when the payment is submitted (Payment and Premium).

Open the form and verify

Open the form as usual. If there is an eligible offer, the form shows insurance in the places you turned on. If you sent everything the quote and the policy need, the quote appears with its price in the payment step; insurance is still added only with the buyer's acceptance: Behavior Rules › Pre-filled details. The card field (createCardField) variant shows no insurance; use the full form for insurance.

Try it with your test key and your test connection: Testing. If insurance does not appear: If insurance is not offered.