Transactions

The transactions module is a read-only ledger for every money movement in Moria. Each transaction row has a polymorphic reference_type + reference_id that links to the originating product (saving goal, donation, investment, etc.). FE can only list and get-by-id — create/update/delete are intentionally not exposed (transactions are only created by the service-layer from payment handlers).

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
Related modules	payments, payment-gateway, accounts, saving-goals, saving-circles, charitable-cause, commodity-financing
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Users can only access their own transactions — the service-layer enforces a filter by user_id from the Bearer token. Query param filters refine the list (e.g. show only transactions for a specific saving goal).

Method	Path	Auth	Summary
GET	/v1/transactions	bearer	List transactions with filter + pagination
GET	/v1/transactions/:id	bearer	Detail of a single transaction

Notes

• The ReferenceType enum here comes from src/common/enums/common.enum.ts — a different value set from the ReferenceType enum in the payment-gateway module. For transaction filtering, use: donation, saving_goal, saving_circle, investment, commodity_financing, account_top_up.
• The amount field is a decimal string (e.g. "50000.0000") — use a decimal library for arithmetic in FE.
• The batch_id field groups related transactions (e.g. fee + price + tax for one payment).

---

GET /v1/transactions bearer

List transactions with optional filters. Only the logged-in user’s transactions are returned. Standard pagination is supported.

bearer read-transaction event · RESOURCE_FETCHED

Query params — FilterTransactionDto

Param	Type	Default	Notes
page	number (string)	1	Page number. Validators IsNumberString + IsNotZero.
limit	number (string)	10	Records per page.
product_id	string	optional	Filter by product ID (saving goal id, circle id, etc.).
reference_type	enum ReferenceType (common)	optional	donation, saving_goal, saving_circle, investment, commodity_financing, account_top_up
type	enum TransactionType	optional	price, fee, tax
user_id	string	optional	Filter by user. Overridden server-side for non-admins.

Example request

GET /v1/transactions?page=1&limit=10&reference_type=saving_goal&product_id=550e8400-e29b-41d4-a716-446655440000

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Transactions retrieved successfully",
  "data": {
    "limit": 10,
    "count": 24,
    "currentPage": 1,
    "totalPages": 3,
    "transactions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "amount": "50000.0000",
        "status": "successful",
        "date": "2026-05-20T08:30:00.000Z",
        "source_account_id": "9e8a1d2c-4b5f-4c6d-8e7a-1b2c3d4e5f60",
        "destination_account_id": null,
        "type": "price",
        "reference_type": "saving_goal",
        "reference_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "batch_id": "550e8400-e29b-41d4-a716-446655440001",
        "purpose": "topup_product",
        "payment_order_id": "fcd8dc3b-9f1b-46e8-91ca-402147556022",
        "created_by": "550e8400-e29b-41d4-a716-446655440000",
        "updated_by": "550e8400-e29b-41d4-a716-446655440000",
        "deleted_by": null,
        "created_at": "2026-05-20T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When
400 Bad Request	Invalid filter (unknown enum, page/limit non-numeric or zero)
401 Unauthorized	Bearer/cookie invalid
403 Forbidden	Missing read-transaction

---

GET /v1/transactions/:id bearer

Detail of a single transaction. Users can only fetch their own transactions (enforced at the service-layer).

bearer read-transaction

Path params

Param	Type	Notes
id	UUID	Transaction ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Transaction retrieved successfully",
  "data": {
    "transaction": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "50000.0000",
      "status": "successful",
      "date": "2026-05-20T08:30:00.000Z",
      "source_account_id": "9e8a1d2c-4b5f-4c6d-8e7a-1b2c3d4e5f60",
      "destination_account_id": null,
      "type": "price",
      "reference_type": "saving_goal",
      "reference_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "batch_id": "550e8400-e29b-41d4-a716-446655440001",
      "purpose": "topup_product",
      "payment_order_id": "fcd8dc3b-9f1b-46e8-91ca-402147556022",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "updated_by": "550e8400-e29b-41d4-a716-446655440000",
      "deleted_by": null,
      "created_at": "2026-05-20T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
403 Forbidden	User attempting to access another’s transaction
404 Not Found	Transaction not found

---

Reference

Enum: TransactionType

• price — main transaction amount
• fee — cost / admin fee
• tax — tax

Enum: TransactionStatus

• pending
• successful
• failed
• reversed

Enum: TransactionPurpose

• topup_pocket
• topup_product
• external_withdrawal
• internal_withdrawal
• product_transfer
• pocket_transfer

Enum: ReferenceType (common)

• donation
• saving_goal
• saving_circle
• investment
• commodity_financing
• account_top_up

Standard error envelope

{
  "message": "Transaction not found",
  "statusCode": 404,
  "error": "Not Found"
}

Common HTTP codes

• 400 invalid filter
• 401 Bearer invalid
• 403 accessing another user’s transaction
• 404 transaction not found
• 500 internal — generic toast

Integration notes

• No POST / PATCH / DELETE endpoints — transactions are only created from payment handlers (the payments module) or the Amdigipay callback.
• For gateway top-up transactions, payment_order_id is set after the completed callback arrives.
• The destination_account_id field is only set for inter-account transfers.