Payments Rail

Payment processing, gateway integration, and fund transfer orchestration for Islamic finance.

Overview

The Payments rail handles all monetary movements across the platform, providing a unified interface for initiating, routing, and settling payments. It supports bank transfers, card payments, digital wallets, and real-time payment networks while ensuring that all payment flows comply with Shariah principles — no interest charges on late payments, and any late-payment penalties are directed to charity.

The rail acts as a payment orchestration layer that abstracts multiple payment service providers (PSPs) and banking networks behind a single API. Payment requests are routed based on currency, geography, amount, and cost optimization rules. The routing engine supports fallback providers, split payments, and multi-currency settlement.

For recurring payments such as Murabaha installments, Ijarah rentals, and fund subscriptions, the rail manages scheduled payment collection with retry logic, grace periods, and automatic reconciliation against the originating contract. Failed payments trigger configurable workflows including notifications, grace extensions, and escalation.

All payment transactions are immutably recorded in the Ledger rail with full traceability from initiation through clearing to final settlement. The Reconciliation rail performs daily matching of payment records against bank statements.

Endpoints

Initiate Payment

POST /v1/rails/payments

const payment = await iof.payments.create({
  amount: 15000,
  currency: "SAR",
  source: {
    type: "bank_account",
    account_id: "acc_src_001",
  },
  destination: {
    type: "bank_account",
    account_id: "acc_dst_002",
  },
  reference: "mur_xyz_installment_12",
  rail_reference: { rail: "murabaha", contract_id: "mur_xyz" },
  idempotency_key: "pay_idem_abc123",
});

Response:

{
  "id": "pay_xyz",
  "status": "PROCESSING",
  "amount": 15000,
  "currency": "SAR",
  "source_account": "acc_src_001",
  "destination_account": "acc_dst_002",
  "reference": "mur_xyz_installment_12",
  "provider": "sarie",
  "estimated_settlement": "2024-01-15T14:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Payment

GET /v1/rails/payments/:id

List Payments

GET /v1/rails/payments

Create Scheduled Payment

POST /v1/rails/payments/schedules

const schedule = await iof.payments.createSchedule({
  amount: 1350,
  currency: "USD",
  source_account_id: "acc_src_001",
  destination_account_id: "acc_dst_002",
  frequency: "monthly",
  start_date: "2024-02-01",
  total_payments: 36,
  rail_reference: { rail: "murabaha", contract_id: "mur_xyz" },
});

Cancel Payment

POST /v1/rails/payments/:id/cancel

Refund Payment

POST /v1/rails/payments/:id/refund

Get Payment Methods

GET /v1/rails/payments/methods

List available payment methods for a tenant or customer.

Simulate Payment (Sandbox)

POST /v1/rails/payments/simulate

Payment Methods

Method	Description
`bank_transfer`	Direct bank-to-bank transfer
`card`	Debit or prepaid card payment
`wallet`	Digital wallet (Apple Pay, mada Pay)
`sarie`	Saudi real-time payment network
`swift`	International SWIFT transfer
`internal`	Intra-platform ledger transfer

Payment Status

Status	Description
`PENDING`	Payment created, not yet submitted
`PROCESSING`	Submitted to payment network
`COMPLETED`	Funds settled at destination
`FAILED`	Payment failed (insufficient funds, etc)
`CANCELLED`	Cancelled before processing
`REFUNDED`	Full or partial refund issued

Integration Points

Ledger Rail — immutable record of all payment transactions
Reconciliation Rail — daily matching against bank statements
Murabaha Rail — installment payment collection
Ijarah Rail — rental payment collection
Funds Rail — subscription and redemption payments
Sadaqah Rail — donation payment processing
Notifications Rail — payment confirmations and failure alerts

Webhooks

Event	Description
`payments.created`	Payment initiated
`payments.completed`	Payment settled
`payments.failed`	Payment failed
`payments.refunded`	Refund processed
`payments.schedule.created`	Recurring schedule established
`payments.schedule.executed`	Scheduled payment executed
`payments.schedule.failed`	Scheduled payment failed

Standards

Next Steps

Ledger Rail - Transaction ledger
Reconciliation Rail - Payment matching
ISO 20022 Rail - Payment messaging standards