Quickstart

This guide walks through creating a Murabaha financing contract, recording the asset purchase, generating a repayment schedule, processing a payment, and checking the contract status using the REST API.

Prerequisites

• A Kora Islamic Banking account (sign up)
• Your API key (starts with test_ for sandbox)
• Your Tenant ID (UUID from your dashboard)

Step 1: Create a Murabaha contract

Define the financing terms including cost price, markup, and tenor.

cURL

curl -X POST https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts \
  -H "Authorization: Bearer $IB_API_KEY" \
  -H "X-Tenant-ID: $IB_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "product_type": "ASSET_MURABAHA",
    "asset_description": "Toyota Hilux 2026",
    "cost_price": 15000000.00,
    "markup_rate": 0.15,
    "selling_price": 17250000.00,
    "currency": "NGN",
    "tenor_months": 36,
    "repayment_frequency": "MONTHLY",
    "disbursement_account_id": "660e8400-e29b-41d4-a716-446655440001"
  }'

Node.js

const response = await fetch("https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.IB_API_KEY}`,
    "X-Tenant-ID": process.env.IB_TENANT_ID,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: "550e8400-e29b-41d4-a716-446655440000",
    product_type: "ASSET_MURABAHA",
    asset_description: "Toyota Hilux 2026",
    cost_price: 15000000.00,
    markup_rate: 0.15,
    selling_price: 17250000.00,
    currency: "NGN",
    tenor_months: 36,
    repayment_frequency: "MONTHLY",
    disbursement_account_id: "660e8400-e29b-41d4-a716-446655440001",
  }),
});

const contract = await response.json();
console.log(contract.id); // "a1b2c3d4-..."

Python

import requests
import os

response = requests.post(
    "https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts",
    headers={
        "Authorization": f"Bearer {os.environ['IB_API_KEY']}",
        "X-Tenant-ID": os.environ["IB_TENANT_ID"],
    },
    json={
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "product_type": "ASSET_MURABAHA",
        "asset_description": "Toyota Hilux 2026",
        "cost_price": 15000000.00,
        "markup_rate": 0.15,
        "selling_price": 17250000.00,
        "currency": "NGN",
        "tenor_months": 36,
        "repayment_frequency": "MONTHLY",
        "disbursement_account_id": "660e8400-e29b-41d4-a716-446655440001",
    },
)

contract = response.json()
print(contract["id"])  # "a1b2c3d4-..."

Go

req := islamicbanking.CreateMurabahaRequest{
    CustomerID:            "550e8400-e29b-41d4-a716-446655440000",
    ProductType:           "ASSET_MURABAHA",
    AssetDescription:      "Toyota Hilux 2026",
    CostPrice:             15000000.00,
    MarkupRate:            0.15,
    SellingPrice:          17250000.00,
    Currency:              "NGN",
    TenorMonths:           36,
    RepaymentFrequency:    "MONTHLY",
    DisbursementAccountID: "660e8400-e29b-41d4-a716-446655440001",
}
contract, err := client.CreateMurabahaContract(ctx, req)
fmt.Println(contract.ID) // "a1b2c3d4-..."

Save the returned id — you'll use it for all subsequent operations.

Step 2: Record asset purchase

Confirm the bank has purchased the asset from the supplier.

cURL

curl -X POST https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/$CONTRACT_ID/purchase \
  -H "Authorization: Bearer $IB_API_KEY" \
  -H "X-Tenant-ID: $IB_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_name": "Toyota Nigeria Ltd",
    "purchase_date": "2026-04-07T00:00:00Z",
    "purchase_price": 15000000.00,
    "invoice_reference": "INV-2026-0042"
  }'

Node.js

await fetch(
  `https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/${contractId}/purchase`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.IB_API_KEY}`,
      "X-Tenant-ID": process.env.IB_TENANT_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      supplier_name: "Toyota Nigeria Ltd",
      purchase_date: "2026-04-07T00:00:00Z",
      purchase_price: 15000000.00,
      invoice_reference: "INV-2026-0042",
    }),
  }
);

Python

requests.post(
    f"https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/{contract_id}/purchase",
    headers={
        "Authorization": f"Bearer {os.environ['IB_API_KEY']}",
        "X-Tenant-ID": os.environ["IB_TENANT_ID"],
    },
    json={
        "supplier_name": "Toyota Nigeria Ltd",
        "purchase_date": "2026-04-07T00:00:00Z",
        "purchase_price": 15000000.00,
        "invoice_reference": "INV-2026-0042",
    },
)

Go

err := client.RecordAssetPurchase(ctx, contractID, islamicbanking.PurchaseRequest{
    SupplierName:     "Toyota Nigeria Ltd",
    PurchaseDate:     time.Date(2026, 4, 7, 0, 0, 0, 0, time.UTC),
    PurchasePrice:    15000000.00,
    InvoiceReference: "INV-2026-0042",
})

Step 3: Generate repayment schedule

cURL

curl https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/$CONTRACT_ID/schedule \
  -H "Authorization: Bearer $IB_API_KEY" \
  -H "X-Tenant-ID: $IB_TENANT_ID"

Node.js

const schedule = await fetch(
  `https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/${contractId}/schedule`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.IB_API_KEY}`,
      "X-Tenant-ID": process.env.IB_TENANT_ID,
    },
  }
);

const data = await schedule.json();
console.log(data.installments.length); // 36
console.log(data.installments[0].amount); // 479166.67

Python

schedule = requests.get(
    f"https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/{contract_id}/schedule",
    headers={
        "Authorization": f"Bearer {os.environ['IB_API_KEY']}",
        "X-Tenant-ID": os.environ["IB_TENANT_ID"],
    },
)

data = schedule.json()
print(len(data["installments"]))  # 36
print(data["installments"][0]["amount"])  # 479166.67

Go

schedule, err := client.GetRepaymentSchedule(ctx, contractID)
fmt.Println(len(schedule.Installments)) // 36
fmt.Println(schedule.Installments[0].Amount) // 479166.67

Step 4: Process a repayment

cURL

curl -X POST https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/$CONTRACT_ID/payments \
  -H "Authorization: Bearer $IB_API_KEY" \
  -H "X-Tenant-ID: $IB_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 479166.67,
    "payment_date": "2026-05-07T00:00:00Z",
    "payment_reference": "PAY-2026-001",
    "source_account_id": "660e8400-e29b-41d4-a716-446655440001"
  }'

Node.js

const payment = await fetch(
  `https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/${contractId}/payments`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.IB_API_KEY}`,
      "X-Tenant-ID": process.env.IB_TENANT_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 479166.67,
      payment_date: "2026-05-07T00:00:00Z",
      payment_reference: "PAY-2026-001",
      source_account_id: "660e8400-e29b-41d4-a716-446655440001",
    }),
  }
);

const result = await payment.json();
console.log(result.outstanding_balance); // 16770833.33

Python

payment = requests.post(
    f"https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/{contract_id}/payments",
    headers={
        "Authorization": f"Bearer {os.environ['IB_API_KEY']}",
        "X-Tenant-ID": os.environ["IB_TENANT_ID"],
    },
    json={
        "amount": 479166.67,
        "payment_date": "2026-05-07T00:00:00Z",
        "payment_reference": "PAY-2026-001",
        "source_account_id": "660e8400-e29b-41d4-a716-446655440001",
    },
)

result = payment.json()
print(result["outstanding_balance"])  # 16770833.33

Go

result, err := client.ProcessPayment(ctx, contractID, islamicbanking.PaymentRequest{
    Amount:           479166.67,
    PaymentDate:      time.Date(2026, 5, 7, 0, 0, 0, 0, time.UTC),
    PaymentReference: "PAY-2026-001",
    SourceAccountID:  "660e8400-e29b-41d4-a716-446655440001",
})
fmt.Println(result.OutstandingBalance) // 16770833.33

Step 5: Check contract status

cURL

curl https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/$CONTRACT_ID \
  -H "Authorization: Bearer $IB_API_KEY" \
  -H "X-Tenant-ID: $IB_TENANT_ID"

Node.js

const contract = await fetch(
  `https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/${contractId}`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.IB_API_KEY}`,
      "X-Tenant-ID": process.env.IB_TENANT_ID,
    },
  }
);

const data = await contract.json();
console.log(data.status);              // "ACTIVE"
console.log(data.total_paid);          // 479166.67
console.log(data.outstanding_balance); // 16770833.33
console.log(data.next_due_date);       // "2026-06-07"

Python

contract = requests.get(
    f"https://api.korastratum.com/islamic-banking/api/v1/murabaha/contracts/{contract_id}",
    headers={
        "Authorization": f"Bearer {os.environ['IB_API_KEY']}",
        "X-Tenant-ID": os.environ["IB_TENANT_ID"],
    },
)

data = contract.json()
print(data["status"])              # "ACTIVE"
print(data["total_paid"])          # 479166.67
print(data["outstanding_balance"]) # 16770833.33
print(data["next_due_date"])       # "2026-06-07"

Go

contract, err := client.GetMurabahaContract(ctx, contractID)
fmt.Println(contract.Status)             // "ACTIVE"
fmt.Println(contract.TotalPaid)          // 479166.67
fmt.Println(contract.OutstandingBalance) // 16770833.33
fmt.Println(contract.NextDueDate)        // "2026-06-07"

What's next

• Authentication — API key formats, environments, and rate limits
• API Reference — Explore every endpoint across all Islamic finance products