Takaful

The Takaful module handles Shariah-compliant mutual insurance: users contribute periodically to a pool, then may submit a claim when certain events occur (death, critical illness, disability, natural disaster). The TakafulController at /takaful combines two primary resources: contributions (CRUD + list) and claims (submit, list, admin review, payout, and pool stats). Review/payout are restricted to @Roles(UserType.MORIA).

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	pools, users, organizations, payments
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

An INDIVIDUAL user creates a contribution via POST /takaful/contributions and can list / view detail of their own. When an incident occurs, the user submits a claim via POST /takaful/claims with a reason category. MORIA admin reviews (approve/reject) via PATCH /takaful/claims/:id/review; after approval, payout is disbursed via POST /takaful/claims/:id/payout. Pool stats are available to admins at GET /takaful/pools/:pool_id/stats.

Method	Path	Auth	Summary
GET	/v1/takaful/contributions	bearer	List contributions (own or by organization)
GET	/v1/takaful/contributions/:id	bearer	Contribution detail
POST	/v1/takaful/contributions	bearer	Create new contribution
GET	/v1/takaful/claims	bearer	List claims (own or by org)
GET	/v1/takaful/claims/:id	bearer	Claim detail
POST	/v1/takaful/claims	bearer	Submit new claim
PATCH	/v1/takaful/claims/:id/review	bearer	MORIA admin reviews claim (approve/reject)
POST	/v1/takaful/claims/:id/payout	bearer	MORIA admin processes payout
GET	/v1/takaful/pools/:pool_id/stats	bearer	MORIA admin: pool statistics

Auth + scope notes

• All endpoints require a Bearer JWT plus the appropriate permission.
• INDIVIDUAL can only access their own contribution/claim.
• ORGANIZATION/MORIA admins can pass the organization_id query (for contributions) or orgId query (for claims) to list within an organization’s scope.
• Claim review, payout, and pool stats endpoints are restricted to @Roles(UserType.MORIA) — platform superadmin only.
• Claim categories: death, critical_illness, disability, natural_disaster.

---

GET /v1/takaful/contributions bearer

List takaful contributions. INDIVIDUAL is automatically scoped to their own; ORGANIZATION/MORIA admins use the organization_id query to filter to a specific org.

bearer read-takaful RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
organization_id	UUID	optional	Filter by org (for admins); ignored if caller is INDIVIDUAL

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful contributions retrieved successfully",
  "data": {
    "contributions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "770e8400-e29b-41d4-a716-446655440222",
        "pool_id": "660e8400-e29b-41d4-a716-446655440111",
        "amount": "500.0000",
        "period_start": "2026-02-01",
        "period_end": "2026-03-01",
        "payment_ref": "PAY-20260201-001",
        "status": "active",
        "created_at": "2026-02-01T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	Organization ID or query param invalid
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient

---

GET /v1/takaful/contributions/:id bearer

Detail of a single takaful contribution.

bearer read-takaful RESOURCE_FETCHED

Path params

Param	Type	Notes
id	UUID	Contribution ID — validated by ParseUUIDPipe

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful contribution retrieved successfully",
  "data": {
    "contribution": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "770e8400-e29b-41d4-a716-446655440222",
      "pool_id": "660e8400-e29b-41d4-a716-446655440111",
      "amount": "500.0000",
      "period_start": "2026-02-01",
      "period_end": "2026-03-01",
      "payment_ref": "PAY-20260201-001",
      "status": "active"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Contribution not found

---

POST /v1/takaful/contributions bearer

Create a new takaful contribution to an organization’s pool. The contribution period is set explicitly via period_start / period_end.

bearer create-takaful CONTRIBUTION_MADE

Request body — CreateTakafulContributionDto

Field	Type	Required	Notes
organization_id	UUID	yes	Target pool organization
amount	numeric string	yes	Contribution amount (IsNumberString)
period_start	string (YYYY-MM-DD)	yes	Period start date
period_end	string (YYYY-MM-DD)	yes	Period end date
payment_ref	string	optional	Payment reference

Example request

{
  "organization_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
  "amount": "500.00",
  "period_start": "2025-02-01",
  "period_end": "2025-03-01",
  "payment_ref": "PAY-20250201-001"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Takaful contribution created successfully",
  "data": { "contribution": { "...": "TakafulContributions shape" } }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (UUID/format)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient

Side effects

• Emits BusinessEvent CONTRIBUTION_MADE (impact MEDIUM).
• Balance is moved to the organization’s takaful pool.

---

GET /v1/takaful/claims bearer

List takaful claims. INDIVIDUAL is automatically scoped to their own claims; ORGANIZATION/MORIA admins use the orgId query (note: param name here is camelCase, differing from the contributions endpoint).

bearer read-takaful-claims RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
orgId	UUID	optional	Filter by org (for admins); ignored if caller is INDIVIDUAL

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful claims retrieved successfully",
  "data": {
    "claims": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "contribution_id": "660e8400-e29b-41d4-a716-446655440111",
        "user_id": "770e8400-e29b-41d4-a716-446655440222",
        "pool_id": "880e8400-e29b-41d4-a716-446655440333",
        "claim_amount": "5000.0000",
        "approved_amount": null,
        "reason": "Medical emergency requiring treatment",
        "claim_reason": "critical_illness",
        "status": "submitted",
        "reviewed_by": null,
        "reviewed_at": null,
        "created_at": "2026-02-15T10:00:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	orgId invalid
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient

---

GET /v1/takaful/claims/:id bearer

Detail of a single takaful claim.

bearer read-takaful-claims RESOURCE_FETCHED

Path params

Param	Type	Notes
id	UUID	Claim ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful claim retrieved successfully",
  "data": {
    "claim": { "...": "TakafulClaims shape" }
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Claim not found

---

POST /v1/takaful/claims bearer

Submit a takaful claim against a contribution. Valid values for claim_reason: death, critical_illness, disability, natural_disaster.

bearer create-takaful-claims RESOURCE_CREATED

Request body — SubmitTakafulClaimDto

Field	Type	Required	Notes
contribution_id	UUID	yes	Contribution that the claim is based on
claim_amount	numeric string	yes	Requested amount
reason	string	yes	Free-text reason detail
claim_reason	enum TakafulClaimReason	yes	death, critical_illness, disability, natural_disaster

Example request

{
  "contribution_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
  "claim_amount": "5000.00",
  "reason": "Medical emergency requiring treatment",
  "claim_reason": "critical_illness"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Takaful claim submitted successfully",
  "data": {
    "claim": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contribution_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
      "claim_amount": "5000.0000",
      "claim_reason": "critical_illness",
      "status": "submitted"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (UUID/format/enum)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient

---

PATCH /v1/takaful/claims/:id/review bearer

MORIA admin reviews a claim: approve (with approved_amount) or reject. After approval, payout can be triggered via a separate endpoint.

bearer MORIA update-takaful-claims RESOURCE_UPDATED

Path params

Param	Type	Notes
id	UUID	Claim ID

Request body — ReviewClaimDto

Field	Type	Required	Notes
action	'approve' | 'reject'	yes	Review action
approved_amount	numeric string	optional	Approved amount (required when action=approve)

Example request

{
  "action": "approve",
  "approved_amount": "5000.00"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful claim reviewed successfully",
  "data": {
    "claim": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "approved",
      "approved_amount": "5000.0000",
      "reviewed_by": "880e8400-e29b-41d4-a716-446655440444",
      "reviewed_at": "2026-02-20T10:00:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed · approved_amount missing on approve
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role not MORIA
404 Not Found	Claim not found

---

POST /v1/takaful/claims/:id/payout bearer

MORIA admin processes payout for an approved claim. Funds are moved from the takaful pool to the recipient account and the claim status changes to paid.

bearer MORIA payout-takaful-claims WITHDRAWAL_PROCESSED

Path params

Param	Type	Notes
id	UUID	Claim ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful payout processed successfully",
  "data": {
    "payout": { "amount": "500.00", "reference": "PAYOUT-20250201-001" }
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid payout (claim not approved, etc.)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role not MORIA
404 Not Found	Claim not found

Side effects

• Claim status → paid.
• Takaful pool balance is reduced by approved_amount.
• Emits BusinessEvent WITHDRAWAL_PROCESSED (impact CRITICAL).

---

GET /v1/takaful/pools/:pool_id/stats bearer

MORIA admin: takaful pool statistics — total contributions, total claims, total payouts, and other metrics.

bearer MORIA read-takaful-claims RESOURCE_FETCHED

Path params

Param	Type	Notes
pool_id	UUID	Takaful pool ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Takaful pool statistics retrieved successfully",
  "data": {
    "stats": {
      "total_contributions": "10000.00",
      "total_claims": 5,
      "total_payouts": "2500.00"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	pool_id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role not MORIA
404 Not Found	Pool not found

---

Reference

Enum: TakafulStatus (contribution)

• active — contribution active within the period
• expired — period has elapsed
• cancelled — cancelled

Enum: TakafulClaimStatus

• submitted — claim newly submitted
• under_review — admin is reviewing
• approved — claim approved, awaiting payout
• rejected — claim rejected
• paid — payout executed

Enum: TakafulClaimReason

• death — participant death
• critical_illness — critical illness
• disability — disability
• natural_disaster — natural disaster

Standard error envelope

{
  "message": "Claim not found",
  "statusCode": 404,
  "error": "Not Found"
}

message may be a string or array of strings (multi-field validation errors).

Common HTTP codes

• 400 body/query/param validation
• 401 token expired / missing
• 403 permission insufficient · role not MORIA
• 404 contribution/claim/pool not found
• 500 internal — show a generic toast

Param naming note

• List contributions: ?organization_id=<uuid>
• List claims: ?orgId=<uuid> (camelCase, different)