Charitable Cause

The Charitable Cause API lets your end-users — individuals or organizations — launch fundraising projects for social causes and accept donations from any verified Moria user. Every cause is reviewed and approved before it can accept donations; donations flow through the same balance-and-gateway payment rails as the rest of the platform. 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 · active · completed · cancelled · rejected · deactivated
Currency	IDR · amounts as decimal numbers (smallest unit)
Integration	~1–2 sprints for a typical mobile or web client

What Charitable Cause does

A charitable cause is a fundraising project with a target amount, description, regulations, and a stated benefit. A user or organization creates a cause; a Moria reviewer approves it; once approved, donors can contribute from their Moria balance or via a payment-gateway top-up. The cause accumulates a collected_amount until it reaches the target or is closed. Funds in the cause pool are collected out through a withdrawal endpoint to the cause owner’s main balance.

Disaster relief

An organization launches a cause for flood relief in West Java with a target of 500,000,000 IDR. Members donate from their main balance; the public donates via the gateway rail. The organization manager withdraws the collected funds for on-the-ground distribution.

Education scholarship

An individual creates a cause to fund one student’s tuition for a year. Friends and family donate; the creator (automatically appointed as a manager) tracks collected_amount against the target and withdraws once the goal is met.

Community project

A mosque committee creates a cause to install a new water pump. The committee appoints additional managers to oversee disbursement; donations and progress appear in every member’s app via the cause endpoints.

What it is not. Charitable Cause is not a direct merchant payout — collected funds land in a Moria-managed pool bound to the cause, not in the owner’s external bank account. It does not run recurring donation subscriptions itself; recurring donations are a future surface. It does not auto-disburse on completion — collecting out of the pool is an explicit withdrawal call.

---

Where the money sits

flowchart LR
    D([Donor])
    M([Cause manager])

    subgraph DONOR_WALLET[" Donor wallet "]
        DMAIN[("Donor<br/>main balance")]
    end

    subgraph CAUSE[" Charitable cause "]
        POOL[("Cause pool<br/>(collected_amount)")]
    end

    subgraph OWNER_WALLET[" Owner wallet "]
        OMAIN[("Owner<br/>main balance")]
    end

    TOPUP[/"Top-up via<br/>payment gateway"/]
    DONATE[/"POST /v1/payments/balance<br/>reference_type:<br/>charitable_cause_donate"/]
    WITHDRAW[/"POST /v1/withdrawals<br/>reference_type: donation"/]

    TOPUP -->|credit| DMAIN
    DMAIN -->|"donation (balance rail)"| POOL
    TOPUP -.->|"donation (gateway rail)"| POOL
    POOL -->|"collection initiated<br/>by manager"| OMAIN

    D -.->|reads progress| POOL
    M -.->|manages cause| POOL

    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 DMAIN,POOL,OMAIN money;
    class TOPUP,DONATE,WITHDRAW edge;
    class D,M user;

---

Status transitions

stateDiagram-v2
    direction LR

    [*] --> pending: POST /v1/charitable-causes<br/>(awaiting review)

    pending --> active: PATCH /v1/charitable-causes/<br/>:id/approve<br/>(admin only)
    pending --> rejected: admin rejects

    active --> completed: collected_amount<br/>reaches target_amount
    active --> cancelled: DELETE /:id<br/>(creator / owner)
    active --> deactivated: admin action

    completed --> [*]
    rejected --> [*]
    cancelled --> [*]
    deactivated --> [*]

    note right of pending
        Donations are NOT accepted
        until the cause is approved.
    end note

    note right of active
        Donations are accepted.
        Edits allowed until
        the cause completes.
    end note

---

Endpoint reference

Method	Path	Purpose	Permission
POST	/v1/charitable-causes	Create a new cause (starts in pending)	create-charitable-cause
GET	/v1/charitable-causes	List causes (paginated, filterable)	read-charitable-cause
GET	/v1/charitable-causes/:id	Fetch a single cause by id	read-charitable-cause
PATCH	/v1/charitable-causes/:id	Update editable metadata (name, description, target, media)	update-charitable-cause
DELETE	/v1/charitable-causes/:id	Cancel a cause (terminal; sweeps remaining balance)	delete-charitable-cause
POST	/v1/charitable-causes/:id/assign-manager	Appoint an additional manager (creator only)	update-charitable-cause
PATCH	/v1/charitable-causes/:id/approve	Approve a pending cause (admin only)	approve-charitable-cause
GET	/v1/summary/charitable-causes	Aggregate statistics for an organization’s causes	read-charitable-cause
GET	/v1/donations/open	List unallocated open donations (admin only)	allocate-open-donation
POST	/v1/donations/allocate	Allocate a batch of open donations to a cause (admin only)	allocate-open-donation

Donations are not on this surface — they use the platform-wide payments endpoints with reference_type: "charitable_cause_donate". Collecting funds out of a cause pool uses the platform-wide withdrawals endpoint with reference_type: "donation". See the donations and withdrawal sections below.

---

Creating a cause

Request

POST /v1/charitable-causes
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_id": "a8c1-...-c9f0",
  "name": "Flood Relief West Java",
  "description": "Emergency aid for families affected by the January floods.",
  "target_amount": 50000000,
  "currency": "IDR",
  "regulations": "All funds disbursed via on-site partner.",
  "benefit": "Food, shelter, clean water for 200 families.",
  "location": "Jakarta, Indonesia",
  "photo_document_id": "f1c2-...-9aa8",
  "video_document_id": "b3d4-...-2eee"
}

Response · 201 Created

{
  "data": {
    "cause": {
      "id": "9f3b-...-1d22",
      "account_id": "a8c1-...-c9f0",
      "name": "Flood Relief West Java",
      "slug_name": "flood_relief_west_java",
      "status": "pending",
      "cause_owner": "individual",
      "target_amount": "50000000.0000",
      "collected_amount": "0.0000",
      "completion_percentage": 0,
      "currency": "IDR",
      "created_at": "2026-05-18T03:12:44Z"
    }
  }
}

Validation rules to know

account_id must belong to the caller (or the caller’s organization, for org admins). Individuals cannot create causes on an organization account — this returns 403. target_amount is a number in IDR; the system also accepts decimal precision. name, description, regulations, and benefit are required strings. photo_document_id and video_document_id are optional UUIDs referencing already-uploaded documents. Created causes start in pending and the creator is automatically added as the first manager.

---

Approval flow

Approving a pending cause

PATCH /v1/charitable-causes/:id/approve
Authorization: Bearer <token>

Transitions the cause from pending to active. Only callers with the approve-charitable-cause permission (Moria super-admin role) can call it. An already-approved cause returns 400.

{
  "data": {
    "cause": {
      "id": "9f3b-...-1d22",
      "status": "active",
      "approved_at": "2026-05-18T04:00:00Z"
    }
  }
}

Who does what

Step	Actor
Submit cause for review	Cause creator (individual or org admin)
Review and approve	Moria super-admin
Reject (out of band)	Moria super-admin — sets status: "rejected"
Accept donations	Any verified user, after approval
Withdraw collected funds	Cause owner or appointed manager

Donations attempted on a pending or rejected cause are rejected at the payments layer before any debit occurs.

Idempotency note

Approving a cause that is already active returns 400 with "cause already approved". Treat a 400 on this endpoint as a harmless no-op if your client resends the approval (e.g. after a network retry) — refresh the cause and reconcile.

---

Donating to a cause

---
config:
  sequence:
    actorMargin: 240
    width: 180
    messageMargin: 45
    boxMargin: 16
    noteMargin: 14
---
sequenceDiagram
    autonumber
    actor D as Donor
    participant API as Moria API
    participant WALLET as Donor balance
    participant POOL as Cause pool

    Note over D,API: One donation, balance rail
    D->>API: POST /v1/payments/balance<br/>{ reference_type: "charitable_cause_donate",<br/>reference_id: "cause-uuid",<br/>source_account_id, amount }
    API->>API: validate cause is active<br/>and visible to donor
    API->>WALLET: debit amount
    API->>POOL: credit amount<br/>(collected_amount += amount)
    API->>API: record donation row<br/>(donation_type: "specific")
    API-->>D: 201 Created<br/>{ data: { transaction_id,<br/>new_balance, reference_id } }

    Note over D,POOL: Notes<br/>- The gateway rail (POST /v1/payments/gateway) uses the same reference_type and credits the pool asynchronously on callback.<br/>- "Open" donations carry no reference_id and sit unallocated until an admin assigns them to a cause.

---

Rails and donation shapes

Balance rail (synchronous)

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

{
  "reference_type": "charitable_cause_donate",
  "reference_id": "9f3b-...-1d22",
  "source_account_id": "a8c1-...-c9f0",
  "amount": "100000"
}

Debits the donor’s specified Moria balance and credits the cause pool in a single transaction. Returns 201 with the donor’s new balance and the cause id.

Gateway rail (asynchronous)

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

{
  "reference_type": "charitable_cause_donate",
  "reference_id": "9f3b-...-1d22",
  "amount": "100000",
  "payment_id": "pay-..."
}

Returns a payment-gateway envelope (VA number / QR / payment link). The cause is credited when the gateway fires the payment.completed callback; until then, the cause’s collected_amount does not change.

Side effects per successful donation

• The cause’s collected_amount increases by amount and completion_percentage is recomputed
• A donations row is inserted with donation_type: "specific" and cause_id set to the cause
• A ledger entry records the fund movement: donor source → cause pool
• If the cause reaches or exceeds target_amount, status transitions to completed

---

Open donations and admin allocation

Open donation flow

A donor who does not pick a specific cause sends an open donation — the same payments endpoint, but with reference_type: "charitable_cause_open_donate". The donation row is created with cause_id: null and donation_type: "open"; funds land in a Moria-managed unallocated pool. An admin then assigns these donations to one or more active causes.

Admin batch allocation

POST /v1/donations/allocate
Authorization: Bearer <token>

{
  "donation_ids": [
    "d1f2-...-aaaa",
    "d2f3-...-bbbb"
  ],
  "cause_id": "9f3b-...-1d22"
}

Allocation constraints

All donations must be open, unallocated, and the cause must be active. The call is atomic — any failure rolls back the whole batch.

Open donations are useful when your client wants to offer a “donate to whatever Moria considers most urgent” path. Most integrators will not need them — use the charitable_cause_donate reference type with a specific reference_id for everyday donations.

---

Manager appointment

Request

POST /v1/charitable-causes/:id/assign-manager
Authorization: Bearer <token>

{
  "user_id": "u1b2-...-c3d4"
}

Only the cause creator can appoint additional managers. The creator is automatically appointed as the first manager when the cause is created, so this endpoint adds more.

What managers can do

• Read the cause and its donation activity
• Edit cause metadata (until the cause completes)
• Initiate withdrawal of collected funds from the cause pool to the cause owner’s main balance
• Cannot transfer ownership, cannot approve causes, cannot appoint other managers (creator only)

Common errors on this endpoint

• 400 — the user is already a manager of this cause
• 403 — caller is not the cause creator
• 404 — cause not found, or the appointed user id does not exist

---

Listing and filtering

Request

GET /v1/charitable-causes?status=active
     &organization_id=o7b3-...-eee1
     &page=1&limit=20
Authorization: Bearer <token>

Returns paginated data containing causes visible to the caller. Individuals see causes within their organization context (or their own account’s causes); organization admins see causes for all members in their organization.

Query parameters

Param	Value	Notes
status	pending · active · completed · cancelled · rejected · deactivated · all	Filter by state
organization_id	uuid	Scope to one organization’s causes
user_id	uuid	Filter by cause creator
account_id	uuid	Scope to a single account
page	integer, default 1	1-indexed
limit	integer, default 20	Page size
order	asc · desc	Sort direction

The response wraps the list inside data with pagination metadata (count, currentPage, totalPages, limit, causes). Plan your client to consume the object envelope, not a bare array — this is forward-compatible against future additions.

---

Errors you will encounter

Status	Typical trigger	What it means · how to respond
400	Validation or state	Body fails schema validation; or the request hits a domain rule (e.g. donating to a non-active cause, allocating already-allocated donations, approving a cause already active). Show the message inline.
401	Bearer token missing or invalid	Token expired, malformed, or absent. Re-authenticate and retry.
403	Permission or ownership missing	Caller lacks the required permission (e.g. an individual trying to approve), is operating on a cause they do not own, or is trying to appoint a manager when not the creator. Do not retry — surface as an access-denied state.
404	Unknown cause or donation id	Cause or donation does not exist, was soft-deleted, or is invisible to the caller. Refresh the list and remove stale entries.
422	Insufficient balance	A balance-rail donation cannot proceed because the donor’s source account has insufficient funds. Prompt the donor to top up via the payment gateway.
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": "Cause is not active (status: pending)", "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’s 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

Permission matrix

Permission	Used by
create-charitable-cause	POST create
read-charitable-cause	GET list · GET one · GET summary
update-charitable-cause	PATCH update · POST assign-manager · withdrawal
delete-charitable-cause	DELETE
approve-charitable-cause	PATCH approve (admin)
donate-charitable-cause	POST /payments/* with this reference type
allocate-open-donation	GET /donations/open · POST /donations/allocate

Visibility rules

• Individuals see and act on causes within their own organization context, and create only on their own account
• Organization admins see and manage causes for all members in their organization, including creating on behalf of members
• Moria super-admins see causes platform-wide, approve them, and allocate open donations
• Causes invisible to the caller return 404 — not 403 — to avoid leaking cross-organization existence

---

What is not supported, and how to work around it

No direct external disbursement

Collected funds are released to the cause owner’s main balance, not to an external bank account. Workaround: after withdrawing collected funds via POST /v1/withdrawals with reference_type: "donation", route them through the platform-wide bank-withdrawal flow as a separate step.

No recurring donations on this surface

A subscription donation type exists in the schema but is not yet exposed as a self-serve endpoint. Workaround: run recurring donations from your client by scheduling balance-rail donations on a cadence; surface the next charge date in your UI.

No auto-disbursement on completion

When a cause reaches its target and transitions to completed, the funds stay in the pool until the owner or a manager explicitly withdraws. Workaround: in your client, badge completed causes and prompt the manager to initiate a withdrawal.

Open-donation reconciliation is admin-driven

Open donations sit unallocated until an admin assigns them. Workaround: if your product depends on a deterministic destination, prefer the charitable_cause_donate reference type with a specific reference_id; use open donations for actual “any urgent cause” UX.

Cause names are not unique

A single owner can have two causes named “Flood Relief”. Workaround: if uniqueness matters for your UX, check the existing list before creating and ask the user to differentiate.

Approval is manual and out of band

Approval happens via an admin endpoint, not on a schedule. Workaround: your client should show a “pending review” state for newly created causes and poll the cause’s status; do not assume creation means live.

---

Integration checklist

Before go-live

• Token plumbing — your client obtains the JWT from the platform’s auth flow and forwards it on every charitable-cause call
• Permissions confirmed — the role assigned to your end-users has the permissions you need (read at minimum, plus create/update/delete/donate per your UX)
• Document upload ready — your client uploads cause photos and videos via POST /v1/documents/upload and sends the returned ids in photo_document_id and video_document_id on create
• State-aware UI — controls are hidden or disabled for terminal states (completed, cancelled, rejected, deactivated), and the donate button is suppressed for pending causes
• Approval polling — newly created causes show a “pending review” state in your UI until status changes to active

Operational readiness

• Donation wiring — your client uses POST /v1/payments/balance or /payments/gateway with reference_type: "charitable_cause_donate" and reflects the updated cause collected_amount after a successful donation
• Withdrawal wiring — managers can collect funds via POST /v1/withdrawals with reference_type: "donation" and reference_id set to the cause id
• Auto-completion handling — when a donation pushes collected_amount past target_amount, the cause auto-transitions to completed; your client refreshes and badges accordingly
• Error envelope — your error handler reads { statusCode, message, error } and maps it to inline / toast / modal patterns in your design system
• Pagination contract — your list parser consumes the object envelope inside data, not a bare array, so future fields do not break things

---

Build with confidence

What is already working well

• Small surface — ten endpoints plus the shared payments and withdrawals rails cover the whole product
• Predictable money model — every donation is a debit on the donor’s balance (or gateway source) + a credit on the cause pool; the cause’s collected_amount is the one number to display
• Clear lifecycle — six explicit statuses with documented transitions; auto-completion when collected_amount reaches target_amount makes the “goal hit” reaction easy
• Unified payment rails — donations share the same balance / gateway endpoints with the rest of the platform, so clients already integrated with payments are already halfway there
• Forward-compatible envelope — responses are always wrapped inside data, so future fields will not break your parser

What to be aware of

• Surface the pending state — newly created causes cannot accept donations until a Moria admin approves
• Withdraw, then disburse — funds land on the owner’s main balance, not an external account; plan a follow-up bank-withdrawal step in your UX
• Mirror auto-completion — refresh the cause on every donation response so the completed transition is reflected immediately
• Prefer specific over open — use charitable_cause_donate with a specific reference_id for everyday flows; use open donations for explicit “any urgent cause” UX
• Differentiate cause names in your UI; uniqueness is not enforced server-side

Charitable Cause is a small, opinionated surface designed to compose with the rest of the platform — donations land via the shared payments rails, withdrawals exit via the shared withdrawals endpoint, and the cause itself simply expresses a contract: “this much, for this benefit, under these regulations, reviewed by Moria before going live.” Knowing the lifecycle, the money flow, and the few caveats above is enough to ship a production integration.