Investments

The Investments module facilitates user investments (one-time, recurring, or from saving goal conversion) into organization-owned pools, with ROI projections and a withdrawal notice flow. The InvestmentsController at /investments handles investment CRUD, recurring schedules, ROI previews, saving goals → investments conversion, and the withdrawal notice workflow (user submits; MORIA admin lists/marks eligible). Every investment requires a proof document uploaded via multipart together with its metadata (atomic transaction).

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json · multipart/form-data for create + convert-goals
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	pools, saving-goals, document, withdrawal, payments
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Users create an investment (one-time or recurring) via POST /investments by attaching a proof document (multipart). Alternative: convert a set of saving goals into investments via POST /investments/convert-goals. For recurring, an internal scheduler debits funds based on frequency. Investment withdrawal uses a notice period: the user submits a notice via POST /:id/withdrawal-notice, and MORIA admin marks eligible once the notice period ends. Cancel/pause for recurring is available at any time.

Method	Path	Auth	Summary
GET	/v1/investments	bearer	List user investments (or by organization)
GET	/v1/investments/:id/preview	bearer	Preview projected ROI for a single investment
GET	/v1/investments/withdrawal-notices	MORIA	MORIA admin: list all withdrawal notices
PATCH	/v1/investments/withdrawal-notices/mark-eligible	MORIA	MORIA admin: bulk mark eligible
GET	/v1/investments/:id	bearer	Investment detail
POST	/v1/investments	bearer	Create one-time / recurring investment (multipart)
PATCH	/v1/investments/:id/pause	bearer	Pause/resume recurring investment
DELETE	/v1/investments/:id	bearer	Cancel recurring investment
POST	/v1/investments/convert-goals	bearer	Convert saving goals → investments (multipart)
GET	/v1/investments/convert-goals/preview	bearer	Preview ROI before converting goals
GET	/v1/investments/:id/schedule	bearer	Get recurring investment schedule
POST	/v1/investments/:id/withdrawal-notice	bearer	Submit withdrawal notice (start notice period)
GET	/v1/investments/:id/withdrawal-notice	MORIA	MORIA admin: get withdrawal notice detail
POST	/v1/investments/:id/withdrawal-notice/cancel	bearer	User: cancel withdrawal notice

Auth + scope notes

• All endpoints require a Bearer JWT + specific permission.
• The withdrawal-notices list and mark-eligible endpoints are restricted to @Roles(UserType.MORIA) — platform superadmin only.
• The create + convert-goals endpoints use multipart/form-data: send the file field (proof, max 50 MB) alongside the metadata fields.
• Withdrawal notice: after submission, the scheduler waits notice_days_required days before eligible. Admin then marks eligible in bulk.
• The actual investment is executed via the payment-gateway / internal payments — the create endpoint here only creates the row + proof document.

---

GET /v1/investments bearer

List investments for the logged-in user. If organization_id is supplied, list all investments in that organization’s pool (for org admins). Without organization_id → user mode with pagination.

bearer read-investment RESOURCE_FETCHED

Query params — QueryParamsDto

Param	Type	Default	Notes
page	number	1	Page number (validated by IsNumberString + IsNotZero)
limit	number	10	Records per page
order	'asc' | 'desc'	desc	Order by created_at
organization_id	UUID	optional	Switch to org mode — list all investments in that org’s pool

Response — 200 OK (user mode)

{
  "status": "success",
  "statusCode": 200,
  "message": "Investments retrieved successfully",
  "data": {
    "limit": 10,
    "count": 5,
    "currentPage": 1,
    "totalPages": 1,
    "investments": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "770e8400-e29b-41d4-a716-446655440222",
        "pool_id": "660e8400-e29b-41d4-a716-446655440111",
        "investment_type": "one_time",
        "amount": "1000.0000",
        "status": "active",
        "projected_roi": "50.0000",
        "maturity_date": "2027-05-20",
        "created_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid query param
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing read-investment permission

---

GET /v1/investments/:id/preview bearer

Preview projected ROI for an existing investment. The service computes this from the organization pool yield rate and the investment amount.

bearer read-investment RESOURCE_FETCHED

Path params

Param	Type	Notes
id	UUID	Investment ID — validated by ParseUUIDPipe

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Projected roi for investment retrieved successfully",
  "data": {
    "projected_roi": "75.0000",
    "investment": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "1000.0000",
      "status": "active"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	No investment selected for preview
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Investment not found

---

GET /v1/investments/withdrawal-notices MORIA

MORIA admin: list all withdrawal notices on the platform. Supports status filter and pagination.

bearer MORIA read-withdrawal RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
status	enum WithdrawalNoticeStatus	optional	pending, eligible, granted, cancelled

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Withdrawal notices retrieved successfully",
  "data": {
    "limit": 10,
    "count": 5,
    "currentPage": 1,
    "totalPages": 1,
    "withdrawal_notices": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "investment_id": "550e8400-e29b-41d4-a716-446655440001",
        "amount": "1000.0000",
        "notice_days_required": 30,
        "notice_date": "2026-05-06",
        "eligible_date": "2026-06-05",
        "status": "pending",
        "granted_date": null,
        "reason": null,
        "created_at": "2026-05-06T00:00:00.000Z",
        "updated_at": "2026-05-06T00:00:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role not MORIA or permission missing

---

PATCH /v1/investments/withdrawal-notices/mark-eligible MORIA

MORIA admin bulk-sets withdrawal notice status to eligible for a list of investment IDs (after the notice period ends). Investments still pending are updated; those already eligible/granted/cancelled are skipped.

bearer MORIA update-withdrawal WITHDRAWAL_PROCESSED

Request body — MarkWithdrawalsEligibleDto

Field	Type	Required	Notes
investment_ids	string[] (UUID)	yes	Array of investment UUIDs (IsUUID per item)

Example request

{
  "investment_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Withdrawal notices marked as eligible successfully",
  "data": {
    "count": 2,
    "withdrawal_notices": [ { "...": "WithdrawalNoticeDto shape" } ]
  }
}

Errors

Status	When it occurs
400 Bad Request	No pending withdrawal notice in the list
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Role not MORIA or permission missing

---

GET /v1/investments/:id bearer

Detail of a single investment. Response includes pool + user relations (see entity shape).

bearer read-investment RESOURCE_FETCHED

Path params

Param	Type	Notes
id	UUID	Investment ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Investment retrieved successfully",
  "data": {
    "investment": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "770e8400-e29b-41d4-a716-446655440222",
      "pool_id": "660e8400-e29b-41d4-a716-446655440111",
      "investment_type": "one_time",
      "amount": "1000.0000",
      "saving_goal_id": null,
      "payment_ref": "PAY-20260520-001",
      "status": "active",
      "projected_roi": "50.0000",
      "maturity_date": "2027-05-20",
      "withdrawal_notice_status": null,
      "withdrawal_notice_date": null,
      "withdrawal_eligible_date": null
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Investment not found

---

POST /v1/investments bearer

Create a one-time or recurring investment. Multipart: the file field (proof file, max 50 MB) is required — investment + proof document are created atomically (single DB transaction).

bearer create-investment RESOURCE_CREATED

Request body — CreateInvestmentDto (multipart)

Field	Type	Required	Notes
file	binary	yes	Proof file (multipart file part); max 50 MB
type	'one_time' | 'recurring'	yes	Investment kind
organization_id	UUID	yes	Target pool organization
amount	numeric string	yes	Investment amount (one_time) or per cycle (recurring). Min 1000, max 2000000
document_type	enum DocumentType	yes	Default RECEIPT if empty. Members: legal_agreement, signature, cause_report, donation_certificate, receipt, image, video
frequency	enum RecurringFrequency	optional	daily, weekly, monthly (default monthly) — only for recurring
start_date	string (YYYY-MM-DD)	optional	Default today for recurring
end_date	string (YYYY-MM-DD)	optional	For recurring

Example request (multipart fields)

file: <binary>
type: recurring
organization_id: be2cb7da-e217-401c-8d07-b01e64adfb34
amount: 1000.00
document_type: receipt
frequency: monthly
start_date: 2026-02-01
end_date: 2027-02-01

Response — 201 Created (recurring)

{
  "status": "success",
  "statusCode": 201,
  "message": "Recurring Investment created successfully",
  "data": {
    "investment": { "id": "550e8400-e29b-41d4-a716-446655440000", "investment_type": "recurring", "amount": "1000.0000", "status": "active" },
    "schedule": { "id": "660e8400-e29b-41d4-a716-446655440111", "frequency": "monthly", "status": "active" }
  }
}

Errors

Status	When it occurs
400 Bad Request	proof document file is required · amount < 1000 or > 2000000 · org_id invalid
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing create-investment permission

Side effects

• Atomic: row investments + row documents (product_type investment) are created in the same transaction.
• For recurring: a row in recurring_investment_schedules is also created.
• Emits BusinessEvent RESOURCE_CREATED (impact MEDIUM).

---

PATCH /v1/investments/:id/pause bearer

Pause or resume a recurring investment. Only recurring investments can be paused. Users may only pause their own investments.

bearer update-investment RESOURCE_UPDATED

Path params

Param	Type	Notes
id	UUID	Investment ID

Request body — PauseInvestmentDto

Field	Type	Required	Notes
pause	boolean	yes	true → pause, false → resume

Example request

{ "pause": true }

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Investment pause status updated successfully",
  "data": { "investment": { "...": "Investments shape, status=paused or active" } }
}

Errors

Status	When it occurs
400 Bad Request	Not a recurring investment
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Attempt to pause another user’s investment
404 Not Found	Investment not found

---

DELETE /v1/investments/:id bearer

Cancel a recurring investment. Investment status is set to cancelled; the schedule is deactivated.

bearer delete-investment RESOURCE_DELETED

Path params

Param	Type	Notes
id	UUID	Investment ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Investment cancelled successfully",
  "data": { "investment": { "...": "Investments shape, status=cancelled" } }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Attempt to cancel another user’s investment
404 Not Found	Investment not found

---

POST /v1/investments/convert-goals bearer

Convert a set of saving goals into separate investments. Multipart: the proof file is uploaded once, each new investment has its own documents row referencing the same object.

bearer lock-saving-goal RESOURCE_CREATED

Request body — ConvertGoalsDto (multipart)

Field	Type	Required	Notes
file	binary	yes	Proof file (multipart file part); max 50 MB
organization_id	UUID	yes	Target pool organization
saving_goal_ids	string[] (UUID)	yes	Array of saving goal UUIDs (IsUUID per item)
document_type	enum DocumentType	yes	Proof document type

Example request (multipart fields)

file: <binary>
organization_id: be2cb7da-e217-401c-8d07-b01e64adfb34
saving_goal_ids: ["be2cb7da-...", "ce2cb7da-..."]
document_type: receipt

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Saving goals converted to investments successfully",
  "data": {
    "investments": [
      { "id": "550e8400-e29b-41d4-a716-446655440000", "investment_type": "saving_goal_conversion", "saving_goal_id": "be2cb7da-...", "amount": "850.0000", "status": "active" }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	proof document file is required · organization_id invalid
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing lock-saving-goal permission
404 Not Found	Saving goals not found: <comma separated ids>

Side effects

• Status of converted saving goals changes to converted.
• The saving goal holding account balance is moved to the organization pool.

---

GET /v1/investments/convert-goals/preview bearer

Preview projected ROI before converting saving goals. The goal_ids query is a comma-separated list of UUIDs.

bearer read-investment RESOURCE_FETCHED

Query params

Param	Type	Required	Notes
goal_ids	string	yes	Comma-separated UUID list (whitespace trimmed)

Example request

GET /v1/investments/convert-goals/preview?goal_ids=be2cb7da-...,ce2cb7da-...

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "ROI preview retrieved successfully",
  "data": {
    "total_amount": "1700.0000",
    "projected_roi": "85.0000",
    "goalCount": 2,
    "goals": [ { "id": "be2cb7da-...", "saved_amount": "850.0000", "...": "SavingGoal shape" } ]
  }
}

Errors

Status	When it occurs
400 Bad Request	You haven't selected any saving goal for investment preview (list empty after trim)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Saving goals not found: <ids>

---

GET /v1/investments/:id/schedule bearer

Get the schedule for a recurring investment. Contains frequency, start/end date, status, and execution history.

bearer read-investment RESOURCE_FETCHED

Path params

Param	Type	Notes
id	UUID	Investment ID (must be type recurring)

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Investment schedule retrieved successfully",
  "data": {
    "schedule": {
      "id": "660e8400-e29b-41d4-a716-446655440111",
      "investment_id": "550e8400-e29b-41d4-a716-446655440000",
      "frequency": "monthly",
      "start_date": "2026-02-01",
      "end_date": "2027-02-01",
      "status": "active"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Investment/schedule not found

---

POST /v1/investments/:id/withdrawal-notice bearer

User submits a withdrawal notice for an investment. Starts the notice period (e.g. 30 days). After the period ends, MORIA admin marks eligible, then funds can be withdrawn.

bearer create-withdrawal WITHDRAWAL_REQUESTED

Path params

Param	Type	Notes
id	UUID	Investment ID

Request body — CreateWithdrawalNoticeDto

Field	Type	Required	Notes
reason	string	optional	Free-text reason, max 500 chars

Example request

{ "reason": "Need funds for emergency" }

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Withdrawal notice submitted successfully",
  "data": {
    "withdrawal_notice": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "investment_id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": "1000.0000",
      "notice_days_required": 30,
      "notice_date": "2026-05-06",
      "eligible_date": "2026-06-05",
      "status": "pending",
      "reason": "Need funds for emergency",
      "created_at": "2026-05-06T00:00:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Withdrawal not allowed (investment not active, pending notice already exists)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Permission insufficient
404 Not Found	Investment not found

---

GET /v1/investments/:id/withdrawal-notice MORIA

MORIA admin: get the withdrawal notice detail for an investment (status, eligible_date, amount, etc.).

bearer MORIA read-withdrawal RESOURCE_FETCHED

Path params

Param	Type	Notes
id	UUID	Investment ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Withdrawal notice retrieved successfully",
  "data": {
    "withdrawal_notice": { "...": "WithdrawalNoticeDto shape" }
  }
}

Errors

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

---

POST /v1/investments/:id/withdrawal-notice/cancel bearer

User cancels a withdrawal notice still in pending. Notices already granted/cancelled cannot be cancelled again.

bearer delete-withdrawal WITHDRAWAL_CANCELLED

Path params

Param	Type	Notes
id	UUID	Investment ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Withdrawal notice cancelled successfully",
  "data": {
    "withdrawal_notice": { "...": "WithdrawalNoticeDto shape, status=cancelled" }
  }
}

Errors

Status	When it occurs
400 Bad Request	Notice already granted or cancelled
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Investment is not owned by user or permission insufficient
404 Not Found	Withdrawal notice not found

---

Reference

Enum: InvestmentType

• one_time — single-payment investment
• recurring — periodic investment (active schedule)
• saving_goal_conversion — result of saving goal conversion

Enum: InvestmentStatus

• active · paused · withdrawn · cancelled

Enum: RecurringFrequency

• daily · weekly · monthly

Enum: RecurringScheduleStatus

• active · paused · completed · cancelled

Enum: WithdrawalNoticeStatus

• pending — new notice, awaiting notice period
• eligible — period complete, admin marked eligible
• granted — funds disbursed
• cancelled — cancelled by user

Enum: ROICycle

• monthly · quarterly · yearly

Standard error envelope

{
  "message": "Minimum investment amount is 1000",
  "statusCode": 400,
  "error": "Bad Request"
}

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

Common HTTP codes

• 400 validation · amount out of range · file missing
• 401 token expired / missing
• 403 not owner · role not MORIA · permission insufficient
• 404 investment/notice/saving goal not found
• 500 internal — show a generic toast

Amount limits

• Min: 1000
• Max: 2000000