Charitable Cause

The Charitable Cause module enables crowdfunding projects: organizations or individuals register a cause (funding target, regulations, benefit), assign managers, and receive donations. User-facing endpoints live in CharitableCauseController (/charitable-causes) for CRUD + assign manager. Admin endpoints live in CharitableCauseAdminController for summary, cause approval, and allocation of open donations (donations without a specific cause) to ACTIVE causes.

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, transactions
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Typical flow: create cause → platform admin approves → donor contributes via the payments module (donation flow) → the creator may assign additional managers. Donations without a specific cause (type OPEN) are pooled and allocated by MORIA superadmin via the admin endpoint POST /donations/allocate.

Method	Path	Auth	Summary
GET	/v1/charitable-causes	bearer	List causes (scoped by role)
GET	/v1/charitable-causes/:id	bearer	Detail of a single cause
POST	/v1/charitable-causes	bearer	Create a new cause
PATCH	/v1/charitable-causes/:id	bearer	Update a cause
DELETE	/v1/charitable-causes/:id	bearer	Deactivate (soft-cancel)
POST	/v1/charitable-causes/:id/assign-manager	bearer	Assign an additional manager
GET	/v1/summary/charitable-causes	bearer	Statistics summary (admin)
GET	/v1/donations/open	bearer	List open donations (MORIA only)
POST	/v1/donations/allocate	bearer	Allocate a batch of open donations to a cause (MORIA only)
PATCH	/v1/charitable-causes/:id/approve	bearer	Approve a cause (MORIA only)

Auth + scope notes

• User endpoints require Bearer + permission read-/create-/update-/delete-charitable-cause. Admin endpoints require role MORIA or ORGANIZATION + additional permissions.
• Initial cause status: pending until a MORIA admin performs approve.
• OPEN donations (donors that did not pick a specific cause) are listed via GET /donations/open and allocated to ACTIVE causes in batches — atomic, all donations must be valid or the entire batch is rolled back.

---

GET /v1/charitable-causes bearer

Paginated list of causes. Scope depends on role: INDIVIDUAL sees causes tied to their account (or marketplace via organization_id); ORGANIZATION admin sees the org’s causes; MORIA sees all.

bearer read-charitable-cause

Query params — CharitableCauseQueryDto

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
status	enum CharitableCauseStatus	optional	Status filter; all means no filter
order	'asc' | 'desc'	desc	Sort by created_at
organization_id	string (UUID)	optional	Marketplace lookup; INDIVIDUAL may only use their own organization
user_id	string (UUID)	optional	User filter; layered authorization
account_id	string (UUID)	optional	Account filter; layered authorization

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Causes fetched successfully",
  "data": {
    "limit": 10,
    "count": 12,
    "currentPage": 1,
    "totalPages": 2,
    "causes": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Bantu Korban Banjir",
        "description": "...",
        "target_amount": 10000000,
        "current_amount": 2500000,
        "currency": "IDR",
        "status": "active",
        "owner_type": "organization",
        "organization_id": "660e8400-e29b-41d4-a716-446655440111",
        "account_id": "be2cb7da-e217-401c-8d07-b01e64adfb34"
      }
    ]
  }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Wrong scope (see auth notes)

---

GET /v1/charitable-causes/:id bearer

Detail of a single cause. Response format differs between MOBILE (raw) and WEB (formatted with aggregation). Scope organization_id is passed from the user.

bearer read-charitable-cause

Path params

Param	Type	Notes
id	UUID	Cause ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Cause retrieved successfully",
  "data": {
    "cause": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Bantu Korban Banjir",
      "description": "Bantuan untuk korban banjir Jakarta",
      "target_amount": 10000000,
      "current_amount": 2500000,
      "currency": "IDR",
      "regulations": "...",
      "benefit": "...",
      "location": "Jakarta, Indonesia",
      "status": "active",
      "owner_type": "organization",
      "managers": [ { "user_id": "...", "role": "manager" } ]
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	No access to the cause
404 Not Found	Cause not found

---

POST /v1/charitable-causes bearer

Create a new cause. The initial status is pending until a MORIA admin approves it. The organization_id field is only for MORIA superadmins creating on behalf of an organization.

bearer create-charitable-cause RESOURCE_CREATED

Request body — CreateCharitableCauseDto

Field	Type	Required	Notes
account_id	string (UUID)	✓	Account that will receive donations
description	string	✓	Cause description
currency	string	optional	Currency (default IDR)
target_amount	number	✓	Funding target (number, not string)
regulations	string	✓	Cause regulations & terms
benefit	string	✓	Cause benefit & impact
name	string	✓	Cause name
location	string	optional	Cause location (e.g. Jakarta, Indonesia)
organization_id	string	optional	Only MORIA may send this — create on behalf of someone else

Example request

{
  "account_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
  "name": "Bantu Korban Banjir",
  "description": "Bantuan untuk korban banjir Jakarta",
  "currency": "IDR",
  "target_amount": 10000000,
  "regulations": "Dana digunakan untuk kebutuhan pokok korban",
  "benefit": "Membantu 500 keluarga terdampak",
  "location": "Jakarta, Indonesia"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Cause created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bantu Korban Banjir",
    "target_amount": 10000000,
    "current_amount": 0,
    "currency": "IDR",
    "status": "pending"
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (non-numeric target_amount, required field empty)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing create-charitable-cause permission

---

PATCH /v1/charitable-causes/:id bearer

Update a cause. Only the creator or a manager may perform this. All fields are optional.

bearer update-charitable-cause RESOURCE_UPDATED

Path params

Param	Type	Notes
id	UUID	Cause ID

Request body — UpdateCharitableCauseDto

Field	Type	Notes
description	string	New description
currency	string	Currency
target_amount	number	New funding target
regulations	string	New regulations
benefit	string	New benefit
name	string	New name
status	enum CharitableCauseStatus	New status

Example request

{ "name": "Bantu Korban Banjir 2026", "target_amount": 15000000 }

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Cause updated successfully",
  "data": { "...": "CauseDto shape" }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not the creator/manager
404 Not Found	Cause not found

---

DELETE /v1/charitable-causes/:id bearer

Deactivate a cause (soft-cancel). Status changes to deactivated; the row is not removed and donations already received are not refunded.

bearer delete-charitable-cause RESOURCE_DELETED

Path params

Param	Type	Notes
id	UUID	Cause ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Cause cancelled successfully",
  "data": { "...": "CauseDto shape, status='deactivated'" }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not the creator
404 Not Found	Cause not found

---

POST /v1/charitable-causes/:id/assign-manager bearer

Designate another user as a manager of the cause. Only the creator is allowed — additional managers may update the cause but may not assign further managers.

bearer update-charitable-cause

Path params

Param	Type	Notes
id	UUID	Cause ID

Request body — AssignManagerDto

Field	Type	Required	Notes
user_id	string (UUID)	✓	ID of the user to become a manager

Example request

{ "user_id": "be2cb7da-e217-401c-8d07-b01e64adfb34" }

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Manager assigned successfully",
  "data": { "manager": { "user_id": "...", "cause_id": "..." } }
}

Errors

Status	When it occurs
400 Bad Request	User is already a manager of this cause
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not the creator (only the creator may assign)
404 Not Found	Cause or user not found

---

GET /v1/summary/charitable-causes bearer

Cause statistics summary for the caller’s organization. Admin endpoint (MORIA / ORGANIZATION). MORIA can also view summaries across organizations.

bearer MORIA, ORGANIZATION read-charitable-cause

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "charitable cause summary fetched successfully",
  "data": {
    "organization_id": "660e8400-e29b-41d4-a716-446655440111",
    "organization_name": "Moria Fund",
    "total_causes": "12",
    "active_causes": "5",
    "completed_causes": "3",
    "pending_causes": "2",
    "total_target_amount": "100000000.00",
    "total_collected_amount": "65000000.00"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Token invalid / querying another org (mismatch)
403 Forbidden	Role is not MORIA/ORGANIZATION

---

GET /v1/donations/open bearer

List OPEN donations not yet allocated to a specific cause. MORIA superadmin only — typically used to allocate donations to causes in need.

bearer MORIA allocate-open-donation RESOURCE_UPDATED

Query params

Param	Type	Default	Notes
page	number	1	Page number
limit	number	20	Records per page

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Unallocated open donations fetched",
  "data": {
    "limit": 20,
    "count": 8,
    "currentPage": 1,
    "totalPages": 1,
    "donations": [
      {
        "id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
        "donor_user_id": "...",
        "amount": "100000.00",
        "donation_type": "open",
        "status": "open",
        "created_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not MORIA superadmin

---

POST /v1/donations/allocate bearer

Allocate a batch of OPEN donations to a single active cause. Atomic — if any donation is invalid (already allocated / cause not active), the entire batch is rolled back.

bearer MORIA allocate-open-donation RESOURCE_UPDATED

Request body — AllocateDonationsBatchDto

Field	Type	Required	Notes
donation_ids	string[] (UUID)	✓	List of donations to allocate — all must be OPEN, not yet allocated, and exist
cause_id	string (UUID)	✓	Target cause; must be in status ACTIVE

Example request

{
  "donation_ids": [
    "be2cb7da-e217-401c-8d07-b01e64adfb34",
    "a1f2c3d4-5678-90ab-cdef-1234567890ab"
  ],
  "cause_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Donations allocated",
  "data": { "allocated_count": 2, "cause_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Errors

Status	When it occurs
400 Bad Request	Some donations are non-OPEN / already allocated / cause not active
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not MORIA superadmin
404 Not Found	Donation or cause not found

---

PATCH /v1/charitable-causes/:id/approve bearer

Approve a cause currently in pending. MORIA superadmin only. After approval, the status moves to approved / active per the service logic.

bearer MORIA approve-charitable-cause RESOURCE_UPDATED

Path params

Param	Type	Notes
id	UUID	Cause ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Cause approved successfully",
  "data": { "...": "CauseDto shape, status='active'" }
}

Errors

Status	When it occurs
400 Bad Request	Cause was already approved
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not MORIA superadmin
404 Not Found	Cause not found

---

Reference

Enum: CharitableCauseStatus

• pending — awaiting MORIA approval
• new — newly created (internal variant)
• active — accepting donations
• approved — approved by admin
• in_progress — disbursement in progress
• completed — target reached / finished
• cancelled — cancelled
• rejected — approval rejected
• deactivated — soft-cancelled
• all — filter sentinel (no filter)

Enum: DonationType

• specific — donor picks the cause
• open — no cause, allocated by admin
• subscription — recurring

Enum: CauseOwner

• organization · individual · moria

Standard error envelope

{
  "message": "target_amount must be a number",
  "statusCode": 400,
  "error": "Bad Request"
}

Common HTTP codes

• 400 validation · donation already allocated · cause already approved
• 401 token expired / missing
• 403 not creator/manager · not MORIA
• 404 cause/donation not found
• 500 internal — show a generic toast