Contracts Rail

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

stateDiagram-v2
    direction LR

    [*] --> Draft: 📝 Create
    Draft --> UnderReview: 📤 Submit
    UnderReview --> Approved: ✅ Approve
    UnderReview --> Rejected: ❌ Reject
    Approved --> Active: 🚀 Activate
    Active --> Completed: ✅ Complete
    Active --> Terminated: ⛔ Terminate
    Rejected --> [*]
    Completed --> [*]
    Terminated --> [*]

    note right of Draft: Shariah validation
    note right of UnderReview: Compliance review
    note right of Active: Contract in force

    classDef draft fill:#1565c0,color:#fff,stroke:#1565c0
    classDef review fill:#e65100,color:#fff,stroke:#e65100
    classDef approved fill:#2e7d32,color:#fff,stroke:#2e7d32
    classDef active fill:#1a5f4a,color:#fff,stroke:#1a5f4a
    classDef done fill:#455a64,color:#fff,stroke:#455a64
    classDef rejected fill:#c62828,color:#fff,stroke:#c62828

    class Draft draft
    class UnderReview review
    class Approved approved
    class Active active
    class Completed done
    class Terminated done
    class Rejected rejected

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

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

const client = new IOFClient({ apiKey: process.env.IOF_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,
});

from iof import IOFClient

client = IOFClient(api_key=os.environ["IOF_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)

:::