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)

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).
Under Architecture B, ownership is derived from the JWT — clients no longer send account_id on create. The creator’s pocket source is resolved server-side from getUserMainAccount(user.id).

`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
`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
`user_id`	string (UUID)	optional	New. When set, the admin creates an INDIVIDUAL-owned circle on behalf of this member (who must belong to the admin’s own organization). The target member is recorded as the first member (turn 0) using their main pocket as the contribution source. When omitted, the circle is ORGANIZATION-owned and starts with no members — they are added via `POST /saving-circles/:id/members`.
`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

{
  "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, legacy `account_id` field sent)
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Missing `create-saving-circle` permission · org admin sent a `user_id` for a user outside their organization

`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 — own circles.
ORGANIZATION admin — the combined set of org-owned circles (owner_type=ORGANIZATION, owner_id=admin's org) and circles owned by individual members of the same organization (member-individual circles are scoped via users.organization_id — they do not leak across orgs). When user_id is supplied (must belong to the admin’s org), it narrows results: for org-owned circles, to those the user participates in as a member; for individual-owned circles, to those owned by that user.
MORIA — all.

Also supports organization_id for marketplace lookup (searching for public circles in another org).

Web / mobile — honors x-client-type (default mobile). See Client types (web vs mobile) for the full rules. Concretely: web nests audit fields as created/updated/deleted { at, by } objects and replaces relations with formatted owner/account/members objects (and a members_count); mobile returns the raw entity with flat created_at/updated_at + created_by/updated_by/deleted_by and foreign-key ids (owner_id, account_id) plus the raw members array.

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 — `mobile` (default)

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circles fetched successfully",
  "data": {
    "limit": 10,
    "count": 8,
    "currentPage": 1,
    "totalPages": 1,
    "savingCircles": [
      {
        "id": "f43a4ded-c64e-4a43-9a70-a5fe52d3a8f6",
        "created_at": "2026-05-22T13:59:46.545Z",
        "updated_at": "2026-05-22T13:59:46.545Z",
        "created_by": "1d534abe-7b53-43bc-9240-b17373dc670a",
        "updated_by": "00000000-0000-0000-0000-000000000000",
        "deleted_by": "00000000-0000-0000-0000-000000000000",
        "name": "Org Circle",
        "slug_name": "org_circle",
        "owner_type": "organization",
        "owner_id": "6f17cd3d-56ea-4bda-afbd-0350f6a56dd1",
        "capacity": 3,
        "current_turn": 0,
        "visibility": "private",
        "lump_sum": "9000.0000",
        "contribution_amount": "3000.0000",
        "start_date": "2027-01-01",
        "end_date": "2027-04-01",
        "duration": 3,
        "status": "active",
        "account_id": "750fd44c-2872-4a4e-8df9-40e638d01d42",
        "deduction_date": 28,
        "deduction_failed_attempts": 0,
        "deduction_next_retry_date": null,
        "members": []
      }
    ]
  },
  "lang": "en"
}

Response — `web` (`x-client-type: web`)

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circles fetched successfully",
  "data": {
    "limit": 10,
    "count": 8,
    "currentPage": 1,
    "totalPages": 1,
    "savingCircles": [
      {
        "id": "f43a4ded-c64e-4a43-9a70-a5fe52d3a8f6",
        "created": {
          "at": "2026-05-22T13:59:46.545Z",
          "by": {}
        },
        "updated": {
          "at": "2026-05-22T13:59:46.545Z",
          "by": {}
        },
        "deleted": {
          "at": null,
          "by": {}
        },
        "name": "Org Circle",
        "capacity": 3,
        "current_turn": 0,
        "visibility": "private",
        "lump_sum": "9000.0000",
        "contribution_amount": "3000.0000",
        "start_date": "2027-01-01",
        "end_date": "2027-04-01",
        "duration": 3,
        "status": "active",
        "owner_type": "organization",
        "owner_id": "6f17cd3d-56ea-4bda-afbd-0350f6a56dd1",
        "members_count": 0,
        "owner": {}
      }
    ]
  },
  "lang": "en"
}

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.

Web / mobile — honors x-client-type (default mobile). See Client types (web vs mobile) for the full rules. Concretely: web nests audit fields as created/updated/deleted { at, by } objects and exposes a formatted owner object; mobile returns the raw entity with flat created_at/updated_at + created_by/updated_by/deleted_by and foreign-key ids (owner_id, account_id). Both shapes carry the same members and member_contributions arrays.

bearer read-saving-circle

Path params

Param	Type	Notes
`id`	UUID	Saving circle ID

Response — `mobile` (default)

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circle fetched successfully",
  "data": {
    "savingCircle": {
      "id": "f43a4ded-c64e-4a43-9a70-a5fe52d3a8f6",
      "created_at": "2026-05-22T13:59:46.545Z",
      "updated_at": "2026-05-22T13:59:46.545Z",
      "created_by": "1d534abe-7b53-43bc-9240-b17373dc670a",
      "updated_by": "00000000-0000-0000-0000-000000000000",
      "deleted_by": "00000000-0000-0000-0000-000000000000",
      "name": "Org Circle",
      "slug_name": "org_circle",
      "owner_type": "organization",
      "owner_id": "6f17cd3d-56ea-4bda-afbd-0350f6a56dd1",
      "capacity": 3,
      "current_turn": 0,
      "visibility": "private",
      "lump_sum": "9000.0000",
      "contribution_amount": "3000.0000",
      "start_date": "2027-01-01",
      "end_date": "2027-04-01",
      "duration": 3,
      "status": "active",
      "account_id": "750fd44c-2872-4a4e-8df9-40e638d01d42",
      "deduction_date": 28,
      "deduction_failed_attempts": 0,
      "deduction_next_retry_date": null,
      "members": [],
      "member_contributions": [
        {
          "user_id": "",
          "total_contribution": "0.00",
          "contribution_count": 0
        }
      ]
    }
  },
  "lang": "en"
}

Response — `web` (`x-client-type: web`)

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving circle fetched successfully",
  "data": {
    "savingCircle": {
      "id": "f43a4ded-c64e-4a43-9a70-a5fe52d3a8f6",
      "created": {
        "at": "2026-05-22T13:59:46.545Z",
        "by": {}
      },
      "updated": {
        "at": "2026-05-22T13:59:46.545Z",
        "by": {}
      },
      "deleted": {
        "at": null,
        "by": {}
      },
      "name": "Org Circle",
      "capacity": 3,
      "current_turn": 0,
      "visibility": "private",
      "lump_sum": "9000.0000",
      "contribution_amount": "3000.0000",
      "start_date": "2027-01-01",
      "end_date": "2027-04-01",
      "duration": 3,
      "status": "active",
      "owner_type": "organization",
      "owner_id": "6f17cd3d-56ea-4bda-afbd-0350f6a56dd1",
      "owner": null,
      "members": [],
      "member_contributions": [
        {
          "user_id": "",
          "total_contribution": "0.00",
          "contribution_count": 0
        }
      ]
    }
  },
  "lang": "en"
}

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

Saving Circles

Summary

POST /v1/saving-circles bearer

Request body — CreateSavingCircleDto (regular user)

Request body — AdminCreateSavingCircleDto (MORIA / ORGANIZATION)

Example request

Response — 201 Created

Errors

POST /v1/saving-circles/members bearer

Request body — AddSavingCircleMemberDto

Example request

Response — 201 Created

Errors

POST /v1/saving-circles/contribute bearer

Request body — ContributeToSavingCircleDto

Example request

Response — 200 OK

Errors

Side effects

GET /v1/saving-circles bearer

Query params

Response — mobile (default)

Response — web (x-client-type: web)

Errors

GET /v1/saving-circles/:id bearer

Path params

Response — mobile (default)

Response — web (x-client-type: web)

Errors

PATCH /v1/saving-circles/:id bearer

Path params

Request body — UpdateSavingCircleDto

Example request

Response — 200 OK

Errors

DELETE /v1/saving-circles/:id bearer

Path params

Response — 200 OK

Errors

GET /v1/summary/saving-circles bearer

Response — 200 OK

Errors

Reference

Enum: SavingCircleStatus

Enum: Visibility

Enum: ContributionStatus

Enum: ContributionRail

Standard error envelope

Common HTTP codes

`POST /v1/saving-circles` bearer

Request body — `CreateSavingCircleDto` (regular user)

Request body — `AdminCreateSavingCircleDto` (MORIA / ORGANIZATION)

Response — `201 Created`

`POST /v1/saving-circles/members` bearer

Request body — `AddSavingCircleMemberDto`

Response — `201 Created`

`POST /v1/saving-circles/contribute` bearer

Request body — `ContributeToSavingCircleDto`

Response — `200 OK`

`GET /v1/saving-circles` bearer

Response — `mobile` (default)

Response — `web` (`x-client-type: web`)

`GET /v1/saving-circles/:id` bearer

Response — `mobile` (default)

Response — `web` (`x-client-type: web`)

`PATCH /v1/saving-circles/:id` bearer

Request body — `UpdateSavingCircleDto`

Response — `200 OK`

`DELETE /v1/saving-circles/:id` bearer

Response — `200 OK`

`GET /v1/summary/saving-circles` bearer

Response — `200 OK`

Enum: `SavingCircleStatus`

Enum: `Visibility`

Enum: `ContributionStatus`

Enum: `ContributionRail`