Zakat Rail

Zakat Rail

Zakat calculation, distribution, and compliance for Islamic finance.

Overview

The Zakat Rail provides endpoints for calculating, tracking, and distributing Zakat in compliance with Islamic principles.

Base URL

/api/v1/zakat

Endpoints

Calculate Zakat

POST /api/v1/zakat/calculate

Calculate Zakat obligation based on assets.

Request Body:

{
  "assets": {
    "cash": "50000.00",
    "gold": "1000.00",
    "silver": "500.00",
    "tradingGoods": "25000.00",
    "investments": "100000.00"
  },
  "liabilities": {
    "debts": "10000.00"
  },
  "currency": "SAR",
  "calculationDate": "2025-01-15",
  "nisabType": "gold"
}

Response:

{
  "data": {
    "calculationId": "zak_abc123",
    "totalAssets": "176500.00",
    "totalLiabilities": "10000.00",
    "netZakatableWealth": "166500.00",
    "nisabThreshold": "15000.00",
    "isZakatDue": true,
    "zakatAmount": "4162.50",
    "zakatRate": "0.025",
    "currency": "SAR",
    "calculationDate": "2025-01-15"
  }
}

Get Nisab Rates

GET /api/v1/zakat/nisab

Get current Nisab thresholds.

Query Parameters:

Parameter	Type	Description
currency	string	Currency code (default: USD)
date	string	Date for rates (default: today)

Response:

{
  "data": {
    "gold": {
      "grams": 85,
      "value": "5500.00",
      "currency": "USD"
    },
    "silver": {
      "grams": 595,
      "value": "450.00",
      "currency": "USD"
    },
    "date": "2025-01-15",
    "source": "market_rates"
  }
}

Create Distribution

POST /api/v1/zakat/distributions

Create a Zakat distribution record.

Request Body:

{
  "calculationId": "zak_abc123",
  "amount": "4162.50",
  "currency": "SAR",
  "recipients": [
    {
      "category": "FUQARA",
      "amount": "1000.00",
      "description": "Poor and needy"
    },
    {
      "category": "MASAKIN",
      "amount": "1000.00",
      "description": "Destitute"
    }
  ],
  "distributionDate": "2025-01-20"
}

List Calculations

GET /api/v1/zakat/calculations

List Zakat calculations for the tenant.

Query Parameters:

Parameter	Type	Description
page	number	Page number
perPage	number	Items per page
year	number	Filter by Hijri year
status	string	Filter by status

Asset Classification

POST /api/v1/zakat/assets/classify

Classify assets for Zakat eligibility.

Request Body:

{
  "assets": [
    {
      "type": "STOCK",
      "name": "Company Shares",
      "value": "50000.00",
      "purpose": "TRADING"
    }
  ]
}

Recipient Categories

Category	Arabic	Description
FUQARA	الفقراء	The poor
MASAKIN	المساكين	The needy
AMILIN	العاملين عليها	Zakat administrators
MUALLAFAT	المؤلفة قلوبهم	Those whose hearts are to be reconciled
RIQAB	الرقاب	Freeing captives
GHARIMIN	الغارمين	Those in debt
FI_SABILILLAH	في سبيل الله	In the cause of Allah
IBN_SABIL	ابن السبيل	The wayfarer

Events

Event	Description
zakat.calculated	Zakat calculation completed
zakat.distributed	Zakat distribution recorded
zakat.nisab.updated	Nisab rates updated

Error Codes

Code	Description
BELOW_NISAB	Net wealth below Nisab threshold
INVALID_ASSET_TYPE	Unrecognized asset type
CALCULATION_FAILED	Calculation error

See Also

• Rails & SKUs - Understanding rails
• Compliance - Shariah compliance