Commodity Financing

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
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	accounts, users, organizations, payments (payback), withdrawal, document
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

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

Auth + scope notes

• Every endpoint requires Bearer JWT plus the matching permission. There are no @Public() endpoints.
• INDIVIDUAL may only access their own financing; user_id/account_id filters are forced to their own data.
• ORGANIZATION admins may access all financings in their organization; sending a user_id from another org → 403.
• MORIA superadmin is unrestricted; admin endpoints (summary, approve, withdraw) are limited by @Roles(MORIA, ORGANIZATION).
• The account_id field no longer exists on the create DTO — Architecture B: the holding account is created automatically by the service.

---

POST /v1/commodity-financings bearer

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.

bearer create-commodity-financing RESOURCE_CREATED

Request body — CreateCommodityFinancingDto (employee)

Field	Type	Required	Notes
product_name	string	yes	Product name (e.g. Tesla Car)
product_price	string	yes	Product price as a string (rupiah)
product_link	string	yes	Product reference URL
requested_installment_amount	string	optional	Requested installment amount
requested_installment_period	number	optional	Number of installment months (Min(1))
status	enum CommodityFinancingStatus	optional	Default pending
legal_agreement_signed	boolean	optional	Default false
deduction_date	string (ISO 8601)	optional	Auto-deduction date

Request body — AdminCreateCommodityFinancingDto (admin-for-employee)

Field	Type	Required	Notes
user_id	UUID	yes	Borrower the financing is created for
product_name, product_price, product_link	string	yes	Same as the employee DTO
requested_installment_amount	string	optional
approved_installment_amount	string	optional	Admin can set the approved amount directly
requested_installment_period	number	optional	Min(1)
status	enum CommodityFinancingStatus	optional
legal_agreement_signed	boolean	optional
completed	boolean	optional
deduction_date	string (ISO 8601)	optional

Example request (employee)

{
  "product_name": "Tesla Car",
  "product_price": "240000000",
  "product_link": "https://teslacar123.com",
  "requested_installment_amount": "1000000",
  "requested_installment_period": 24
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Commodity financing created successfully",
  "data": {
    "commodityFinance": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "account_id": "123e4567-e89b-12d3-a456-426614174001",
      "organization_id": "123e4567-e89b-12d3-a456-426614174002",
      "user_id": "123e4567-e89b-12d3-a456-426614174003",
      "product_name": "Tesla Car",
      "slug_product_name": "tesla_car",
      "product_price": "240000000.0000",
      "reselling_price": "0.0000",
      "product_link": "https://teslacar123.com",
      "approved_installment_amount": "0.00",
      "requested_installment_amount": "1000000.00",
      "paid_amount": "0.00",
      "remaining_amount": "240000000.00",
      "requested_installment_period": 24,
      "approved_installment_period": 0,
      "status": "pending",
      "legal_agreement_signed": false,
      "deduction_date": null,
      "deduction_failed_attempts": 0,
      "deduction_next_retry_date": null,
      "created_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed / account not linked to user
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing create-commodity-financing permission
404 Not Found	Account or user not found

Side effects

• Creates a commodity_financings row with initial status pending.
• Creates a per-financing holding accounts row (org-owned, account_type=COMMODITY_FINANCING) atomically.
• Emits BusinessEvent RESOURCE_CREATED (impact MEDIUM).

---

POST /v1/commodity-financings/:financing_id/sign bearer

Employee signs the legal agreement for a financing already in status legal_agreement. Moves the status to signed / active per the service logic.

bearer sign-commodity-financing RESOURCE_UPDATED

Path params

Param	Type	Notes
financing_id	UUID	Financing ID — validated by ParseUUIDPipe

Request body — SignAgreementDto

Field	Type	Required	Notes
legal_agreement_signed	boolean	yes	Set to true to sign

Example request

{ "legal_agreement_signed": true }

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Legal agreement signed successfully",
  "data": { "commodityFinance": { "...": "CommodityFinancingDto shape, status=signed/active" } }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not the owner / status invalid for signing
404 Not Found	Financing not found

---

GET /v1/commodity-financings bearer

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.

bearer read-commodity-financing

Query params

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
status	enum CommodityFinancingStatus	optional	pending, under_review, rejected, legal_agreement, cancelled, signed, active, completed
order	'asc' | 'desc'	optional	Sort by created_at
user_id	string (UUID)	optional	Filter by user; INDIVIDUAL may only use their own user.id; ORGANIZATION admin only users from their org
account_id	string (UUID)	optional	Filter by account; INDIVIDUAL only their own account; ORGANIZATION admin only accounts from their org

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Commodity financings fetched successfully",
  "data": {
    "limit": 10,
    "count": 100,
    "currentPage": 1,
    "totalPages": 10,
    "commodityFinancings": [
      { "id": "123e4567-e89b-12d3-a456-426614174000", "product_name": "Laptop Dell Inspiron", "product_price": "15000000.0000", "status": "active", "...": "CommodityFinancingDto shape" }
    ]
  }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	INDIVIDUAL sends another user’s user_id/account_id · ORGANIZATION admin sends a user/account from another org

---

GET /v1/commodity-financings/:financing_id bearer

Detail of a single financing. Response differs based on the client (header x-client-type): MOBILE gets member_contributions via the with-summary variant; WEB gets the formatted variant.

bearer read-commodity-financing

Path params

Param	Type	Notes
financing_id	UUID	Financing ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "commodity finance fetched successfully",
  "data": {
    "commodityFinance": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "product_name": "Laptop Dell Inspiron",
      "product_price": "15000000.0000",
      "reselling_price": "16500000.0000",
      "approved_installment_amount": "1500000.00",
      "paid_amount": "4500000.00",
      "remaining_amount": "12000000.00",
      "approved_installment_period": 12,
      "status": "active",
      "legal_agreement_signed": true,
      "deduction_date": "2026-01-15",
      "deduction_failed_attempts": 0,
      "deduction_next_retry_date": null
    }
  }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	INDIVIDUAL viewing another user’s financing
404 Not Found	Financing not found

---

PATCH /v1/commodity-financings/:financing_id bearer

Update financing parameters. Cannot update a financing already completed. All fields are optional — send only what changed.

bearer update-commodity-financing RESOURCE_UPDATED

Path params

Param	Type	Notes
financing_id	UUID	Financing ID

Request body — UpdateCommodityFinancingDto

Field	Type	Notes
product_name	string	New product name
product_price	string	New product price
reselling_price	string	Reselling price (murabahah markup)
product_link	string	New product URL
approved_installment_amount	string	Approved installment amount
approved_installment_period	number	Approved installment period (Min(1))
deduction_date	string (ISO 8601)	New auto-deduction date
status	enum CommodityFinancingStatus	New status

Example request

{
  "approved_installment_amount": "1200000",
  "approved_installment_period": 18
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Commodity financing updated successfully",
  "data": { "commodityFinance": { "...": "CommodityFinancingDto shape" } }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Financing already completed
404 Not Found	Financing not found

---

DELETE /v1/commodity-financings/:financing_id bearer

Soft-delete a financing (set deleted_at). Cannot delete a financing already completed.

bearer delete-commodity-financing RESOURCE_DELETED

Path params

Param	Type	Notes
financing_id	UUID	Financing ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Commodity financing deleted successfully"
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Financing already completed
404 Not Found	Financing not found

Side effects

• Emits BusinessEvent RESOURCE_DELETED (impact HIGH).
• Holding account balance is handled per service logic (not permanently deleted).

---

GET /v1/summary/commodity-financings bearer

Aggregate commodity financing statistics for the caller’s organization. Only admins (MORIA/ORGANIZATION) are allowed. Useful for analytics dashboards (totals, status breakdowns, averages).

bearer MORIA, ORGANIZATION read-commodity-financing

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "commodity financing summary fetched successfully",
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_name": "Acme Corporation",
    "total_financings": "50",
    "total_product_value": "750000000.00",
    "total_approved_installment_amount": "75000000.00",
    "pending_financings": "5",
    "under_review_financings": "8",
    "rejected_financings": "3",
    "legal_agreement_financings": "6",
    "cancelled_financings": "2",
    "signed_financings": "10",
    "active_financings": "15",
    "completed_financings": "20",
    "signed_agreements": "30",
    "agreements_with_id": "28",
    "total_installment_periods": "600",
    "avg_installment_period": "12",
    "avg_product_price": "15000000.00",
    "avg_approved_installment_amount": "1500000.00",
    "avg_installment_percentage": "10.00"
  }
}

Errors

Status	When it occurs
401 Unauthorized	MORIA attempts to view an organization other than their own
403 Forbidden	Role is not MORIA/ORGANIZATION
404 Not Found	Organization not found

---

PATCH /v1/commodity-financings/:financing_id/approve bearer

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.

bearer MORIA, ORGANIZATION update-commodity-financing RESOURCE_UPDATED

Path params

Param	Type	Notes
financing_id	UUID	Financing ID

Request body — ApproveCommodityFinancingDto

Field	Type	Required	Notes
status	enum CommodityFinancingStatus	yes	New status
approved_installment_amount	string	optional	Approved installment amount
requested_installment_period	number	optional	Period (IsInt)

Example request

{
  "status": "legal_agreement",
  "approved_installment_amount": "1500000",
  "requested_installment_period": 12
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "commodity finance updated successfully"
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role is not MORIA/ORGANIZATION
404 Not Found	Financing not found

---

POST /v1/commodity-financings/:financing_id/withdraw bearer

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.

bearer MORIA, ORGANIZATION update-commodity-financing RESOURCE_UPDATED

Path params

Param	Type	Notes
financing_id	UUID	Financing ID, source of the holding account

Request body — AdminWithdrawCommodityFinancingDto

Field	Type	Required	Notes
amount	string	yes	Withdrawal nominal (rupiah), must be > 0 and <= holding balance
destination_account_id	UUID	yes	Destination account, must be owned by the same organization

Example request

{
  "amount": "500000",
  "destination_account_id": "be2cb7da-e217-401c-8d07-b01e64adfb34"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "commodity financing withdrawal processed successfully"
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role is not MORIA/ORGANIZATION · destination account belongs to a different organization
404 Not Found	Financing / destination account not found

Side effects

• Moves the balance from the holding account to destination_account_id via the transactions service.
• Emits BusinessEvent RESOURCE_UPDATED (impact HIGH).

---

Reference

Enum: CommodityFinancingStatus

• pending — new application, not yet reviewed
• under_review — admin currently reviewing
• rejected — admin rejected the application
• legal_agreement — approved, awaiting agreement signing
• cancelled — cancelled
• signed — agreement signed
• active — auto-deduction running
• completed — financing paid off

State machine

pending → under_review → legal_agreement → signed → active → completed

Rejection branch: from pending/under_review → rejected or cancelled.

Standard error envelope

{
  "message": "you can't view another user commodity finance",
  "statusCode": 403,
  "error": "Forbidden"
}

message can be a string or an array of strings (multi-field validation errors).

Common HTTP codes

• 400 body/query/param validation or account not linked to user
• 401 token expired / missing
• 403 not the owner / wrong scope / status already completed
• 404 financing/account/user not found
• 500 internal — show a generic toast