Debt Rail

Debt Rail

The Debt Rail provides APIs for managing credit facilities, receivables, repayment schedules, covenant monitoring, and collections operations.

Overview

The Debt Rail covers the full credit facility lifecycle:

Capability	Description
Facility Management	Create and manage revolving and term credit facilities
Drawdown & Repayment	Track utilization, drawdowns, and repayments
Covenant Monitoring	Monitor and track financial covenant compliance
Collections	Manage delinquent accounts and recovery workflows

Endpoints

List Debt Facilities

GET /api/v1/debt/facilities

Lists all credit facilities for the authenticated tenant.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status (draft, submitted, approved, active, delinquent, defaulted, closed)
type	string	Filter by type (revolving, term, overdraft, trade_finance)
customerId	string	Filter by customer entity ID
page	number	Page number (default: 1)
perPage	number	Items per page (default: 20, max: 100)

Create Debt Facility

POST /api/v1/debt/facilities

Creates a new credit facility.

Request Body:

{
  "type": "revolving",
  "customerId": "ent_customer_456",
  "facilityAmount": {
    "amount": 5000000,
    "currency": "SAR"
  },
  "interestBasis": "murabaha",
  "profitRate": 0.055,
  "tenorMonths": 24,
  "purposeCode": "WORKING_CAPITAL",
  "collateral": [
    {
      "type": "real_estate",
      "description": "Commercial property, Riyadh",
      "valuationAmount": { "amount": 8000000, "currency": "SAR" }
    }
  ],
  "covenants": [
    {
      "type": "financial",
      "metric": "debt_service_coverage_ratio",
      "threshold": 1.25,
      "testingFrequency": "quarterly"
    }
  ]
}

Response:

{
  "data": {
    "id": "dbt_fac_abc123",
    "status": "draft",
    "type": "revolving",
    "customerId": "ent_customer_456",
    "facilityAmount": {
      "amount": 5000000,
      "currency": "SAR"
    },
    "utilizedAmount": {
      "amount": 0,
      "currency": "SAR"
    },
    "availableAmount": {
      "amount": 5000000,
      "currency": "SAR"
    },
    "profitRate": 0.055,
    "tenorMonths": 24,
    "expiryDate": "2026-01-15",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Submit Facility for Approval

POST /api/v1/debt/facilities/{id}/submit

Submits a draft facility for credit approval.

Approve Facility

POST /api/v1/debt/facilities/{id}/approve

Approves a submitted credit facility.

Request Body:

{
  "approverNotes": "Approved subject to documentation",
  "approvedAmount": {
    "amount": 5000000,
    "currency": "SAR"
  },
  "conditionsPrecedent": [
    "Execution of facility agreement",
    "Registration of collateral"
  ]
}

Drawdown from Facility

POST /api/v1/debt/facilities/{id}/drawdown

Records a drawdown against an active facility.

Request Body:

{
  "drawdownAmount": {
    "amount": 1000000,
    "currency": "SAR"
  },
  "valueDate": "2024-01-17",
  "purposeNarrative": "Inventory purchase",
  "disbursementAccountId": "acc_operating_001"
}

Response:

{
  "data": {
    "id": "dbt_drw_xyz789",
    "facilityId": "dbt_fac_abc123",
    "drawdownAmount": {
      "amount": 1000000,
      "currency": "SAR"
    },
    "remainingAvailable": {
      "amount": 4000000,
      "currency": "SAR"
    },
    "valueDate": "2024-01-17",
    "status": "disbursed",
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

Repay Facility

POST /api/v1/debt/facilities/{id}/repay

Records a repayment against a facility.

Request Body:

{
  "repaymentAmount": {
    "amount": 250000,
    "currency": "SAR"
  },
  "repaymentDate": "2024-02-15",
  "repaymentType": "scheduled",
  "sourceAccountId": "acc_operating_001"
}

Restructure Facility

POST /api/v1/debt/facilities/{id}/restructure

Initiates a facility restructuring.

Request Body:

{
  "restructureType": "term_extension",
  "newTenorMonths": 36,
  "newProfitRate": 0.06,
  "restructureReason": "Customer cash flow challenges",
  "approvalReference": "RESTR-2024-001"
}

Close Facility

POST /api/v1/debt/facilities/{id}/close

Closes a fully repaid or expired facility.

Request Body:

{
  "closureReason": "fully_repaid",
  "closureDate": "2024-01-15",
  "notes": "Facility repaid in full ahead of schedule"
}

Get Repayment Schedules

GET /api/v1/debt/schedules

Retrieves repayment schedules for facilities.

Query Parameters:

Parameter	Type	Description
facilityId	string	Filter by facility ID
fromDate	string	Filter from date (ISO 8601)
toDate	string	Filter to date (ISO 8601)
status	string	Filter by status (upcoming, due, overdue, paid)

Response:

{
  "data": [
    {
      "id": "sch_001",
      "facilityId": "dbt_fac_abc123",
      "installmentNumber": 1,
      "dueDate": "2024-02-15",
      "principalAmount": { "amount": 200000, "currency": "SAR" },
      "profitAmount": { "amount": 22916, "currency": "SAR" },
      "totalDue": { "amount": 222916, "currency": "SAR" },
      "status": "upcoming"
    }
  ]
}

List Covenants

GET /api/v1/debt/covenants

Lists all covenant definitions and their current test results.

Query Parameters:

Parameter	Type	Description
facilityId	string	Filter by facility ID
status	string	Filter by status (compliant, breached, waived)
type	string	Filter by type (financial, operational, informational)

Create Covenant

POST /api/v1/debt/covenants

Adds a covenant to an existing facility.

Request Body:

{
  "facilityId": "dbt_fac_abc123",
  "type": "financial",
  "metric": "current_ratio",
  "threshold": 1.5,
  "operator": "gte",
  "testingFrequency": "quarterly",
  "waiverAllowed": true
}

List Collections

GET /api/v1/debt/collections

Lists active collections cases.

Query Parameters:

Parameter	Type	Description
facilityId	string	Filter by facility ID
status	string	Filter by status (open, in_progress, resolved, written_off)
daysOverdue	number	Filter by minimum days overdue

Create Collections Case

POST /api/v1/debt/collections

Opens a collections case for a delinquent facility.

Request Body:

{
  "facilityId": "dbt_fac_abc123",
  "overdueAmount": { "amount": 445832, "currency": "SAR" },
  "daysOverdue": 35,
  "collectionStrategy": "negotiated_repayment_plan",
  "assignedOfficer": "usr_collections_001"
}

Facility Lifecycle

stateDiagram-v2
    direction LR

    [*] --> Draft: Create
    Draft --> Submitted: Submit
    Submitted --> Approved: Approve
    Approved --> Active: Activate
    Active --> Delinquent: Missed Payment
    Delinquent --> Active: Cured
    Delinquent --> Defaulted: Escalate
    Active --> Closed: Close
    Defaulted --> Closed: Write Off / Recover

    classDef draft fill:#1565c0,color:#fff,stroke:#1565c0
    classDef submitted fill:#e65100,color:#fff,stroke:#e65100
    classDef approved fill:#2e7d32,color:#fff,stroke:#2e7d32
    classDef active fill:#1a5f4a,color:#fff,stroke:#1a5f4a
    classDef delinquent fill:#f57f17,color:#fff,stroke:#f57f17
    classDef defaulted fill:#c62828,color:#fff,stroke:#c62828
    classDef closed fill:#455a64,color:#fff,stroke:#455a64

    class Draft draft
    class Submitted submitted
    class Approved approved
    class Active active
    class Delinquent delinquent
    class Defaulted defaulted
    class Closed closed

Facility Status

Status	Description
draft	Facility created, pending submission
submitted	Submitted for credit approval
approved	Approved, pending documentation
active	Facility live and available for drawdown
delinquent	Missed repayment, under collections
defaulted	Classified as default
closed	Facility fully repaid or written off

Webhooks

The Debt Rail emits the following webhook events:

Event	Description
debt.facility.created	New facility created
debt.facility.submitted	Facility submitted for approval
debt.facility.approved	Facility approved by credit team
debt.facility.activated	Facility activated and available for drawdown
debt.facility.delinquent	Facility classified as delinquent
debt.facility.defaulted	Facility classified as defaulted
debt.facility.closed	Facility closed
debt.covenant.breached	Covenant threshold breached
debt.collections.case.opened	Collections case opened for delinquent facility
debt.collections.case.resolved	Collections case resolved

Code Examples

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

const client = new IOFClient({ apiKey: process.env.IOF_API_KEY });

// Create a revolving credit facility
const facility = await client.debt.facilities.create({
  type: "revolving",
  customerId: "ent_customer_456",
  facilityAmount: { amount: 5000000, currency: "SAR" },
  interestBasis: "murabaha",
  profitRate: 0.055,
  tenorMonths: 24,
  purposeCode: "WORKING_CAPITAL",
});

// Submit for approval
await client.debt.facilities.submit(facility.id);

// Approve the facility
await client.debt.facilities.approve(facility.id, {
  approverNotes: "Approved subject to documentation",
  approvedAmount: { amount: 5000000, currency: "SAR" },
});

// Record a drawdown
await client.debt.facilities.drawdown(facility.id, {
  drawdownAmount: { amount: 1000000, currency: "SAR" },
  valueDate: "2024-01-17",
  purposeNarrative: "Inventory purchase",
  disbursementAccountId: "acc_operating_001",
});

// Check repayment schedule
const schedule = await client.debt.schedules.list({ facilityId: facility.id });

from iof import IOFClient

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

# Create facility
facility = client.debt.facilities.create(
    type="revolving",
    customer_id="ent_customer_456",
    facility_amount={"amount": 5000000, "currency": "SAR"},
    profit_rate=0.055,
    tenor_months=24,
    purpose_code="WORKING_CAPITAL",
)

# Lifecycle progression
client.debt.facilities.submit(facility.id)
client.debt.facilities.approve(facility.id, approver_notes="Approved")
client.debt.facilities.drawdown(
    facility.id,
    drawdown_amount={"amount": 1000000, "currency": "SAR"},
    value_date="2024-01-17",
)

# Monitor covenants
covenants = client.debt.covenants.list(facility_id=facility.id)

Next Steps

• Risk Rail - Credit risk assessment
• Compliance Rail - Regulatory compliance
• Collections Rail - Case management
• Contracts Rail - Islamic contract lifecycle