The Commodity Financing module enables commodity financing (cars, laptops, etc.) for employees of an organization under a Shariah-compliant murabahah scheme. Two controllers are involved: CommodityFinancingController at /commodity-financings (employee CRUD + sign agreement) and AdminCommodityFinancingController (summary, approve/reject, admin withdraw). The status lifecycle follows a state machine: pending → under_review → legal_agreement → signed → active → completed (with branches for rejected/cancelled). Architecture B: a per-financing holding account is created automatically by the service and owned by the organization — the borrower has no direct claim on the holding account.
Property
Value
Base URL
{HOST}/v1
Auth
Bearer JWT (header Authorization) or cookie access_token
An employee (INDIVIDUAL) submits an application via POST /commodity-financings; organization/MORIA admins can also create one on behalf of the employee (the body uses AdminCreateCommodityFinancingDto). The admin then approves/rejects via PATCH /commodity-financings/:id/approve; after approval, the employee signs the legal agreement via POST /commodity-financings/:id/sign. Auto-deduction then runs from the employee’s source pocket. Admins can withdraw funds from the holding account to forward them to the destination org account.
Method
Path
Auth
Summary
POST
/v1/commodity-financings
bearer
Create a commodity financing (employee or admin-for-employee)
POST
/v1/commodity-financings/:financing_id/sign
bearer
Employee signs the legal agreement
GET
/v1/commodity-financings
bearer
Paginated list with status/user/account filters
GET
/v1/commodity-financings/:financing_id
bearer
Detail of a single financing (response differs for mobile vs web)
PATCH
/v1/commodity-financings/:financing_id
bearer
Update financing parameters (except those already completed)
DELETE
/v1/commodity-financings/:financing_id
bearer
Soft-delete a financing
GET
/v1/summary/commodity-financings
bearer
Organization statistics summary (admin only)
PATCH
/v1/commodity-financings/:financing_id/approve
bearer
Admin approves/rejects an application
POST
/v1/commodity-financings/:financing_id/withdraw
bearer
Admin withdraws from the holding account to the destination org account
Create a commodity financing application. If the caller is INDIVIDUAL, the body uses CreateCommodityFinancingDto. If MORIA/ORGANIZATION admin, the body uses AdminCreateCommodityFinancingDto (with a user_id field). The service decides the path based on user.user_type.
bearercreate-commodity-financingRESOURCE_CREATED
Request body — CreateCommodityFinancingDto (employee)
Paginated list of financings. INDIVIDUAL only sees their own; ORGANIZATION admin sees all within the org; MORIA is unrestricted. The user_id/account_id filters are validated against the caller’s scope — sending an ID outside the scope → 403.
Web / mobile — honors x-client-type (default mobile). See Client types (web vs mobile) for the full rules. Concretely: web nests audit fields as created/updated/deleted{ at, by } objects and replaces relations with formatted account/user/organization objects; mobile returns the raw entity with flat created_at/updated_at + created_by/updated_by/deleted_by and foreign-key ids (account_id, organization_id, user_id). Both clients include product_image_document and legal_agreement — web as a formatted document object ({ id, document_type, document: <url>, … }), mobile as the raw Documents row (or null).
product_image_document is an array of raw Documents rows (product images; [] when none, currently capped at one): e.g. product_image_document: [{ "id": "…", "url": "https://s3-dev.moriafund.com/moria-bucket-dev/image/….jpg", "document_type": "image", "mime_type": "image/jpeg", "size_bytes": 12345, "filename": "…", "visibility": "private", "status": "uploaded", … }]. legal_agreement is a single raw Documents row (or null). In all cases the url is the absolute, ready-to-use public URL — no need to prepend a base. The web shape formats each (product_image_document stays an array of formatted docs).
Audit fields are nested as created/updated/deleted{ at, by }; relations are formatted into account/user/organization objects, and product_image_document/legal_agreement are returned as formatted document objects.
Detail of a single financing. Response differs based on the client (header x-client-type): both variants attach a member_contributions summary; web additionally formats the audit fields and relations.
Web / mobile — honors x-client-type (default mobile). See Client types (web vs mobile) for the full rules. Concretely: web nests audit fields as created/updated/deleted{ at, by } objects and replaces relations with formatted account/user/organization objects; mobile returns the raw entity with flat created_at/updated_at + created_by/updated_by/deleted_by and foreign-key ids (account_id, organization_id, user_id). Both clients include product_image_document and legal_agreement — web as a formatted document object ({ id, document_type, document: <url>, … }), mobile as the raw Documents row (or null). Both attach member_contributions.
Audit fields nested as created/updated/deleted{ at, by }; relations formatted into account/user/organization objects; product_image_document/legal_agreement surfaced; member_contributions still attached.
Aggregate commodity financing statistics for the caller’s organization. Only admins (MORIA/ORGANIZATION) are allowed. Useful for analytics dashboards (totals, status breakdowns, averages).
Admin approves or rejects an application. Sets a new status + (optional) approved_installment_amount + requested_installment_period. Valid statuses: legal_agreement for approve, rejected/cancelled for reject.
Admin withdraws funds from the per-financing holding account to the destination org account. Architecture B: only org admins have access to the holding account; the borrower has no claim. Used to forward funds to a vendor / supplier.
