Accounts

The accounts module manages “pocket” / ledger accounts belonging to a user or organization. Every account has an account_number (encrypted + hash) used for internal transfers. The main endpoints: list/filter, transfer between accounts, detail by ID, label update, and soft-delete. All endpoints require Bearer and specific permissions (read-account, top-up-account, update-account, delete-account).

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

Summary

GET /accounts is polymorphic: with no filter → list of user/organization accounts (paginated); with user_id → accounts for a specific user; with account_number → a single account by number. The pair user_id + account_number cannot be sent together. Internal transfers use source & destination account_number (not the account UUID).

Method	Path	Summary
GET	/v1/accounts	List accounts or fetch detail by user_id/account_number
POST	/v1/accounts/transfer	Transfer funds between accounts (by account number)
GET	/v1/accounts/:id	Detail of one account by UUID
PATCH	/v1/accounts/:id	Update account (name, currency, account_type)
DELETE	/v1/accounts/:id	Soft delete an account

Key notes

• account_number is stored encrypted (@EncryptedColumn) plus a separate hash for lookup. FE only receives/displays the plaintext value already decrypted by the server.
• Transfers use account_number, not id. The source account must belong to the caller’s user/organization.
• DELETE is a soft-delete (sets deleted_at); the data remains in the DB.

---

GET /v1/accounts bearer

List accounts owned by the user (or the organization if the caller is UserType.ORGANIZATION). When user_id or account_number is sent, the response is a single account (not paginated). The two filters cannot be sent together.

bearer read-account

Query params — QueryParamsDto

Param	Type	Default	Notes
page	number	1	Page number (list mode)
limit	number	10	Records per page
order	'asc' | 'desc'	desc	Order by created_at
user_id	UUID	optional	Filter to a specific user’s accounts (detail mode)
account_number	string	optional	Filter to a specific account number (detail mode)

Response — 200 OK (list mode)

{
  "status": "success",
  "statusCode": 200,
  "message": "User Accounts retrrieved successfully",
  "data": {
    "limit": 10,
    "count": 4,
    "currentPage": 1,
    "totalPages": 1,
    "accounts": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440222",
        "account_number": "1234567890",
        "name": "Savings Pocket",
        "slug_name": "savings_pocket",
        "balance": "150000.0000",
        "currency": "IDR",
        "owner_type": "individual",
        "account_type": "pocket",
        "scope": "internal",
        "status": "active",
        "baas_provider": "cimb",
        "owner_id": "660e8400-e29b-41d4-a716-446655440111",
        "opened_at": "2026-05-20T08:30:00.000Z",
        "closed_at": null,
        "created_at": "2026-05-20T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Detail mode (user_id / account_number filter): data contains { account: AccountDto }.

Errors

Status	When it occurs
400 Bad Request	Filters user_id + account_number sent together
401 Unauthorized	Attempted to read an account that is not theirs
403 Forbidden	Missing read-account permission
404 Not Found	Account not found

---

POST /v1/accounts/transfer bearer

Transfer funds between two internal accounts using account_number. The source account must belong to the caller (or their organization). Self-transfers (source = destination) are rejected.

bearer top-up-account

Request body — AccountTransferDto

Field	Type	Required	Notes
source_account_number	string	yes	Source account number (must belong to the caller)
destination_account_number	string	yes	Destination account number (can be another account)
amount	string	yes	Transfer amount (decimal string, e.g. "50000.0000")

Example request

{
  "source_account_number": "123456789012",
  "destination_account_number": "210987654321",
  "amount": "50000.0000"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Transfer completed successfully",
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "source_account_id": "550e8400-e29b-41d4-a716-446655440001",
    "destination_account_id": "550e8400-e29b-41d4-a716-446655440002",
    "amount": "50000.0000"
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid amount, inactive account, or self-transfer
401 Unauthorized	Invalid Bearer/cookie
403 Forbidden	Source account does not belong to the caller
404 Not Found	One of the accounts not found

Side effects

• Creates a ledger transaction (transactions module).
• Updates both account balances atomically.

---

GET /v1/accounts/:id bearer

Detail of a single account by UUID. The server validates that the account belongs to the user or their organization.

bearer read-account

Path params

Param	Type	Notes
id	UUID	Account ID (validated by ParseUUIDPipe)

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Account retrieved successfully",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440222",
    "account_number": "1234567890",
    "name": "Savings Pocket",
    "balance": "150000.0000",
    "currency": "IDR",
    "owner_type": "individual",
    "account_type": "pocket",
    "scope": "internal",
    "status": "active",
    "baas_provider": "cimb",
    "owner_id": "660e8400-e29b-41d4-a716-446655440111",
    "opened_at": "2026-05-20T08:30:00.000Z",
    "closed_at": null
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Account does not belong to the caller
403 Forbidden	Missing read-account permission
404 Not Found	Account not found

---

PATCH /v1/accounts/:id bearer

Update account fields (e.g. name / label, currency, account_type). The DTO extends CreateAccountDto via PartialType — all fields are optional.

bearer update-account ACCOUNT_UPDATED

Path params

Param	Type	Notes
id	UUID	Account ID

Request body — UpdateAccountDto (all fields optional)

Field	Type	Notes
account_type	enum AccountType	pocket, saving_goal, saving_circle, commodity_financing, charitable_cause, investment, takaful
name	string	Account label
currency	string	ISO currency (e.g. IDR)

Example request

{
  "name": "Tabungan Pernikahan"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Account updated successfully",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440222",
    "name": "Tabungan Pernikahan",
    "currency": "IDR",
    "account_type": "pocket",
    "updated_at": "2026-05-20T10:00:00.000Z"
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (invalid enum)
401 Unauthorized	Account does not belong to the caller
403 Forbidden	Missing update-account permission
404 Not Found	Account not found

---

DELETE /v1/accounts/:id bearer

Soft delete an account. The record is preserved in the DB (deleted_at + deleted_by columns are populated) but the account no longer appears in list/detail endpoints.

bearer delete-account RESOURCE_DELETED

Path params

Param	Type	Notes
id	UUID	ID of the account to delete

Response — 200 OK

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

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Account does not belong to the caller
403 Forbidden	Missing delete-account permission
404 Not Found	Account not found

Side effects

• Soft-delete: deleted_at set to the current timestamp, deleted_by to the caller’s user ID.
• Emit BusinessEvent RESOURCE_DELETED (impact HIGH).

---

Reference

Enum: AccountType

• pocket — general pocket
• saving_goal
• saving_circle
• commodity_financing
• charitable_cause
• investment
• takaful

Enum: AccountScope

• internal — Moria ledger
• external — linked to an external bank account

Enum: AccountStatus

• active, suspended, closed, inactive

Enum: OwnerType

• individual, organization, moria

Enum: BaasProvider

• cimb, berrypay, amarbank

Standard error envelope

{
  "message": "you can't filter by user_id and account_id at the same time",
  "statusCode": 400,
  "error": "Bad Request"
}

message can be a string or an array of strings.

Common HTTP codes

• 400 body/query/param validation or illegal filter combination
• 401 account does not belong to the caller
• 403 permission mismatch
• 404 account not found
• 500 internal — show a generic toast

Balance field

All monetary values are sent as strings with 4 decimals (e.g. "50000.0000") to preserve precision — FE must parse via BigDecimal / a high-precision library.