LFI · Insurance · Quotation · TPP-Led

TPP-Led Flow 7 min read

The TPP collects KYC in its own UI and surfaces an LFI-hosted payment URL to the customer. Your LFI is responsible for underwriting, premium pricing, payment hosting, and policy document generation — but customer interaction outside the payment page lives entirely with the TPP.

01 End-to-end sequence

TPP-Led flow

Sequence diagramInsurance Quotation — TPP-Led FlowClick to expand

02 POST /{type}-insurance-quotes

Underwrite and return one or more quotes

Create Quote behaves identically to LFI-Led mode — mint a QuoteId, run underwriting, return 201 with the quote details (or 204 to decline). The mode forks on PATCH Accept, not on Create.

03 PATCH /{type}-insurance-quotes/{QuoteId}

Accept the quote — return PolicyIssuanceAllowed

Respond 200 with data.PolicyIssuanceAllowed declaring which steps the TPP may perform. All three booleans are required.

200 OK responsejson

{
  "data": {
    "PolicyIssuanceAllowed": {
      "CustomerVerification": true,
      "Payment": true,
      "PolicyDocuments": true
    }
  }
}

Immediately after responding, PATCH the quote-log with QuoteStatus: ApplicationPending so the TPP knows the application has been registered. The TPP will then collect KYC in its own UI.

04 PATCH /{type}-insurance-quotes/{QuoteId} (second call)

Receive the TPP's KYC submission

The TPP submits the collected KYC by PATCHing the same quote endpoint again. The body conforms to the sector\'s accept-quote request schema (AEInsurance.AE{Type}InsuranceQuoteAcceptQuoteRequestProperties). Validate it as you would a direct application: Emirates ID checks, sanctions screening, any sector-specific underwriting confirmations.

If KYC fails, respond 400 with a descriptive errorMessage; the TPP will surface the error to the customer and let them retry. If KYC passes, respond 200 (no body) and proceed to issue the payment URL.

05 PATCH /insurance-quote-log/{logId}

Emit ApplicationApproved + BrokerInstructions.Url

Generate a single-use payment URL on your LFI-hosted payment surface and emit a Pending Completion event:

PATCH /insurance-quote-log/{logId}json

{
  "QuoteStatus": "ApplicationApproved",
  "BrokerInstructions": [
    {
      "ActionRequired": "Customer must complete premium payment at the LFI-hosted payment page.",
      "Url": "https://pay.examplelfi.ae/checkout/sess-c93e1f4a"
    }
  ]
}

The TPP will redirect the customer to this URL. Customer payment is collected on your LFI’s page — the TPP never sees the card details. After payment success, your LFI redirects the customer back to the URL the TPP supplied (typically as part of its webhook subscription or out-of-band registration).

Single-use, time-bound

Invalidate the URL after first redemption or after a session window of 15–30 minutes. The TPP MUST NOT cache or replay it. If the customer abandons and returns later, you can emit a fresh PaymentRequired event with a new URL.

06 POST /{type}-insurance-policies

Issue the policy from the KYC + payment-confirmed quote

Once payment is confirmed, the TPP calls POST to create the policy. The body carries the originating QuoteId plus any additional data your LFI requires (most KYC was already submitted via the second PATCH). Issue the policy and respond 201.

If the TPP retries with the same QuoteId, return the same policy reference — policy creation MUST be idempotent.

07 PATCH /insurance-quote-log/{logId}

Emit PolicyIssued + Documents

In TPP-Led mode the TPP is the document delivery channel — your LFI MUST NOT email or post documents to the customer directly. Attach every customer-facing document (Policy Booklet, Terms & Conditions, IPID, etc.) as base64-encoded Documents entries with SHA-256 hashes for integrity verification.

PATCH /insurance-quote-log/{logId}json

{
  "QuoteStatus": "PolicyIssued",
  "Documents": [
    {
      "Type": "Policy Booklet",
      "FileName": "policy-booklet.pdf",
      "ContentType": "application/pdf",
      "Content": "JVBERi0xLjQKJeLjz9MKMyAwI...",
      "HashType": "SHA256",
      "Hash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
    },
    {
      "Type": "Terms & Conditions",
      "FileName": "terms.pdf",
      "ContentType": "application/pdf",
      "Content": "JVBERi0xLjQKJeLjz9MKMyAwI...",
      "HashType": "SHA256",
      "Hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ]
}

Documents MUST be PDFs (application/pdf) or images (image/jpeg, image/png). The TPP verifies each Hash against the decoded Content before surfacing to the customer.

08 PATCH /insurance-quote-log/{logId}

Emit Completed and close the lifecycle

Same as LFI-Led: emit a final Completed Status event with the finalised premium breakdown, policy term, and (where applicable) the Commission due to the TPP. The Hub rejects any subsequent PATCH for this logId.

Commission.PaymentMethod controls how the LFI pays the TPP: DirectToTPP for direct bilateral settlement, or ThroughAPIHub for Hub-routed payment.