Wadiah Rail

Safekeeping deposit contract endpoints for Islamic custody and savings accounts.

Overview

The Wadiah rail provides:

Safekeeping deposit contract creation and management
Wadiah Yad Amanah (pure safekeeping) support
Wadiah Yad Dhamanah (guaranteed custody with permission to use) support
Hibah (discretionary gift) distribution to depositors

Wadiah is a safekeeping contract where one party entrusts assets or funds to another for custody. In its basic form (Yad Amanah), the custodian holds the deposit as a trust and is not liable for loss except in cases of negligence. The custodian may not use the deposited funds.

In Wadiah Yad Dhamanah, the depositor grants the custodian permission to use the funds. The custodian guarantees the full return of the deposit and may, at their sole discretion, offer a gift (Hibah) to the depositor as a token of appreciation. This form is widely used for Islamic savings and current accounts.

The key distinction from conventional deposits is that no return is promised or contractually obligated. Any gift from the custodian is entirely voluntary and cannot be stipulated as a condition of the contract.

Endpoints

Create Wadiah Contract

POST /v1/rails/wadiah/contracts

const contract = await iof.wadiah.create({
  wadiah_type: "yad_dhamanah",
  description: "Savings account deposit",
  deposit_amount: 50000,
  currency: "USD",
  depositor_id: "cpty_customer",
  custodian_id: "cpty_institution",
  permissions: {
    use_funds: true,
    commingling: true,
  },
});

Response:

{
  "id": "wdh_xyz",
  "type": "wadiah",
  "subtype": "yad_dhamanah",
  "status": "DRAFT",
  "deposit_amount": 50000,
  "currency": "USD",
  "guaranteed_return": 50000,
  "hibah_history": [],
  "created_at": "2024-01-15T10:30:00Z"
}

Get Wadiah Contract

GET /v1/rails/wadiah/contracts/:id

List Wadiah Contracts

GET /v1/rails/wadiah/contracts

Execute Wadiah Contract

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

Distribute Hibah

POST /v1/rails/wadiah/contracts/:id/distribute-hibah

Withdraw Deposit

POST /v1/rails/wadiah/contracts/:id/withdraw

Contract Types

Type	Description
`yad_amanah`	Pure safekeeping, custodian may not use funds
`yad_dhamanah`	Guaranteed custody, custodian permitted to use funds

Contract Status

Status	Description
`DRAFT`	Contract created, pending review
`PENDING_SHARIAH_REVIEW`	Awaiting Shariah board approval
`SHARIAH_APPROVED`	Approved by Shariah board
`ACTIVE`	Deposit held in custody
`COMPLETED`	Full deposit returned to depositor
`TERMINATED`	Contract terminated early

Shariah Compliance

The custodian must guarantee the full return of the deposit in Yad Dhamanah
No return or profit may be promised or stipulated in the contract
Hibah (gift) is entirely at the custodian’s discretion and cannot be pre-agreed
Regular or patterned Hibah payments must not create an expectation of return
In Yad Amanah, the custodian is not liable for loss except due to negligence
The depositor may withdraw funds at any time without penalty

Webhooks

Event	Description
`wadiah.contract.created`	Contract created
`wadiah.contract.executed`	Deposit placed in custody
`wadiah.hibah.distributed`	Discretionary gift given
`wadiah.withdrawal.processed`	Withdrawal processed
`wadiah.contract.completed`	Full deposit returned

Standards

Next Steps

Qard Rail - Interest-free loan
Kafalah Rail - Guarantee contracts
Contracts Rail - General contract management