Transactions API

Base route: /api/transactions
Auth required: ✅ JWT Bearer

A Transaction is an individual payment recorded against an invoice.
Multiple transactions can be recorded against a single invoice (partial payments).

---

GET /api/transactions

Returns a paginated, sortable list of payment transactions.

Permission: Transaction:Read

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number (1-based)
pageSize	int	15	Items per page (max 100)
sortBy	string	transactionDate	Sort field: transactionDate | amount | transactionType | createdAt
sortDir	string	desc	asc | desc
invoiceId	int	—	Return transactions for this invoice only
fromDate	datetime	—	Inclusive lower bound on transactionDate
toDate	datetime	—	Inclusive upper bound on transactionDate
transactionType	string	—	Filter by payment method: Cash | UPI | NetBanking
isActive	bool	true	true = active, false = soft-deleted

Response — List 200 OK

{
  "items": [
    {
      "id": 201,
      "invoiceId": 101,
      "amount": 20000.00,
      "transactionDate": "2026-02-01T00:00:00Z",
      "transactionType": "UPI",
      "description": "February partial payment",
      "isActive": true,
      "createdAt": "2026-02-01T09:15:00Z",
      "invoice": {
        "id": 101,
        "invoiceNumber": "INV-2026-001",
        "vendorName": "ABC Pharmaceuticals",
        "amount": 50000.00,
        "pendingAmount": 30000.00
      }
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 15
}

---

GET /api/transactions/:id

Returns a single transaction with nested invoice details.

Permission: Transaction:Read

Response — Single 200 OK — TransactionDto (with nested invoice object)

Response — Not Found 404

---

POST /api/transactions

Records a new payment against an invoice.

Permission: Transaction:Create

Request Body

{
  "invoiceId": 101,
  "amount": 15000.00,
  "transactionDate": "2026-03-17T00:00:00Z",
  "transactionType": "Cash",
  "description": "March cash payment"
}

Field	Required	Description
invoiceId	✅	Must reference an existing active invoice
amount	✅	Payment amount (positive decimal)
transactionDate	✅	Date the payment was made
transactionType	✅	Cash | UPI | NetBanking
description	—	Optional payment note

TIP

After recording a transaction, the invoice's paidAmount and pendingAmount are recalculated automatically on the next fetch. The invoice status may change to FullyPaid if pendingAmount reaches 0.

Response — Created 201 — TransactionDto

Response — Invalid 400

---

PUT /api/transactions/:id

Updates an existing transaction.

Permission: Transaction:Update

Response — Updated 200 OK — Updated TransactionDto

Response — Not Found 404

---

DELETE /api/transactions/:id

Soft-deletes a transaction.

Permission: Transaction:Delete

Request Body (optional)

{ "reason": "Recorded against wrong invoice" }

Response — Deleted 204 No Content

Response — Not Found 404

---

Transaction Types

Value	Description
Cash	Physical cash payment
UPI	UPI / mobile payment
NetBanking	Bank transfer / NEFT / RTGS