API Transactions

API – Transactions

Track payments made against bills. Creating a transaction can automatically update the associated bill's status.

Base path: /api/v1/transactions

---

Endpoints

Method	Endpoint	Description
GET	/transactions	List transactions
POST	/transactions	Record a new transaction
GET	/transactions/{transaction}	Get a single transaction
PUT	/transactions/{transaction}	Update a transaction
DELETE	/transactions/{transaction}	Delete a transaction
GET	/transactions/{transaction}/receipt	Get formatted receipt

---

GET /transactions

List all transactions for the active team with filtering and pagination.

Query Parameters:

Parameter	Type	Description
search	string	Search notes or payment method
bill_id	integer	Filter by bill
payment_method	string	Filter by payment method
date_from	date	Filter from date (YYYY-MM-DD)
date_to	date	Filter to date (YYYY-MM-DD)
min_amount	numeric	Minimum amount filter
max_amount	numeric	Maximum amount filter
sort_by	string	Column to sort by
sort_direction	string	asc or desc
per_page	integer	Results per page (max: 100)

Response 200:

{
  "data": [
    {
      "id": 1,
      "tnx_id": "TXN-001",
      "amount": 15.99,
      "payment_date": "2026-02-01T00:00:00.000Z",
      "payment_method": "credit_card",
      "payment_method_name": "Credit Card",
      "attachment_link": "https://...",
      "notes": "Paid via auto-billing",
      "bill": {
        "id": 1,
        "title": "Netflix Subscription"
      }
    }
  ],
  "links": { ... },
  "meta": { ... }
}

---

POST /transactions

Record a new payment transaction. Creating a transaction will automatically mark the linked bill as paid.

Request:

{
  "bill_id": 1,
  "amount": 15.99,
  "payment_date": "2026-02-01",
  "payment_method": "credit_card",
  "notes": "Paid via auto-billing",
  "attachment": "base64_encoded_file_content"
}

Field	Type	Required	Description
bill_id	integer	Yes	ID of the bill being paid
amount	numeric	Yes	Amount paid (≥ 0)
payment_date	date	Yes	Date of payment (YYYY-MM-DD)
payment_method	string	No	e.g. credit_card, bank_transfer, cash
notes	string	No	Optional payment notes
attachment	string	No	Base64-encoded receipt file

Response 201:

{
  "success": true,
  "message": "Transaction created successfully",
  "data": {
    "id": 1,
    "tnx_id": "TXN-001",
    "amount": 15.99,
    "payment_date": "2026-02-01T00:00:00.000Z",
    "bill_id": 1
  }
}

---

GET /transactions/{transaction}

Get a single transaction by ID with full details.

Response 200:

{
  "success": true,
  "data": {
    "id": 1,
    "tnx_id": "TXN-001",
    "amount": 15.99,
    "payment_date": "2026-02-01T00:00:00.000Z",
    "payment_method": "credit_card",
    "payment_method_name": "Credit Card",
    "attachment_link": "https://...",
    "notes": "Paid via auto-billing",
    "bill": {
      "id": 1,
      "title": "Netflix Subscription"
    }
  }
}

---

PUT /transactions/{transaction}

Update an existing transaction. All fields are optional.

Request:

{
  "amount": 19.99,
  "payment_date": "2026-02-05",
  "payment_method": "bank_transfer",
  "notes": "Updated payment notes"
}

Response 200:

{
  "success": true,
  "message": "Transaction updated successfully",
  "data": {
    "id": 1,
    "tnx_id": "TXN-001",
    "amount": 19.99
  }
}

---

DELETE /transactions/{transaction}

Delete a transaction. This may affect the associated bill's computed status.

Response 200:

{
  "success": true,
  "message": "Transaction deleted successfully"
}

---

GET /transactions/{transaction}/receipt

Get a formatted receipt view for a transaction — useful for display or printing.

Response 200:

{
  "success": true,
  "data": {
    "tnx_id": "TXN-001",
    "amount": 15.99,
    "payment_date": "2026-02-01T00:00:00.000Z",
    "bill_title": "Netflix Subscription",
    "category": "Entertainment",
    "payment_method_name": "Credit Card"
  }
}

---

cURL Examples

TOKEN="YOUR_TOKEN"
BASE="https://bills.msar.me/api/v1"

# List transactions for a specific bill
curl "$BASE/transactions?bill_id=1" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# Record a payment
curl -X POST "$BASE/transactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bill_id": 1,
    "amount": 15.99,
    "payment_date": "2026-04-01",
    "payment_method": "credit_card",
    "notes": "Monthly payment"
  }'

# Filter by date range
curl "$BASE/transactions?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# View receipt
curl "$BASE/transactions/1/receipt" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"