Saving Circles

Saving Circles is the implementation of Arisan rotational savings — a group of users contributes each round, and one member receives the payout per round. The module provides circle CRUD, member management, contributions (gateway or balance rail), and admin summaries. POST /saving-circles accepts two DTO shapes: CreateSavingCircleDto (regular user) or AdminCreateSavingCircleDto (admin creating on behalf of employees).

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, payment-gateway (bisabiller), users, organizations, withdrawal
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Typical flow: create circle → add members (member accounts) → each round members contribute (gateway VA / QR or balance debit) → the round winner receives the payout. Organization admins can view statistics summaries for circles in their org. The visibility field controls whether the circle is discoverable in other orgs’ marketplaces or kept private.

Method	Path	Summary
POST	/v1/saving-circles	Create a saving circle (regular or admin oneOf DTO)
POST	/v1/saving-circles/members	Add members to a circle
POST	/v1/saving-circles/contribute	Contribute to a circle (gateway / balance)
GET	/v1/saving-circles	List circles with status / org / user filters
GET	/v1/saving-circles/:id	Detail of a single circle
PATCH	/v1/saving-circles/:id	Update circle parameters
DELETE	/v1/saving-circles/:id	Delete a circle (not allowed when there are active contributions)
GET	/v1/summary/saving-circles	Statistics summary (admin MORIA/ORGANIZATION)

Auth + DTO notes

• The POST /saving-circles endpoint accepts oneOf CreateSavingCircleDto (regular user) or AdminCreateSavingCircleDto (MORIA/ORGANIZATION). The server picks the path based on the caller’s user_type.
• Circle owner types are only individual or organization — there is no MORIA-owned circle (the DB enum SavingCircleOwnerType rejects it).
• Balance-rail contributions are immediately COMPLETED; gateway-rail contributions remain PENDING until the Bisabiller callback (see the payment-gateway module).
• Authorization filtering follows the same layered model as saving-goals (INDIVIDUAL → self, ORGANIZATION → org, MORIA → unrestricted).

---

POST /v1/saving-circles bearer

Create a new saving circle. The server picks the DTO based on user_type: INDIVIDUAL uses CreateSavingCircleDto, MORIA/ORGANIZATION uses AdminCreateSavingCircleDto (creating a circle for employees).

bearer create-saving-circle RESOURCE_CREATED

Request body — CreateSavingCircleDto (regular user)

Field	Type	Required	Notes
account_id	string (UUID)	✓	Source account of the circle owner
name	string	✓	Circle name (e.g. Hajj)
capacity	number	optional	Maximum number of members, min 1
start_date	date (ISO 8601)	✓	Start date of the first round
amount	string	✓	Contribution nominal per round (rupiah)

Request body — AdminCreateSavingCircleDto (MORIA / ORGANIZATION)

Field	Type	Required	Notes
account_id	string (UUID)	✓	Sponsoring organization account
name	string	✓	Circle name
capacity	number	optional	Maximum number of members
start_date	date (ISO 8601)	✓	Start date
amount	string	✓	Contribution nominal per round

Example request

{
  "account_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
  "name": "Hajj",
  "capacity": 10,
  "start_date": "2028-02-06",
  "amount": "240000000"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Saving circle created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Hajj",
    "amount": "240000000.0000",
    "capacity": 10,
    "current_turn": 0,
    "start_date": "2028-02-06",
    "status": "new",
    "visibility": "private",
    "owner_type": "individual",
    "owner_id": "770e8400-e29b-41d4-a716-446655440222",
    "account_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
    "created_at": "2026-05-20T08:30:00.000Z"
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (capacity < 1, invalid date)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing create-saving-circle permission

---

POST /v1/saving-circles/members bearer

Add new members to an existing saving circle. Only the creator or an admin may add. Send a list of account_ids for prospective members.

bearer create-saving-circle RESOURCE_UPDATED

Request body — AddSavingCircleMemberDto

Field	Type	Required	Notes
saving_circle_id	string (UUID)	✓	Target circle
account_ids	string[] (UUID)	optional	List of prospective member accounts

Example request

{
  "saving_circle_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_ids": [
    "03be5259-f281-478e-a8d0-e7e825e525f2",
    "03be5259-f281-478e-a8d0-e7e825e525f3"
  ]
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Members added successfully",
  "data": { "members": [ { "id": "...", "saving_circle_id": "...", "account_id": "...", "turn_number": null } ] }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed · circle is full · account is already a member
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not the circle creator/admin
404 Not Found	Circle not found

---

POST /v1/saving-circles/contribute bearer

A member contributes to the circle for the current round. Can use the balance rail (debit Moria balance directly) or the gateway rail (Bisabiller). Dedup rule: a row with status PENDING or COMPLETED for the same (circle_id, user_id, turn_number) rejects a repeat attempt; FAILED/CANCELLED rows allow retry.

bearer update-saving-circle CONTRIBUTION_MADE

Request body — ContributeToSavingCircleDto

Field	Type	Required	Notes
saving_circle_id	string (UUID)	✓	Target circle
contribution_amount	numeric string	✓	Must equal the circle’s per-round amount · IsNotZero + IsValidDecimal

Example request

{
  "saving_circle_id": "550e8400-e29b-41d4-a716-446655440000",
  "contribution_amount": "1000.00"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Contribution made successfully",
  "data": {
    "contribution": {
      "id": "880e8400-e29b-41d4-a716-446655440333",
      "saving_circle_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "770e8400-e29b-41d4-a716-446655440222",
      "amount": "1000.0000",
      "turn_number": 3,
      "status": "completed",
      "rail": "balance"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Amount does not match circle.amount · user already has a PENDING/COMPLETED row for this turn · insufficient balance
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not a circle member
404 Not Found	Circle not found

Side effects

• Inserts a row into saving_circle_contributions (status=PENDING for gateway, COMPLETED for balance).
• For balance rail: ledger transaction debits the user account and credits the holding circle account.
• Emits BusinessEvent CONTRIBUTION_MADE (impact MEDIUM).

---

GET /v1/saving-circles bearer

List saving circles. Scope depends on role: INDIVIDUAL sees their own circles, ORGANIZATION admin sees the org’s circles, MORIA sees all. Supports organization_id for marketplace lookup (searching for public circles in another org).

bearer read-saving-circle

Query params

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
status	enum SavingCircleStatus	optional	new, active, cancelled, completed
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; same authorization as saving-goals
account_id	string (UUID)	optional	Account filter; same authorization as saving-goals

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circles retrieved successfully",
  "data": {
    "limit": 10,
    "count": 5,
    "currentPage": 1,
    "totalPages": 1,
    "saving_circles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Hajj",
        "amount": "240000000.0000",
        "capacity": 10,
        "current_turn": 2,
        "status": "active",
        "visibility": "private",
        "owner_type": "individual",
        "owner_id": "770e8400-e29b-41d4-a716-446655440222"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid query param
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	INDIVIDUAL queries another user’s data · ORGANIZATION queries another org

---

GET /v1/saving-circles/:id bearer

Detail of a single saving circle, including members and a contributions summary. Response format differs between WEB and MOBILE.

bearer read-saving-circle

Path params

Param	Type	Notes
id	UUID	Saving circle ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "saving circle fetched successfully",
  "data": {
    "savingCircle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Hajj",
      "amount": "240000000.0000",
      "capacity": 10,
      "current_turn": 2,
      "status": "active",
      "visibility": "private",
      "owner_type": "individual",
      "members": [
        { "id": "...", "account_id": "...", "user_id": "...", "turn_number": 1 }
      ]
    }
  }
}

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 circle
404 Not Found	Circle not found

---

PATCH /v1/saving-circles/:id bearer

Update circle parameters. Only the creator or an admin may perform this. All fields are optional.

bearer update-saving-circle RESOURCE_UPDATED

Path params

Param	Type	Notes
id	UUID	Saving circle ID

Request body — UpdateSavingCircleDto

Field	Type	Notes
name	string	New name
capacity	number	New capacity
start_date	string	New start date (free-form string; ISO format recommended)
amount	string	Per-round contribution nominal
current_turn	number	Current turn
visibility	enum Visibility	private, public, organization

Example request

{ "capacity": 12, "visibility": "organization" }

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circle updated successfully",
  "data": { "...": "SavingCircleDto shape" }
}

Errors

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

---

DELETE /v1/saving-circles/:id bearer

Delete a saving circle. Not allowed if the circle is already ACTIVE with recorded contributions — use status cancellation elsewhere.

bearer delete-saving-circle RESOURCE_DELETED

Path params

Param	Type	Notes
id	UUID	Saving circle ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circle deleted successfully"
}

Errors

Status	When it occurs
400 Bad Request	Circle is ACTIVE with recorded contributions
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Not the creator/admin
404 Not Found	Circle not found

---

GET /v1/summary/saving-circles bearer

Organization-level saving circles statistics summary. Admin endpoint — only MORIA and ORGANIZATION. Includes totals, status breakdown, capacity utilization, etc.

bearer MORIA, ORGANIZATION read-saving-circle RESOURCE_FETCHED

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "saving circles summary fetched successfully",
  "data": {
    "organization_id": "660e8400-e29b-41d4-a716-446655440111",
    "organization_name": "Moria Fund",
    "total_circles": "8",
    "active_circles": "5",
    "completed_circles": "2",
    "cancelled_circles": "1",
    "total_contribution_amount": "120000000.00",
    "average_capacity": "8.50",
    "average_current_turn": "2.40"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Token invalid · querying another org (mismatch)
403 Forbidden	Role is not MORIA/ORGANIZATION
404 Not Found	Organization not found

---

Reference

Enum: SavingCircleStatus

• new — circle created, not yet running
• active — rounds in progress
• cancelled — cancelled
• completed — all rounds finished

Enum: Visibility

• private — only owner + members can see it
• public — discoverable in the cross-org marketplace
• organization — limited to organization members

Enum: ContributionStatus

• pending · completed · failed · cancelled · refunded

Enum: ContributionRail

• gateway — VA/QR via Bisabiller
• balance — direct debit of Moria balance

Standard error envelope

{
  "message": "capacity must be at least 1",
  "statusCode": 400,
  "error": "Bad Request"
}

Common HTTP codes

• 400 validation · circle full · insufficient balance · duplicate contribution
• 401 token expired / missing
• 403 not owner/member · wrong scope
• 404 circle not found
• 500 internal — show a generic toast