Banking Rail

Core Islamic banking services spanning retail, corporate, SME, and digital banking operations.

Overview

The Banking rail provides foundational banking capabilities built on Islamic finance principles. It manages customer accounts, deposit products, financing facilities, and day-to-day banking operations for institutions offering retail, corporate, SME, or digital-only banking services.

Deposit accounts are structured using Wadiah (safekeeping) for current accounts and Mudarabah (profit-sharing) for savings and investment accounts. Unlike conventional interest-bearing deposits, Mudarabah accounts share actual profits generated by the bank’s Shariah-compliant investment activities, with the profit-sharing ratio agreed upon at account opening. Wadiah accounts may receive Hibah (discretionary gifts) from the bank but depositors have no contractual right to returns.

The corporate and SME banking modules extend the core with working capital facilities (Murabaha, Musharakah), trade finance integration, cash management, and multi-signatory approval workflows. Digital banking capabilities include virtual card issuance, QR code payments, open banking API access, and real-time notifications.

All banking operations pass through the Compliance rail for AML/CFT screening and the Shariah Governance rail for product approval, ensuring that every account, transaction, and product offering maintains full regulatory and Shariah compliance.

Endpoints

Open Account

POST /v1/rails/banking/accounts

const account = await iof.banking.openAccount({
  customer_id: "cust_001",
  type: "savings",
  structure: "mudarabah",
  currency: "SAR",
  profit_sharing_ratio: { customer: 0.6, bank: 0.4 },
  initial_deposit: 10000,
  tier: "premium",
});

Response:

{
  "id": "acct_xyz",
  "account_number": "SA0380000000608010167519",
  "type": "savings",
  "structure": "mudarabah",
  "status": "ACTIVE",
  "currency": "SAR",
  "balance": 10000,
  "profit_sharing_ratio": { "customer": 0.6, "bank": 0.4 },
  "tier": "premium",
  "iban": "SA0380000000608010167519",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Account

GET /v1/rails/banking/accounts/:id

List Accounts

GET /v1/rails/banking/accounts

Get Account Balance

GET /v1/rails/banking/accounts/:id/balance

Get Account Statement

GET /v1/rails/banking/accounts/:id/statement

const statement = await iof.banking.getStatement({
  account_id: "acct_xyz",
  from_date: "2024-01-01",
  to_date: "2024-01-31",
  format: "json",
});

Create Financing Facility

POST /v1/rails/banking/facilities

const facility = await iof.banking.createFacility({
  customer_id: "cust_corp_001",
  type: "working_capital",
  structure: "murabaha",
  limit: 500000,
  currency: "SAR",
  tenor_months: 12,
  purpose: "Inventory procurement for Q1 2024",
  collateral: [
    {
      type: "property",
      value: 750000,
      description: "Warehouse - Industrial City",
    },
  ],
});

Draw Down Facility

POST /v1/rails/banking/facilities/:id/drawdowns

Issue Virtual Card

POST /v1/rails/banking/cards/virtual

Freeze Account

POST /v1/rails/banking/accounts/:id/freeze

Close Account

POST /v1/rails/banking/accounts/:id/close

Calculate Profit Distribution

POST /v1/rails/banking/accounts/profit-distribution

Calculate and distribute Mudarabah profits to savings/investment account holders.

Account Types

Type	Islamic Structure	Description
`current`	Wadiah	Safekeeping account, no profit share
`savings`	Mudarabah	Profit-sharing savings account
`investment`	Mudarabah	Fixed-term investment deposit
`business`	Wadiah/Mudarabah	Business operating account
`escrow`	Amanah	Trust/escrow holding account

Facility Types

Type	Islamic Structure	Description
`working_capital`	Murabaha/Musharakah	Short-term business financing
`term_financing`	Murabaha	Medium to long-term financing
`trade_finance`	Wakalah/Murabaha	Import/export financing
`project_finance`	Musharakah/Istisna	Large-scale project financing
`personal_finance`	Murabaha	Retail consumer financing
`home_finance`	Diminishing Musharakah	Residential property financing

Account Status

Status	Description
`PENDING`	Account opening in progress
`ACTIVE`	Account open and operational
`DORMANT`	No activity for defined period
`FROZEN`	Frozen by compliance or court order
`CLOSED`	Account closed

Banking Segments

Segment	Description
`retail`	Individual customers, personal accounts
`sme`	Small and medium enterprises
`corporate`	Large corporations, multi-signatory workflows
`private`	High-net-worth individuals, wealth management
`digital`	Digital-only banking, API-first access

Integration Points

Ledger Rail — real-time balance and transaction tracking
Payments Rail — fund transfers, bill payments, standing orders
KYC Rail — customer onboarding and ongoing due diligence
Compliance Rail — AML/CFT transaction monitoring
Murabaha Rail — underlying contracts for financing facilities
Musharakah Rail — partnership-based financing structures
Shariah Governance Rail — product approval and periodic review
Cards Rail — debit and prepaid card management

Webhooks

Event	Description
`banking.account.opened`	Account successfully opened
`banking.account.closed`	Account closed
`banking.account.frozen`	Account frozen
`banking.facility.created`	Financing facility established
`banking.facility.drawdown`	Facility drawdown processed
`banking.profit.distributed`	Mudarabah profit distributed
`banking.card.issued`	Virtual or physical card issued
`banking.statement.ready`	Account statement generated

Standards

Next Steps

Murabaha Rail - Cost-plus financing
Musharakah Rail - Partnership financing
Payments Rail - Payment processing
KYC Rail - Customer onboarding