Embedded Finance Rail

Embedded Islamic finance capabilities for Banking-as-a-Service (BaaS), white-label solutions, and API-first banking integration.

Overview

The Embedded Finance rail enables non-bank platforms — such as e-commerce marketplaces, accounting software, ERP systems, and fintech applications — to embed Shariah-compliant financial services directly into their products. Instead of redirecting users to a separate banking portal, partner platforms offer Islamic finance capabilities natively within their own user experience.

The rail provides a complete BaaS (Banking-as-a-Service) toolkit: virtual IBAN provisioning, Shariah-compliant payment accounts, embedded Murabaha financing at checkout, Takaful insurance widgets, and Zakat calculation modules. Each capability is exposed as a composable API that partners integrate using their own branding and UI.

White-label configuration allows partners to customize product names, fee structures, eligibility rules, and branding elements while the underlying Shariah-compliant infrastructure remains managed by the platform. A single partner integration can offer multiple financial products — a marketplace might embed checkout financing (Murabaha), seller payouts (payments), and merchant working capital (Musharakah) through one API key.

Tenant isolation ensures that each partner’s customers, transactions, and data are fully segregated. The platform handles all regulatory compliance, Shariah governance, and banking partner relationships, allowing partners to focus on their core product while offering financial services.

Endpoints

Register Partner

POST /v1/rails/embedded-finance/partners

const partner = await iof.embeddedFinance.registerPartner({
  name: "ShopHalal Marketplace",
  type: "marketplace",
  website: "https://shophalal.com",
  products_requested: [
    "checkout_financing",
    "merchant_payouts",
    "virtual_accounts",
  ],
  branding: {
    display_name: "ShopHalal Pay",
    primary_color: "#1A6B4A",
    logo_url: "https://shophalal.com/logo.svg",
  },
  contact_email: "partnerships@shophalal.com",
});

Response:

{
  "id": "partner_xyz",
  "name": "ShopHalal Marketplace",
  "status": "PENDING_REVIEW",
  "api_key": "sk_live_partner_xyz_...",
  "sandbox_api_key": "sk_test_partner_xyz_...",
  "products_enabled": [],
  "created_at": "2024-01-15T10:30:00Z"
}

Create Virtual Account

POST /v1/rails/embedded-finance/accounts

const account = await iof.embeddedFinance.createAccount({
  partner_id: "partner_xyz",
  customer_external_id: "shop_customer_12345",
  customer_name: "Fatima Al-Rashid",
  account_type: "payment",
  currency: "SAR",
});

Initiate Checkout Financing

POST /v1/rails/embedded-finance/financing/checkout

const financing = await iof.embeddedFinance.checkoutFinancing({
  partner_id: "partner_xyz",
  customer_external_id: "shop_customer_12345",
  order_reference: "ORD-2024-78901",
  amount: 3000,
  currency: "SAR",
  structure: "murabaha",
  installments: 6,
  items: [{ name: "Laptop", quantity: 1, price: 3000 }],
});

Response:

{
  "id": "emb_fin_xyz",
  "type": "checkout_financing",
  "structure": "murabaha",
  "status": "APPROVED",
  "amount": 3000,
  "profit_amount": 150,
  "total_payable": 3150,
  "currency": "SAR",
  "installments": 6,
  "installment_amount": 525,
  "first_due_date": "2024-02-15",
  "approval_url": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Get Partner Configuration

GET /v1/rails/embedded-finance/partners/:id/config

Update White-Label Branding

PUT /v1/rails/embedded-finance/partners/:id/branding

List Partner Transactions

GET /v1/rails/embedded-finance/partners/:id/transactions

Get Customer Portfolio (Partner View)

GET /v1/rails/embedded-finance/customers/:external_id/portfolio

Generate Partner Settlement Report

POST /v1/rails/embedded-finance/partners/:id/settlements

Partner Types

Type	Description
`marketplace`	E-commerce marketplace with buyer/seller flows
`erp`	Enterprise resource planning integration
`accounting`	Accounting software integration
`fintech`	Fintech app embedding financial services
`neobank`	White-label neobank built on IOF

Embeddable Products

Product	Islamic Structure	Description
`checkout_financing`	Murabaha	Buy-now-pay-later at checkout
`merchant_payouts`	Wakalah	Automated seller fund settlement
`virtual_accounts`	Wadiah	Customer payment accounts
`working_capital`	Musharakah	Merchant financing facility
`micro_takaful`	Takaful	Embedded insurance coverage
`zakat_widget`	Zakat	Zakat calculation and payment
`savings_pots`	Mudarabah	Goal-based savings accounts

Partner Status

Status	Description
`PENDING_REVIEW`	Application under compliance review
`SANDBOX`	Approved for sandbox testing only
`ACTIVE`	Live in production
`SUSPENDED`	Temporarily suspended
`TERMINATED`	Partnership terminated

Integration Points

Murabaha Rail — underlying contracts for checkout financing
Payments Rail — payment processing for all embedded transactions
KYC Rail — customer onboarding and verification
Compliance Rail — partner and transaction compliance monitoring
Billing Rail — partner fee calculation and settlement
API Keys Rail — partner API key management and scoping

Webhooks

Event	Description
`embedded_finance.partner.approved`	Partner approved for production
`embedded_finance.account.created`	Virtual account provisioned
`embedded_finance.financing.approved`	Checkout financing approved
`embedded_finance.financing.disbursed`	Financing funds released
`embedded_finance.financing.repaid`	Financing installment paid
`embedded_finance.settlement.completed`	Partner settlement processed

Standards

Next Steps

Murabaha Rail - Cost-plus financing contracts
Payments Rail - Payment processing
API Keys Rail - API key management