Murabaha Rail

Cost-plus financing contract endpoints for Islamic banking.

Overview

The Murabaha rail provides:

Cost-plus sale contract creation and management
Shariah-compliant markup disclosure
Payment schedule generation
Early settlement calculations

Murabaha is a sale contract where the seller discloses the cost and adds an agreed profit margin. It is the most widely used Islamic finance contract for trade and asset financing.

Endpoints

Create Murabaha Contract

POST /v1/rails/murabaha/contracts

const contract = await iof.murabaha.create({
  asset_description: "Commercial vehicle - Toyota Hilux 2024",
  cost_price: 45000,
  profit_margin: 0.08,
  currency: "USD",
  payment_terms: {
    installments: 36,
    frequency: "monthly",
  },
  counterparty_id: "cpty_abc123",
});

Response:

{
  "id": "mur_xyz",
  "type": "murabaha",
  "status": "DRAFT",
  "cost_price": 45000,
  "profit_amount": 3600,
  "sale_price": 48600,
  "currency": "USD",
  "payment_schedule": {
    "installments": 36,
    "installment_amount": 1350,
    "frequency": "monthly"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Get Murabaha Contract

GET /v1/rails/murabaha/contracts/:id

List Murabaha Contracts

GET /v1/rails/murabaha/contracts

Execute Murabaha Contract

POST /v1/rails/murabaha/contracts/:id/execute

Early Settlement

POST /v1/rails/murabaha/contracts/:id/settle

Contract Status

Status	Description
`DRAFT`	Contract created, pending review
`PENDING_SHARIAH_REVIEW`	Awaiting Shariah board approval
`SHARIAH_APPROVED`	Approved by Shariah board
`ACTIVE`	Contract executed and active
`COMPLETED`	All payments received
`TERMINATED`	Contract terminated early

Shariah Compliance

Cost price and profit margin must be disclosed to the buyer
The asset must exist and be owned by the seller at the time of sale
The sale price cannot be changed after contract execution
Late payment penalties are donated to charity (not retained as income)

Webhooks

Event	Description
`murabaha.contract.created`	Contract created
`murabaha.contract.executed`	Contract executed
`murabaha.payment.received`	Installment received
`murabaha.contract.completed`	All payments completed

Standards

Next Steps

Ijarah Rail - Islamic leasing
Musharakah Rail - Partnership finance
Contracts Rail - General contract management