Takaful

Takaful has two parallel lifecycles. Contributions stay active while the cover period runs, then move to expired or cancelled. Claims move through submitted → under_review → approved or rejected, and approved claims end at paid after an admin disburses from the tabarru pool.

Lifecycle

Contributions fund the tabarru pool. Claims are evaluated by a Moria admin and, when approved, paid out from that same pool through a separate POST /:id/payout call. The two lifecycles never touch each other directly — they meet only inside the pool’s balance.

stateDiagram-v2
    direction LR

    [*] --> contribute_active: POST /v1/takaful/contributions<br/>(member contributes to the pool)
    contribute_active --> expired: cover period<br/>ends
    contribute_active --> contrib_cancelled: member cancels
    expired --> [*]
    contrib_cancelled --> [*]

    [*] --> claim_submitted: POST /v1/takaful/claims
    claim_submitted --> claim_under_review: admin opens the case
    claim_under_review --> claim_approved: admin approves
    claim_under_review --> claim_rejected: admin rejects
    claim_approved --> claim_paid: POST /:id/payout<br/>funds released
    claim_rejected --> [*]
    claim_paid --> [*]

    note right of contribute_active
        Contributions fund the
        tabarru pool. Claims are
        paid from the same pool.
    end note

Sequence

Members contribute to the tabarru pool, then later file claims with a reason (death, critical illness, disability, natural disaster) and supporting documents. The admin reviews and approves or rejects; on approval, a separate POST /:id/payout call disburses from the takaful pool to the claimant’s main balance.

---
config:
  sequence:
    actorMargin: 380
    width: 240
    messageMargin: 38
    boxMargin: 14
    noteMargin: 12
---
sequenceDiagram
    autonumber
    actor M as Member
    actor AD as Moria Admin
    participant API as Moria API

    Note over M,API: Contribution<br/>• debits the main balance<br/>• credits the tabarru pool

    M->>API: POST /v1/takaful/contributions<br/>{ pool_id, amount }
    API->>API: debit main balance<br/>credit tabarru pool
    API-->>M: 201 Created<br/>{ contribution_id, status: "active" }

    Note over M,API: Claim submission
    M->>API: POST /v1/takaful/claims<br/>{ pool_id, reason: "critical_illness",<br/>amount, documents[] }
    API-->>M: 201 Created<br/>{ claim_id, status: "submitted" }

    Note over AD,API: Admin review
    AD->>API: PATCH /v1/takaful/claims/:id/review<br/>{ decision: "approved", note }
    API-->>AD: 200 OK<br/>{ status: "approved" }

    Note over AD,API: Payout
    AD->>API: POST /v1/takaful/claims/:id/payout
    API->>API: debit tabarru pool<br/>credit claimant's main balance
    API-->>AD: 200 OK<br/>{ status: "paid" }

Approval and payout are separate calls

A claim moving to approved does not automatically pay the claimant. Payout is a deliberate second admin action — POST /v1/takaful/claims/:id/payout — that debits the tabarru pool and credits the claimant’s main balance. Between approved and paid a claim may sit waiting for the admin to disburse.

Contributions and claims share a pool, not a record

A member’s contributions are not earmarked for that member’s claims — the tabarru pool is shared. Any approved claim is paid from the pool’s aggregate balance, regardless of who contributed.