Commodity Financing

The Commodity Financing API lets partner organizations extend installment-based financing to their members for physical goods — vehicles, household appliances, equipment. Borrowers submit a request, organization admins approve terms, the legal agreement is signed, and the borrower then repays the financing in fixed installments. This guide is aimed at backend engineers integrating the API: every endpoint, every state transition, every field your client will send and receive.

Property	Value
Audience	Partner integrators · backend engineers
Base URL	/v1 · JSON over HTTPS
Auth	Bearer token (JWT) · per-endpoint permissions
Lifecycle	pending · under_review · legal_agreement · signed · active · completed · rejected · cancelled
Currency	IDR · amounts as decimal-string
Integration	~1–2 sprints for a typical mobile or web client

What Commodity Financing does

A commodity financing represents an agreement between a borrower and their partner organization to acquire a physical good and repay its cost in installments. The borrower submits a request with the product details, the organization admin reviews and sets the approved installment amount and period, the borrower signs the legal agreement, and the financing becomes active. From there, installments are paid through the platform’s unified payments endpoint until paid_amount reaches reselling_price.

Vehicle financing

A 24-month financing for a motorcycle. The organization approves a fixed monthly installment; the borrower pays each month from their Moria balance or via an external payment rail.

Appliances for employees

The organization admin opens financing on behalf of an employee for household appliances (washing machine, refrigerator). Same lifecycle, but the admin path supplies the borrower’s user_id directly.

Work equipment

A 12-month plan for a laptop or work device. The borrower self-enrolls; the admin reviews, approves, and the borrower repays one installment at a time.

What it isn’t. Commodity Financing does not supply the physical good itself — fulfilment is the organization’s responsibility. It does not compute interest or apply late fees server-side. It does not auto-debit the borrower’s Moria balance for installments — repayments are borrower-initiated through the unified /v1/payments surface. And the per-financing holding account is owned by the organization: only the organization admin can move funds out of it.

---

Where money lives

flowchart LR
    B([Borrower])
    A([Organization admin])

    subgraph WALLET[" Borrower wallet "]
        MAIN[("Main balance<br/>(primary cash)")]
    end

    subgraph FIN[" Per-financing holding "]
        HOLD[("Holding account<br/>(org-owned, one per financing)")]
    end

    subgraph ORG[" Organization accounts "]
        DEST[("Destination account<br/>(org-owned)")]
    end

    EXT[/"External payment<br/>(VA · QRIS · e-wallet)"/]

    EXT -->|"gateway rail<br/>(POST /v1/payments/gateway)"| HOLD
    MAIN -->|"balance rail<br/>(POST /v1/payments/balance)"| HOLD
    HOLD -->|"admin withdrawal<br/>(POST /v1/commodity-financings/:id/withdraw)"| DEST

    B -.->|submits financing| HOLD
    A -.->|approves · withdraws| HOLD

    classDef money fill:#FDF8E8,stroke:#3C2C96,stroke-width:2px,color:#1E1B4B;
    classDef edge fill:#FFF3D0,stroke:#F4BE27,stroke-width:1.5px,color:#8B5A00;
    classDef user fill:#E8E1FF,stroke:#3C2C96,stroke-width:1.5px,color:#1E1B4B;
    class MAIN,HOLD,DEST money;
    class EXT edge;
    class B,A user;

Each financing has its own holding account, owned by the organization, created automatically when the financing is created. Installments — whether paid from the borrower’s main balance or via an external gateway — credit that holding account. The organization admin sweeps funds out of the holding into a destination organization account using the dedicated admin withdrawal endpoint. The borrower has no claim on the holding account.

---

Lifecycle and status transitions

flowchart TB
    classDef state fill:#FDF8E8,stroke:#3C2C96,stroke-width:1.5px,color:#1E1B4B
    classDef terminal fill:#EEF7F1,stroke:#2E7D5B,stroke-width:1.5px,color:#1E1B4B
    classDef bad fill:#FFE0E2,stroke:#D4232C,stroke-width:1.5px,color:#1E1B4B
    classDef note fill:#FFF8E6,stroke:#B8860B,stroke-width:1px,color:#3A332C,font-size:11px

    Start([●]) --> pending
    pending[pending]:::state --> under_review[under_review]:::state
    pending --> legal_agreement[legal_agreement]:::state
    under_review --> legal_agreement
    legal_agreement --> signed[signed]:::state
    signed --> active[active]:::state
    active --> completed[completed]:::terminal

    pending --> rejected[rejected]:::bad
    under_review --> rejected

    InstallmentNote["Installments paid via<br/>POST /v1/payments/balance<br/>reference_type:<br/>commodity_financing_payment"]:::note
    active -.- InstallmentNote

    CancelNote["The borrower can cancel any<br/>pre-active state via DELETE /:id.<br/>The admin can also cancel an active<br/>financing when holding = 0."]:::note
    pending -.- CancelNote

---

Endpoint reference

Method	Path	Purpose	Permission
POST	/v1/commodity-financings	Create a financing (borrower or admin)	create-commodity-financing
GET	/v1/commodity-financings	List financings (paginated, filterable)	read-commodity-financing
GET	/v1/commodity-financings/:financing_id	Fetch one financing by id	read-commodity-financing
PATCH	/v1/commodity-financings/:financing_id	Update editable fields (product, status, etc.)	update-commodity-financing
POST	/v1/commodity-financings/:financing_id/sign	Borrower signs the legal agreement	sign-commodity-financing
PATCH	/v1/commodity-financings/:financing_id/approve	Admin approves or rejects · sets terms	update-commodity-financing
POST	/v1/commodity-financings/:financing_id/withdraw	Admin sweeps funds out of the holding account	update-commodity-financing
DELETE	/v1/commodity-financings/:financing_id	Borrower cancels (only before active)	delete-commodity-financing
GET	/v1/summary/commodity-financings	Organization-wide stats (org admins · Moria only)	read-commodity-financing

Installment repayments are not on this surface — they use the platform-wide payments endpoints with reference_type: "commodity_financing_payment". See the repayment section below.

---

Two create paths, one endpoint

POST /v1/commodity-financings serves two callers — a borrower applying for themselves, or an organization admin opening a financing on behalf of a member. The endpoint inspects the user type from the bearer token to decide which DTO shape to expect: an individual caller sends the borrower DTO; an organization admin sends the admin DTO, which carries richer fields (target borrower user_id, optional pre-set approved_installment_amount, legal_agreement_id, etc.).

Borrower path · individual caller

• Caller’s bearer token belongs to an INDIVIDUAL user
• Body follows the borrower DTO — no user_id field; the borrower is the caller
• The resulting financing starts at pending
• The borrower’s organization is inferred from the caller

Admin path · organization caller

• Caller’s bearer token belongs to an ORGANIZATION or MORIA user
• Body follows the admin DTO — must include the borrower’s user_id
• The admin can pre-fill approved_installment_amount and legal_agreement_id up front
• The borrower must belong to the admin’s organization (enforced server-side)

Why the two shapes are separate

Routing by user type on the endpoint keeps both flows reachable behind a single REST path while letting each caller be validated against a strict, non-overlapping schema. Sending the wrong shape for your user type results in 400 from schema validation before the domain logic runs. Your client should choose the DTO based on the token it holds, not based on which fields happen to be available.

---

Creating a financing · borrower path

Request

POST /v1/commodity-financings
Authorization: Bearer <token>
Content-Type: application/json

{
  "product_name": "Honda Beat 2026",
  "product_price": "24000000",
  "product_link": "https://store.example/honda-beat",
  "product_image_document_id": "9f3b-...-1d22",
  "requested_installment_amount": "1000000",
  "requested_installment_period": 24,
  "deduction_date": "2026-06-25"
}

Response · 201 Created

{
  "data": {
    "commodityFinance": {
      "id": "a8c1-...-c9f0",
      "user_id": "be2c-...-fb34",
      "organization_id": "0123-...-4567",
      "account_id": "1111-...-2222",
      "product_name": "Honda Beat 2026",
      "product_price": "24000000.0000",
      "requested_installment_amount": "1000000.00",
      "requested_installment_period": 24,
      "status": "pending",
      "legal_agreement_signed": false,
      "paid_amount": "0.00",
      "remaining_amount": "0.00",
      "created_at": "2026-05-18T03:12:44Z"
    }
  }
}

The account_id in the response is the financing’s holding account, provisioned automatically at create time. It is owned by the borrower’s organization, not by the borrower. Store this id alongside the financing id — you will see it referenced in payment events later.

---

Creating a financing · admin path

Request

POST /v1/commodity-financings
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": "be2c-...-fb34",
  "signature_id": "7777-...-8888",
  "product_name": "MacBook Pro 14\"",
  "product_price": "35000000",
  "product_link": "https://store.example/mbp-14",
  "product_image_document_id": "9f3b-...-1d22",
  "requested_installment_amount": "1500000",
  "approved_installment_amount": "1500000",
  "requested_installment_period": 24,
  "legal_agreement_id": "5555-...-6666",
  "deduction_date": "2026-06-25"
}

Validation rules to know

• user_id must reference a borrower who belongs to the admin’s organization — otherwise 400
• The (user_id, slugified product_name) combination must be unique — otherwise 409
• Amounts are decimal-strings in IDR; period is a positive integer
• deduction_date is an ISO date (YYYY-MM-DD) — used by the platform-side reminder cadence
• Document ids (product_image_document_id, legal_agreement_id, signature_id) come from your prior upload to POST /v1/documents/upload
• The resulting financing starts at pending regardless of any status override supplied

---

Paying an installment

---
config:
  sequence:
    actorMargin: 240
    width: 180
    messageMargin: 45
    boxMargin: 16
    noteMargin: 14
---
sequenceDiagram
    autonumber
    actor B as Borrower
    participant API as Moria API
    participant MAIN as Borrower main balance
    participant HOLD as Financing holding account
    actor A as Organization admin

    Note over B,API: One installment cycle (balance rail)
    B->>API: POST /v1/payments/balance<br/>{ reference_type: "commodity_financing_payment",<br/>reference_id, amount, source_account_id }
    API->>API: validate ownership · state · amount<br/>(amount must equal one installment)

    alt sufficient balance · validation passes
        API->>MAIN: debit amount
        API->>HOLD: credit amount
        API->>API: bump paid_amount<br/>· recompute remaining_amount<br/>· flip status if paid off
        API-->>B: 201 { new_balance, transaction_id }
    else insufficient balance or wrong amount
        API-->>B: 400 { statusCode, message, error }
    end

    Note over A,HOLD: Admin sweeps the holding (any time)
    A->>API: POST /v1/commodity-financings/:id/withdraw<br/>{ amount, destination_account_id }
    API->>HOLD: debit amount
    API->>API: credit destination_account_id<br/>(org-owned)
    API-->>A: 200 { transaction_id,<br/>destination_account_id, amount }

---

Two payment rails · same reference

Balance rail · synchronous

POST /v1/payments/balance
Authorization: Bearer <token>

{
  "reference_type": "commodity_financing_payment",
  "reference_id": "a8c1-...-c9f0",
  "amount": "1000000",
  "source_account_id": "be2c-...-fb34"
}

Debits the borrower’s Moria account and credits the financing’s holding account in a single DB transaction. Returns the new source balance and a transaction id. Use this when the borrower has funds on the platform.

Gateway rail · asynchronous

POST /v1/payments/gateway
Authorization: Bearer <token>

{
  "reference_type": "commodity_financing_payment",
  "reference_id": "a8c1-...-c9f0",
  "amount": "1000000",
  "payment_id": "client-generated-uuid",
  "transaction_name": "Honda Beat instalment #3"
}

Returns a payment-gateway envelope (VA number / QR / payment link). The financing is credited asynchronously once the gateway confirms payment — poll the gateway order or wait for your webhook to know the final state.

Amount rule · exactly one installment

Both rails enforce that amount must equal the approved installment exactly (1-cent tolerance). Partial payments and lump-sum overpayments are rejected with 400. Multi-installment catch-up is done by sending several sequential payment calls, not by paying a larger amount in a single request.

---

Admin approval flow

Approve or reject

PATCH /v1/commodity-financings/:financing_id/approve
Authorization: Bearer <token>

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

The admin pushes the financing toward legal_agreement (approved) or rejected. The approved installment amount and period are written to the entity at this step.

Borrower signs

POST /v1/commodity-financings/:financing_id/sign
Authorization: Bearer <token>

{ "legal_agreement_signed": true }

The borrower confirms the legal agreement. Sign can only be called from legal_agreement or signed (re-sign is idempotent). The financing transitions to active on success.

Sequence in practice

1. Borrower or admin creates the financing — status starts as pending
2. Admin reviews · calls PATCH /:financing_id/approve with status legal_agreement and the approved terms
3. Your client downloads or generates the agreement document and presents it to the borrower
4. Borrower calls POST /:financing_id/sign · status becomes active
5. Borrower starts paying installments via /v1/payments/balance or /v1/payments/gateway

---

Admin sweeps the holding account

Request

POST /v1/commodity-financings/:financing_id/withdraw
Authorization: Bearer <token>

{
  "amount": "5000000",
  "destination_account_id": "0123-...-4567"
}

Moves funds from the financing’s holding account to an organization-owned destination account. Atomic ledger transfer; no domain update on the financing row.

What the platform checks

• Caller must be an organization admin (ORGANIZATION or MORIA)
• The financing must belong to the caller’s organization
• The destination must be an organization-owned account in the same organization
• amount must be greater than zero and less than or equal to the holding balance
• Returns a ledger transaction id so you can reconcile on your side

Cancelling an active financing

An active financing can only be cancelled if its holding account balance is zero. If funds remain in the holding, PATCH /:financing_id with status: "cancelled" returns 403. Withdraw the balance first via the endpoint above, then cancel.

---

List and filter

Request

GET /v1/commodity-financings?status=active
     &user_id=be2c-...-fb34
     &page=1&limit=20
Authorization: Bearer <token>

Returns paginated data. Individual borrowers only see their own financings. Organization admins see every financing in their organization and can filter by user_id or account_id.

Query parameters

Param	Values	Notes
status	pending · under_review · legal_agreement · signed · active · completed · cancelled · rejected	Filter by state
user_id	uuid	Admin only · scope to one borrower
account_id	uuid	Scope to one holding account
order	asc · desc	Order by created_at
page	integer, default 1	1-indexed
limit	integer, default 10	Page size

The response wraps the list inside data with pagination metadata (count, currentPage, totalPages, limit). The single-fetch endpoint GET /:financing_id also returns member_contributions — a summary of prior installment payments — for clients identified as mobile.

---

Errors you will encounter

Status	Typical trigger	What it means · how to respond
400	Validation	The body fails schema validation — required field missing, wrong type, payback amount that doesn’t equal one installment, admin creating for a user outside their organization. Show an inline message.
401	Missing or invalid bearer token	Token expired, malformed, or absent. Re-authenticate and retry.
403	Permission · ownership · state	Caller lacks the required permission, or is operating on a financing they don’t own, or attempting an illegal state transition (sign on a non-legal_agreement financing, cancel an active financing with non-zero holding, update a completed financing). Do not retry.
404	Unknown id	Financing, user, or account does not exist or is soft-deleted. Refresh and drop stale entries.
409	Duplicate	A financing with the same (user_id, slug_product_name) already exists for this borrower. Differentiate the product name on your side before retrying.
500	Internal	Retry once with exponential backoff. If persistent, capture the request id from the error envelope and contact support.

Standard error envelope

{
  "statusCode": 400,
  "message": "Payback amount must equal one installment: expected 1000000.00, got 500000",
  "error": "Bad Request"
}

---

Auth, permissions, and visibility

Auth

• Every endpoint expects an Authorization: Bearer <token> header
• The token is a JWT issued by the platform auth flow — your client obtains it on behalf of the end-user and forwards it on every call
• Each call is checked against the caller’s role and the permissions bound to that role
• Admin-only endpoints (approve, withdraw, summary) additionally check that the caller’s role is ORGANIZATION or MORIA

Permission matrix

Permission	Used by
create-commodity-financing	POST create
read-commodity-financing	GET list · GET one · GET summary
update-commodity-financing	PATCH update · PATCH approve · POST withdraw
sign-commodity-financing	POST sign
delete-commodity-financing	DELETE
payback-commodity-financing	POST /v1/payments/balance · /gateway with reference_type: commodity_financing_payment

Visibility rules

• Borrowers see and act only on financings where they are the user_id
• Organization admins see every financing where organization_id matches their organization, and can filter by user_id or account_id to narrow
• Approve, withdraw, and summary are restricted to ORGANIZATION or MORIA roles regardless of granted permissions
• Payback always runs against the borrower’s own financing — admins cannot pay on a borrower’s behalf through the payments surface

---

What isn’t supported, and how to work around it

No installment auto-debit

The platform does not silently pull installments from the borrower’s main balance. Workaround: in your client, surface the next due date and amount and have the borrower initiate the payment via /v1/payments/balance or /v1/payments/gateway.

No partial or lump-sum payments

The payback amount must exactly equal one installment. Workaround: to catch up on several missed installments, send several sequential payment calls — one per installment.

Borrowers cannot withdraw from the holding

The holding account is organization-owned. Workaround: if a refund is needed, the organization admin uses the admin withdrawal endpoint to move funds to an org account, then settles off-ledger with the borrower.

No interest accrual or late fees

The financing record only stores principal and the installment plan. Workaround: if your product needs interest or penalties, add them on your side and adjust approved_installment_amount at create time.

Product name is slugified for uniqueness

A borrower cannot hold two financings with the same slugified product name. Workaround: differentiate the product name (e.g. add a year or variant tag) before POST if you see a 409.

No fulfilment surface

The API tracks the financing agreement, not the physical good. Workaround: handle order tracking, shipment, and inventory in your own systems and reference the financing id from there.

---

Integration checklist

Before going live

• Token plumbing — your client obtains the JWT from the platform auth flow and forwards it on every commodity-financing call
• Two-shape create — your client picks the borrower DTO or admin DTO based on the token it holds, not based on which fields are at hand
• Upload documents first — product image, legal agreement, and signature documents go through POST /v1/documents/upload before you reference their ids in create / approve / sign calls
• State-aware UI — controls are hidden or disabled for terminal states (completed, cancelled, rejected) and you treat 403 transition errors as a refresh trigger

Operational readiness

• Payback wiring — your client uses the unified payments endpoints with reference_type: "commodity_financing_payment" and enforces the one-installment-per-call rule before POST
• Sweep cadence — admins know to call POST /:financing_id/withdraw on the cadence that fits their reconciliation; nothing happens automatically
• Cancel-active discipline — cancelling an active financing requires a zero holding balance; chain withdraw → cancel in your admin UI
• Error envelope — your error handler reads { statusCode, message, error } and maps it to inline / toast / modal patterns in your design system

Commodity Financing composes with the rest of the Moria surface: documents pass through the document API, payback flows through the unified payments endpoints, and the per-financing holding account lives alongside every other Moria account in the same ledger. Knowing the lifecycle, the two create paths, the one-installment payback rule, and the admin-only withdraw is enough to ship a production integration.