Hawalah Rail

Debt transfer contract endpoints for Islamic payment and remittance services.

Overview

The Hawalah rail provides:

Debt transfer contract creation and management
Creditor-initiated and debtor-initiated transfer support
Multi-party debt assignment workflows
Settlement tracking and confirmation

Hawalah is a contract for the transfer of a debt obligation from one debtor to another. The original debtor (Muhil) transfers their liability to a third party (Muhal Alayh) who assumes the obligation to pay the creditor (Muhal). Once the transfer is complete, the original debtor is discharged from the obligation.

This contract is one of the oldest financial instruments in Islamic commercial law and forms the basis of modern remittance services, bill of exchange mechanisms, and payment transfers. It enables efficient settlement of debts without the physical transfer of money between all parties.

Hawalah may be conditional (Hawalah Muqayyadah), where the new debtor’s obligation is tied to a specific receivable they owe the original debtor, or unconditional (Hawalah Mutlaqah), where the new debtor assumes the obligation regardless of any existing debt relationship.

Endpoints

Create Hawalah Contract

POST /v1/rails/hawalah/contracts

const contract = await iof.hawalah.create({
  hawalah_type: "conditional",
  description: "Trade payable transfer - Invoice INV-2025-001",
  original_debtor_id: "cpty_buyer",
  new_debtor_id: "cpty_distributor",
  creditor_id: "cpty_supplier",
  transfer_amount: 75000,
  currency: "USD",
  underlying_receivable: {
    reference: "INV-2025-042",
    amount: 75000,
    due_date: "2025-04-15",
  },
});

Response:

{
  "id": "hwl_xyz",
  "type": "hawalah",
  "subtype": "conditional",
  "status": "DRAFT",
  "transfer_amount": 75000,
  "currency": "USD",
  "original_debtor_id": "cpty_buyer",
  "new_debtor_id": "cpty_distributor",
  "creditor_id": "cpty_supplier",
  "underlying_receivable": {
    "reference": "INV-2025-042",
    "amount": 75000,
    "due_date": "2025-04-15"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Get Hawalah Contract

GET /v1/rails/hawalah/contracts/:id

List Hawalah Contracts

GET /v1/rails/hawalah/contracts

Execute Hawalah Contract

POST /v1/rails/hawalah/contracts/:id/execute

Confirm Settlement

POST /v1/rails/hawalah/contracts/:id/confirm-settlement

Contract Types

Type	Description
`conditional`	Transfer tied to an existing receivable (Muqayyadah)
`unconditional`	Transfer not tied to any existing debt (Mutlaqah)

Contract Status

Status	Description
`DRAFT`	Contract created, pending review
`PENDING_SHARIAH_REVIEW`	Awaiting Shariah board approval
`PENDING_CONSENT`	Awaiting consent from all parties
`SHARIAH_APPROVED`	Approved by Shariah board
`ACTIVE`	Debt transferred, awaiting settlement
`SETTLED`	New debtor has paid the creditor
`COMPLETED`	Transfer confirmed and closed
`TERMINATED`	Contract terminated early

Shariah Compliance

The original debt must be valid, known, and enforceable
All parties (original debtor, new debtor, creditor) must consent to the transfer
Once executed, the original debtor is discharged from the obligation
The creditor has recourse only against the new debtor after execution
In conditional Hawalah, the underlying receivable must exist and be valid
The transfer amount must be known and denominated in the same currency as the original debt

Webhooks

Event	Description
`hawalah.contract.created`	Contract created
`hawalah.consent.received`	Party consent received
`hawalah.contract.executed`	Debt transferred
`hawalah.settlement.confirmed`	Payment settled
`hawalah.contract.completed`	Transfer completed and closed

Standards

Next Steps

Kafalah Rail - Guarantee contracts
Clearing Rail - Settlement and clearing
Contracts Rail - General contract management