Saving Goals

The Saving Goals API lets your end-users set aside money toward named targets — Hajj, education, emergency fund — with a fixed monthly auto-debit from their main balance into a per-goal holding. 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 permission
Lifecycle	new · active · paused · completed · cancelled · converted
Currency	IDR · amounts as integer-string (smallest unit)
Integration	~1–2 sprints for a typical mobile or web client

What Saving Goals does

A saving goal represents an intent to set aside funds toward a named target over a defined period. Once created, the system automatically debits a fixed amount each month from the owner’s main balance into a holding dedicated to that goal. The owner can pause auto-debit, withdraw funds back to the main balance, or let the goal mature toward its target.

Hajj Fund — a 5-year goal with liquidity_type: "locked" and a monthly deduction equal to target_amount / months. The end-user watches the progress bar tick up each cycle.

Emergency fund — a short-term goal with liquidity_type: "loose". The owner can withdraw at any time; auto-debit stops as soon as they pause or delete the goal.

Education fund — a medium-term goal that an organization admin can set up on behalf of a member, including a manual deduction endpoint for off-schedule one-time contributions.

What it is not. Saving Goals does not pull funds from external banks, does not earn interest on stored funds, and does not move funds between goals. Funds must already exist in the main balance before auto-debit can run; withdrawals release funds back to the same main balance.

---

Where the money lives

flowchart LR
    U([Account owner])

    TOPUP[/"Top-up<br/>(payment gateway)"/]

    subgraph WALLET[" Wallet "]
        direction TB
        MAIN[("Main balance<br/>(primary cash)")]
        HOLD[("Goal holding<br/>(per saving goal)")]
        MAIN -->|"auto-debit on<br/>deduction_date (monthly)"| HOLD
        HOLD -->|"manual withdrawal or<br/>on completion"| MAIN
    end

    PAYOUT[/"Disbursement to<br/>external bank"/]
    WITHDRAW[/"POST /v1/withdrawals<br/>reference_type: saving_goal"/]

    TOPUP -->|credit| MAIN
    MAIN -->|"withdrawal to bank<br/>(separate flow)"| PAYOUT

    U -.->|creates goal| HOLD
    U -.->|reads saved_amount| HOLD
    U -.->|initiates| WITHDRAW

    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 money;
    class TOPUP,WITHDRAW,PAYOUT edge;
    class U user;

---

Status transitions

stateDiagram-v2
    direction LR

    [*] --> new: POST /v1/saving-goals<br/>(transient)
    new --> active: created with<br/>default state

    active --> paused: PATCH /:id/pause<br/>{ pause: true }
    paused --> active: PATCH /:id/pause<br/>{ pause: false }

    active --> completed: holding reaches 0<br/>(automatic, after<br/>full withdrawal)

    active --> cancelled: DELETE /:id<br/>(terminal)
    paused --> cancelled: DELETE /:id<br/>(terminal)

    active --> converted: terminal<br/>(reserved)

    completed --> [*]
    cancelled --> [*]
    converted --> [*]

    note right of active
        Auto-deduction runs
        on deduction_date
        every month
    end note

    note right of paused
        Auto-deduction is
        skipped. Manual
        deduction can still
        be called by org admin.
    end note

---

Endpoint reference

Method	Path	Purpose	Permission
POST	/v1/saving-goals	Create a new goal for an account	create-saving-goal
GET	/v1/saving-goals	List goals (paginated, filterable)	read-saving-goal
GET	/v1/saving-goals/:id	Fetch a single goal by id	read-saving-goal
PATCH	/v1/saving-goals/:id	Update editable metadata (name, end date, etc.)	update-saving-goal
PATCH	/v1/saving-goals/:id/pause	Pause or resume auto-debit	pause-saving-goal
PATCH	/v1/saving-goals/:id/manual-deduction	One-time contribution (org admin only)	update-saving-goal
DELETE	/v1/saving-goals/:id	Soft-delete a goal (terminal)	delete-saving-goal
GET	/v1/summary/saving-goals	Aggregate statistics (org admin only)	read-saving-goal

Withdrawal is not on this surface — withdrawals use the platform-wide withdrawal endpoint with a saving-goal reference. See the withdrawal section below.

---

Creating a saving goal

Request

POST /v1/saving-goals
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_id": "a8c1-...-c9f0",
  "name": "Hajj Fund",
  "target_amount": "50000000",
  "deduction_amount": "1000000",
  "deduction_date": 25,
  "start_date": "2026-06-01",
  "end_date": "2030-06-01",
  "liquidity_type": "locked"
}

Response · 201 Created

{
  "data": {
    "savingGoal": {
      "id": "9f3b-...-1d22",
      "account_id": "a8c1-...-c9f0",
      "name": "Hajj Fund",
      "status": "active",
      "target_amount": "50000000",
      "saved_amount": "0",
      "deduction_amount": "1000000",
      "deduction_date": 25,
      "start_date": "2026-06-01",
      "end_date": "2030-06-01",
      "liquidity_type": "locked",
      "created_at": "2026-05-18T03:12:44Z"
    }
  }
}

Validation rules to know

account_id must belong to the caller (or to a member of their organization, for org admins). target_amount and deduction_amount are decimal-strings in the smallest IDR unit. deduction_date is an integer 1–28 (safe across all months). end_date must be after start_date. liquidity_type is "loose" or "locked" (default "loose").

---

How funds enter the goal

sequenceDiagram
    autonumber
    actor U as Account owner
    participant API as Moria API
    participant SCH as Scheduler
    participant MAIN as Main balance
    participant HOLD as Goal holding

    Note over U,API: One-time setup
    U->>API: POST /v1/saving-goals<br/>{ account_id, name, target_amount,<br/>deduction_amount, deduction_date,<br/>start_date, end_date, liquidity_type }
    API-->>U: 201 Created<br/>{ savingGoal: { id, status: "active", ... } }

    Note over SCH,HOLD: Every month, on deduction_date
    SCH->>API: trigger auto-deduction sweep
    API->>MAIN: read available balance for account_id
    MAIN-->>API: balance

    alt sufficient funds
        API->>MAIN: debit deduction_amount
        API->>HOLD: credit deduction_amount
        API->>API: refresh saved_amount on goal
    else insufficient funds
        API->>API: skip this cycle<br/>(goal stays active)
    end

    Note over U,API: Owner reads progress
    U->>API: GET /v1/saving-goals/:id
    API-->>U: { id, status, saved_amount,<br/>target_amount, progress%, ... }

---

Auto and manual deduction

Auto-debit · monthly

• Runs on the deduction_date day each month, starting from start_date
• Debits deduction_amount from the owner’s main balance, credits the goal-specific holding
• Updates saved_amount on the goal — which your client polls or displays
• Silently skipped when the main balance is insufficient — the goal stays active and tries again next cycle
• Does not run when the goal is paused, completed, cancelled, or converted

Manual deduction · org admin only

PATCH /v1/saving-goals/:id/manual-deduction
Authorization: Bearer <token>

{ "deduction_amount": "500000" }

A one-time contribution off the monthly schedule. Useful for ad-hoc top-ups (year-end bonus, employer match). The same balance check applies — the caller must have funds in the main balance. Available only to organization admins; individuals cannot call this.

Both paths use the same money mechanic: a debit on the main balance is paired with a credit on the goal-specific holding. saved_amount on the goal reflects the holding, so a single read gives you the progress number.

---

Returning funds to the main balance

Request

POST /v1/withdrawals
Authorization: Bearer <token>

{
  "reference_type": "saving_goal",
  "reference_id": "9f3b-...-1d22",
  "amount": "2000000"
}

Withdrawal uses the platform-wide withdrawal endpoint. reference_type tells the system to debit the goal-specific holding, not some other source.

What happens

• The system debits the goal’s holding by amount
• Credits the owner’s main balance by the same amount
• Refreshes saved_amount on the goal
• If the holding reaches zero, the goal automatically transitions to completed
• No external bank transfer — funds simply return to the main balance and the owner can use them anywhere

A note on liquidity

liquidity_type: "locked" is currently informational — it signals product intent, but the withdrawal endpoint will not currently reject withdrawals on locked goals. If your product needs a hard lock, enforce it in your client until the platform adds server-side enforcement.

---

Pause and resume

Pause

PATCH /v1/saving-goals/:id/pause
Authorization: Bearer <token>

{ "pause": true }

Sets status to paused. Auto-debit stops on the next cycle.

Resume

PATCH /v1/saving-goals/:id/pause
Authorization: Bearer <token>

{ "pause": false }

Returns the goal to active. Auto-debit resumes from the next scheduled deduction_date.

What pause does *not* do

• Does not backfill missed cycles on resume — you simply pick up at the next deduction_date
• Does not block manual deduction — org admins can still top up while paused
• Does not block withdrawal — owners can still withdraw funds already saved
• Cannot transition from completed, cancelled, or converted — those are terminal

---

List and filter

Request

GET /v1/saving-goals?status=active
     &liquidity_type=locked
     &page=1&limit=20
Authorization: Bearer <token>

Returns a paginated data envelope of goals visible to the caller. Individuals see their own goals; organization admins see goals across all members in their organization.

Query parameters

Param	Values	Notes
status	active · paused · completed · cancelled · converted	Filter by state
liquidity_type	locked · liquid	Filter by liquidity
account_id	uuid	Scope to a single account
owner_id	uuid	Org admin only · scope to a single member
page	integer, default 1	1-indexed
limit	integer, default 20	Page size

Responses wrap the list inside data with pagination metadata. 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	Meaning · how to respond
400	Validation	Body fails schema validation — missing field, wrong type, deduction_date out of range, end_date before start_date. Show an inline message.
401	Bearer token missing or invalid	Token expired, malformed, or absent. Re-authenticate and retry.
403	Missing permission or ownership	The caller lacks the required permission (e.g. an individual trying to call manual-deduction) or operates on a goal that is not theirs. Do not retry — surface as an access-denied state.
404	Unknown goal id	Goal does not exist or has been soft-deleted. Refresh the list and remove the stale entry.
409	Illegal state transition	Attempting to pause a completed goal, manual-deduct a cancelled goal, etc. Re-fetch the goal to learn its current state.
422	Insufficient main balance	Manual deduction (or any flow touching the main balance) cannot proceed because the owner’s funds are insufficient. Prompt the owner to top up.
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": "deduction_date must be between 1 and 28", "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-saving-goal	POST create
read-saving-goal	GET list · GET one · GET summary
update-saving-goal	PATCH update · PATCH manual-deduction
pause-saving-goal	PATCH pause
delete-saving-goal	DELETE

Visibility rules

• Individuals see and act only on their own goals (where the underlying account belongs to them)
• Organization admins see goals across all members in their organization and can use owner_id for scoping
• Manual deduction and summary are restricted to organization admins, regardless of the granted permission
• Goals not visible to the caller return 404 — not 403 — to avoid leaking existence

---

What is not supported, and how to work around it

No withdrawal from external banks

Auto-debit only pulls from the main balance. Workaround: prompt the owner to keep the main balance topped up; surface the next deduction date and amount in your UI so they can plan.

No interest accrual

Stored amounts do not earn yield. Workaround: if your product needs yield, add it on your side and reconcile to the goal’s saved_amount; or route part of the balance to a separate investment surface.

No inter-goal transfers

Funds can only move holding ↔ main balance. Workaround: withdraw first to the main balance, then trigger a manual deduction to the destination goal.

`liquidity_type: "locked"` is not yet server-side enforced

“Locked” goals can still be withdrawn from. Workaround: enforce the lock in your client (hide the withdraw control, or show a confirmation modal). Server-side enforcement is on the roadmap.

Goal names are not unique

An owner can have two goals named “Hajj Fund”. Workaround: if uniqueness matters to your UX, check the existing list before creating and prompt the user to disambiguate.

Insufficient-balance cycles pass silently

If a monthly deduction is missed due to insufficient funds, no notification event is emitted from this surface. Workaround: poll the goal’s saved_amount after each expected deduction_date and compare to the expected progression to detect misses.

---

Integration checklist

Before go-live

• Token plumbing — your client obtains the JWT from the platform’s auth flow and forwards it on every saving-goals call
• Permissions confirmed — the role assigned to your end-users has the saving-goal permissions you need (read at minimum, plus create/update/pause/delete per your UX)
• Synchronous validation — your client ensures deduction_date is 1–28, end_date > start_date, amounts are positive, and liquidity_type is sensible before POST
• State-aware UI — controls are hidden or disabled for terminal states (completed, cancelled, converted) and you handle 409 transition errors as a refresh trigger

Operational readiness

• Withdrawal wiring — your client uses POST /v1/withdrawals with reference_type: "saving_goal", and handles the auto-completed transition when the holding reaches zero
• Insufficient-balance UX — when a deduction is silently skipped, your UI shows the owner why and how to top up the main balance
• Locked-goal enforcement — if your product offers a locked variant, your client refuses withdrawals until server-side enforcement ships
• Error envelope — your error handler reads { statusCode, message, error } and maps it to inline / toast / modal patterns in your design system

---

Build with confidence

What is already working well

• Small surface — eight endpoints plus one shared withdrawal call cover the entire product
• Predictable money model — every contribution is a debit on the main balance + a credit on the goal holding; saved_amount on the goal is the only number you need to display
• Clean lifecycle — six explicit statuses with documented transitions; auto-completed on zero holding makes “goal done” reactions easy
• Forward-compatible envelope — responses are always wrapped inside data, so future fields will not break your parser

What to be aware of

• Hold the lock on your side until server-side enforcement for liquidity_type: "locked" ships
• Detect silent skips — poll saved_amount after each deduction_date and reconcile to the expected progression
• Disambiguate goal names in your UI; uniqueness is not enforced server-side
• Plan the top-up path — auto-debit needs funds in the main balance, so your onboarding should make top-up obvious

Saving Goals is a deliberately small surface, designed to compose with the rest of the platform — top-ups land in the main balance, withdrawals exit through the same generic withdrawal endpoint, and goals themselves just express a contract: “this much, per month, into a named holding.” Knowing the lifecycle, the money flow, and a handful of notes above is enough to ship a production integration.