Contracts Rail

The Contracts Rail provides APIs for managing Islamic financial contracts throughout their lifecycle.

Overview

Islamic Open Finance™ supports multiple Shariah-compliant contract types:

Contract Type	Description	Use Case
murabaha	Cost-plus-profit sale	Vehicle/equipment financing
ijarah	Leasing arrangement	Property/asset leasing
musharakah	Partnership	Joint ventures, equity financing
mudarabah	Profit-sharing	Investment funds
sukuk	Islamic bonds	Capital markets
wakala	Agency arrangement	Investment management
salam	Forward sale	Commodity financing
istisna	Manufacturing contract	Construction, manufacturing
takaful	Islamic insurance	Insurance products

Endpoints

Create Contract

POST /v1/contracts

Creates a new contract.

Request Body:

{
  "type": "murabaha",
  "jurisdiction": "SA",
  "parties": {
    "financier": {
      "entityId": "ent_financier_123"
    },
    "customer": {
      "entityId": "ent_customer_456"
    }
  },
  "asset": {
    "description": "Toyota Camry 2024",
    "category": "vehicle",
    "costPrice": {
      "amount": 120000,
      "currency": "SAR"
    },
    "profitMargin": 0.08
  },
  "terms": {
    "paymentSchedule": "monthly",
    "numberOfInstallments": 60,
    "gracePeriodDays": 30
  }
}

Response:

{
  "data": {
    "id": "con_abc123",
    "type": "murabaha",
    "status": "draft",
    "jurisdiction": "SA",
    "parties": { ... },
    "asset": { ... },
    "terms": { ... },
    "payment": {
      "totalAmount": 129600,
      "monthlyAmount": 2160,
      "currency": "SAR"
    },
    "compliance": {
      "shariahStatus": "pending_review",
      "lastChecked": null
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

List Contracts

GET /v1/contracts

Lists all contracts for the authenticated tenant.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status (draft, active, completed, terminated)
type	string	Filter by contract type
page	number	Page number (default: 1)
perPage	number	Items per page (default: 20, max: 100)

Get Contract

GET /v1/contracts/{id}

Retrieves a specific contract by ID.

Update Contract

PATCH /v1/contracts/{id}

Updates a contract. Only allowed for contracts in draft status.

Submit for Approval

POST /v1/contracts/{id}/submit

Submits a draft contract for Shariah review and approval.

Activate Contract

POST /v1/contracts/{id}/activate

Activates an approved contract.

Terminate Contract

POST /v1/contracts/{id}/terminate

Terminates an active contract.

Request Body:

{
  "reason": "early_settlement",
  "effectiveDate": "2024-06-15",
  "notes": "Customer requested early settlement"
}

Contract Lifecycle

Webhooks

The Contracts Rail emits the following webhook events:

Event	Description
contract.created	Contract created
contract.submitted	Contract submitted for review
contract.approved	Contract approved
contract.rejected	Contract rejected
contract.activated	Contract activated
contract.completed	Contract completed
contract.terminated	Contract terminated

Code Examples

TypeScript

import { IOFClient } from "@iof/sdk";

const client = new IOFClient({ apiKey: "your-api-key" });

// Create a Murabaha contract
const contract = await client.contracts.create({
  type: "murabaha",
  jurisdiction: "SA",
  parties: {
    financier: { entityId: "ent_123" },
    customer: { entityId: "ent_456" },
  },
  asset: {
    description: "Commercial vehicle",
    category: "vehicle",
    costPrice: { amount: 100000, currency: "SAR" },
    profitMargin: 0.08,
  },
  terms: {
    paymentSchedule: "monthly",
    numberOfInstallments: 48,
  },
});

// Submit for approval
await client.contracts.submit(contract.id);

// List active contracts
const contracts = await client.contracts.list({
  status: "active",
  perPage: 50,
});

Python

from iof import IOFClient

client = IOFClient(api_key="your-api-key")

# Create a Murabaha contract
contract = client.contracts.create(
    type="murabaha",
    jurisdiction="SA",
    parties={
        "financier": {"entity_id": "ent_123"},
        "customer": {"entity_id": "ent_456"},
    },
    asset={
        "description": "Commercial vehicle",
        "category": "vehicle",
        "cost_price": {"amount": 100000, "currency": "SAR"},
        "profit_margin": 0.08,
    },
    terms={
        "payment_schedule": "monthly",
        "number_of_installments": 48,
    }
)

# Submit for approval
client.contracts.submit(contract.id)

# List active contracts
contracts = client.contracts.list(status="active", per_page=50)