Quick Start

Quick Start

Build a complete Islamic Open Finance™ integration in 15 minutes.

What We’ll Build

In this quick start, you’ll:

1. Create a sandbox account
2. Install the SDK
3. Create your first Murabaha contract
4. Set up webhook notifications
5. Query contract status

Prerequisites

• Node.js 18+ or Python 3.9+
• An IDE or text editor
• Basic REST API knowledge

Step 1: Get Your API Credentials

1. Sign up at app.islamicopenfinance.com
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Name it “Quickstart Demo”
5. Copy the key (you won’t see it again!)

# Set your API key as an environment variable
export IOF_API_KEY=sk_sandbox_your_key_here

Step 2: Install the SDK

npm install @iof/sdk

pnpm add @iof/sdk

pip install iof-sdk

:::

Step 3: Initialize the Client

Create a new file quickstart.ts (or quickstart.py):

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

const client = new IOFClient({
  apiKey: process.env.IOF_API_KEY!,
  environment: "sandbox",
});

async function main() {
  // We'll add code here
}

main().catch(console.error);

import os
from iof import IOFClient

client = IOFClient(
    api_key=os.environ["IOF_API_KEY"],
    environment="sandbox"
)

def main():
    # We'll add code here
    pass

if __name__ == "__main__":
    main()

:::

Step 4: Create Entities

Before creating a contract, we need to create the parties:

// Create the financier (bank/institution)
const financier = await client.entities.create({
  type: "institution",
  name: "Al Rajhi Bank",
  jurisdiction: "SA",
  registrationNumber: "123456789",
});

// Create the customer
const customer = await client.entities.create({
  type: "individual",
  name: "Ahmed Al-Rashid",
  jurisdiction: "SA",
  nationalId: "1234567890",
  email: "ahmed@example.com",
});

console.log("Financier:", financier.id);
console.log("Customer:", customer.id);

# Create the financier (bank/institution)
financier = client.entities.create(
    type="institution",
    name="Al Rajhi Bank",
    jurisdiction="SA",
    registration_number="123456789"
)

# Create the customer
customer = client.entities.create(
    type="individual",
    name="Ahmed Al-Rashid",
    jurisdiction="SA",
    national_id="1234567890",
    email="ahmed@example.com"
)

print(f"Financier: {financier.id}")
print(f"Customer: {customer.id}")

:::

Step 5: Create a Murabaha Contract

Now let’s create a vehicle financing contract:

const contract = await client.contracts.create({
  type: "murabaha",
  jurisdiction: "SA",
  parties: {
    financier: { entityId: financier.id },
    customer: { entityId: customer.id },
  },
  asset: {
    description: "Toyota Land Cruiser 2024",
    category: "vehicle",
    vin: "JTDKN3DU5A0123456",
    costPrice: {
      amount: 250000,
      currency: "SAR",
    },
    profitMargin: 0.07, // 7% profit margin
  },
  terms: {
    paymentSchedule: "monthly",
    numberOfInstallments: 60, // 5 years
    gracePeriodDays: 30,
    lateFeePercentage: 0.02,
  },
});

console.log("Contract created:", contract.id);
console.log("Status:", contract.status);
console.log("Monthly payment:", contract.payment.monthlyAmount, "SAR");
console.log("Total amount:", contract.payment.totalAmount, "SAR");

contract = client.contracts.create(
    type="murabaha",
    jurisdiction="SA",
    parties={
        "financier": {"entity_id": financier.id},
        "customer": {"entity_id": customer.id},
    },
    asset={
        "description": "Toyota Land Cruiser 2024",
        "category": "vehicle",
        "vin": "JTDKN3DU5A0123456",
        "cost_price": {
            "amount": 250000,
            "currency": "SAR",
        },
        "profit_margin": 0.07,  # 7% profit margin
    },
    terms={
        "payment_schedule": "monthly",
        "number_of_installments": 60,  # 5 years
        "grace_period_days": 30,
        "late_fee_percentage": 0.02,
    }
)

print(f"Contract created: {contract.id}")
print(f"Status: {contract.status}")
print(f"Monthly payment: {contract.payment.monthly_amount} SAR")
print(f"Total amount: {contract.payment.total_amount} SAR")

:::

Step 6: Submit for Shariah Review

// Submit for Shariah compliance review
const submitted = await client.contracts.submit(contract.id);
console.log("Contract submitted for review:", submitted.status);

// In sandbox, approval is automatic
// In production, this would go through the Shariah board

# Submit for Shariah compliance review
submitted = client.contracts.submit(contract.id)
print(f"Contract submitted for review: {submitted.status}")

# In sandbox, approval is automatic
# In production, this would go through the Shariah board

:::

Step 7: Set Up Webhooks

Create a webhook subscription to receive real-time updates:

const webhook = await client.webhooks.create({
  url: "https://your-app.com/webhooks/iof",
  events: [
    "contract.approved",
    "contract.activated",
    "payment.received",
    "payment.overdue",
  ],
  secret: process.env.WEBHOOK_SECRET,
});

console.log("Webhook created:", webhook.id);

webhook = client.webhooks.create(
    url="https://your-app.com/webhooks/iof",
    events=[
        "contract.approved",
        "contract.activated",
        "payment.received",
        "payment.overdue",
    ],
    secret=os.environ["WEBHOOK_SECRET"]
)

print(f"Webhook created: {webhook.id}")

:::

Step 8: Query Contract Status

// Get contract details
const details = await client.contracts.get(contract.id);
console.log("Contract details:", details);

// List all contracts
const contracts = await client.contracts.list({
  status: "active",
  type: "murabaha",
});

for (const c of contracts.data) {
  console.log(`${c.id}: ${c.asset.description} - ${c.status}`);
}

# Get contract details
details = client.contracts.get(contract.id)
print(f"Contract details: {details}")

# List all contracts
contracts = client.contracts.list(
    status="active",
    type="murabaha"
)

for c in contracts.data:
    print(f"{c.id}: {c.asset.description} - {c.status}")

:::

Complete Example

Here’s the complete quickstart script:

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

const client = new IOFClient({
  apiKey: process.env.IOF_API_KEY!,
  environment: "sandbox",
});

async function main() {
  // 1. Create entities
  const financier = await client.entities.create({
    type: "institution",
    name: "Al Rajhi Bank",
    jurisdiction: "SA",
    registrationNumber: "123456789",
  });

  const customer = await client.entities.create({
    type: "individual",
    name: "Ahmed Al-Rashid",
    jurisdiction: "SA",
    nationalId: "1234567890",
  });

  // 2. Create contract
  const contract = await client.contracts.create({
    type: "murabaha",
    jurisdiction: "SA",
    parties: {
      financier: { entityId: financier.id },
      customer: { entityId: customer.id },
    },
    asset: {
      description: "Toyota Land Cruiser 2024",
      category: "vehicle",
      costPrice: { amount: 250000, currency: "SAR" },
      profitMargin: 0.07,
    },
    terms: {
      paymentSchedule: "monthly",
      numberOfInstallments: 60,
    },
  });

  console.log("Contract created:", contract.id);
  console.log("Monthly payment:", contract.payment.monthlyAmount, "SAR");

  // 3. Submit for review
  await client.contracts.submit(contract.id);
  console.log("Contract submitted for Shariah review");

  // 4. Set up webhook
  await client.webhooks.create({
    url: "https://your-app.com/webhooks/iof",
    events: ["contract.approved", "payment.received"],
  });

  console.log("Setup complete!");
}

main().catch(console.error);

:::

Next Steps

Congratulations! You’ve created your first Islamic Open Finance™ contract.

• API Reference - Explore all available endpoints
• Webhooks Guide - Learn more about event notifications
• Contract Types - Explore all Shariah-compliant contract types
• SDKs - Detailed SDK documentation