11.7 Financing cases

A financing case is created from a committee-approved application and then moves through disbursement and repayment lifecycle steps.

Lifecycle values: CONDITIONS_PRECEDENT, DOCUMENTATION, READY_TO_DISBURSE, PARTIALLY_DISBURSED, ACTIVE, COMPLETED, RESTRUCTURED, DEFAULTED, RECOVERY, CANCELLED, WRITTEN_OFF.

High-risk targets (require approve authority, MFA and fresh session): READY_TO_DISBURSE, PARTIALLY_DISBURSED, ACTIVE, COMPLETED, RESTRUCTURED, DEFAULTED, RECOVERY, WRITTEN_OFF.

GET /api/v1/financing-cases

• Purpose. Lists financing cases visible to the actor.
• Authentication. Session cookie and X-DFFMS-Tenant-Id.
• Role. Finance read set, with case data scope.
• Parameters. limit, cursor.
• Errors. As for generic list.

POST /api/v1/financing-cases

• Purpose. Creates a controlled financing case from an application whose committee approval is complete.
• Authentication. Session cookie, tenant header, Origin, Idempotency-Key, MFA enrolled, session age within 15 minutes.
• Role. approve on financing_case: FA (or PSA).
• Body.

Field	Type	Required	Rules
applicationId	UUID	Yes	Application must be APPROVED
beneficiary.displayName	string	Yes	2 to 200
beneficiary.type	string	Yes	2 to 100
beneficiary.externalReference	string	No	Max 120
beneficiary.gender	enum	No	FEMALE or MALE (for inclusion indicators)
beneficiary.youth	boolean	No	Youth inclusion indicator
institutionId	UUID	No	Institution must exist

curl -s -X POST https://dffms.org/api/v1/financing-cases \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>' \
  -H 'X-DFFMS-Tenant-Id: <tenantId>' \
  -H 'Origin: https://dffms.org' \
  -H 'Idempotency-Key: fc-create-2026-10-26-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationId": "0190f2c4-6b3e-7a1d-8c2f-000000000040",
    "beneficiary": {
      "displayName": "Demo Agro Cooperative",
      "type": "COOPERATIVE",
      "externalReference": "COOP-000123",
      "gender": "FEMALE",
      "youth": false
    },
    "institutionId": "0190f2c4-6b3e-7a1d-8c2f-000000000050"
  }'

Response (201): the financing case row (id, tenantId, applicationId, lifecycle CONDITIONS_PRECEDENT at creation, idempotencyKey, timestamps).

Errors:

HTTP	Code	Meaning
400	IDEMPOTENCY_KEY_REQUIRED	Header missing or malformed.
400	VALIDATION_ERROR	Body invalid.
401	UNAUTHENTICATED	No session.
403	MFA_REQUIRED / FRESH_AUTH_REQUIRED / FORBIDDEN	As for application decisions.
404	APPLICATION_NOT_FOUND	Application missing in the tenant.
404	INSTITUTION_NOT_FOUND	Institution missing.
409	APPLICATION_NOT_APPROVED	Application not APPROVED.
409	COMMITTEE_APPROVAL_REQUIRED	No completed committee approval with a decider.
409	APPROVED_TERMS_MISSING	Committee decision lacks a valid immutable term snapshot.

Side effects: creates the case, its initial workflow rows, outbox entries and audit FINANCING_CASE_CREATED. A replay with the same key returns the existing case.

POST /api/v1/financing-cases/{financingCaseId}/transition

• Purpose. Moves a case to the next lifecycle state, checking conditions precedent and restructuring approval where relevant.
• Authentication. Session cookie, tenant header, Origin, Idempotency-Key. For high-risk targets: MFA enrolled and session within 15 minutes.
• Role. approve (FA, or PSA) for high-risk targets; otherwise update on financing_case (CSA, PA, IA, FEO, FA, or PSA).
• Body.

Field	Type	Required	Rules
expectedLifecycle	enum	Yes	Current lifecycle
targetLifecycle	enum	Yes	Target lifecycle
reason	string	Yes	10 to 1,000

Errors:

HTTP	Code	Meaning
400	IDEMPOTENCY_KEY_REQUIRED	Header missing or malformed.
400	VALIDATION_ERROR	Body invalid.
401	UNAUTHENTICATED	No session.
403	MFA_REQUIRED / FRESH_AUTH_REQUIRED / FORBIDDEN	Step-up or role failure.
404	NOT_FOUND	Missing or outside scope.
409	INVALID_STATE_TRANSITION	Transition not permitted.
409	STALE_STATE	expectedLifecycle no longer matches.
409	(condition code)	A condition-precedent check failed; the code is specific to the failing rule.
409	RESTRUCTURING_APPROVAL_REQUIRED	Target RESTRUCTURED without an approved restructuring.

Side effects: updates lifecycle, writes a transition event and audit FINANCING_CASE_TRANSITIONED, and may queue notifications. Replays with the same key return the stored transition.

POST /api/v1/financing-cases/{financingCaseId}/agreements

• Purpose. Records an executed financing, guarantee, investment or security agreement against a case. Records are immutable once written.
• Authentication. Session cookie, tenant header, Origin, Idempotency-Key. No step-up.
• Role. create on financing_case: CSA, PA, IA, FEO, FA (or PSA).
• Body.

Field	Type	Required	Rules
agreementType	enum	Yes	FINANCING_AGREEMENT, GUARANTEE_AGREEMENT, INVESTMENT_AGREEMENT, SECURITY_DOCUMENT
version	string	Yes	1 to 40; ^[A-Za-z0-9][A-Za-z0-9._/-]*$
executedOn	date	Yes	ISO date (YYYY-MM-DD)
signatories	string	Yes	5 to 1,000
executionReference	string	No	Max 160

curl -s -X POST https://dffms.org/api/v1/financing-cases/0190f2c4-6b3e-7a1d-8c2f-000000000060/agreements \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>' \
  -H 'X-DFFMS-Tenant-Id: <tenantId>' \
  -H 'Origin: https://dffms.org' \
  -H 'Idempotency-Key: fc-agr-2026-10-26-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "agreementType": "FINANCING_AGREEMENT",
    "version": "v1.0",
    "executedOn": "2026-10-20",
    "signatories": "Director, Demo Agro Cooperative; Accounting Officer, DFFMS",
    "executionReference": "EXEC-2026-0001"
  }'

Response (201): the agreement record.

Errors:

HTTP	Code	Meaning
400	IDEMPOTENCY_KEY_REQUIRED	Header missing or malformed.
400	VALIDATION_ERROR	Body invalid.
401	UNAUTHENTICATED	No session.
403	FORBIDDEN	Role not permitted. This route has no step-up check.
404	NOT_FOUND	Case missing in the tenant.
409	CASE_CLOSED	Case is COMPLETED, CANCELLED or WRITTEN_OFF.
409	(agreement rule code)	Agreement failed validation (for example, duplicate version of the same type).

Side effects: inserts the agreement, writes audit FINANCING_AGREEMENT_EXECUTED. A replay with the same key returns the stored agreement.