Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.digiflecttech.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Transactions API lets you record and manage all financial activity in a group — contributions, payouts, loan repayments, and penalties. Every transaction is created with a PENDING status and only takes effect on the group balance after all active admins have approved it. Members can view their own transaction history; admins can filter across the entire group.

​
List transactions

Retrieve a paginated list of transactions. Members always see only their own records. Admins can optionally filter by any member and by date range. GET /api/transactions

​
Query parameters

​
memberId
string
Filter by member ID. Admins only — members always see their own transactions regardless of this parameter.
​
startDate
integer
Start of the date range as a Unix timestamp in milliseconds (e.g., 1700000000000).
​
endDate
integer
End of the date range as a Unix timestamp in milliseconds.
​
limit
integer
default:"20"
Maximum number of records to return. Minimum 1, maximum 100.
​
offset
integer
default:"0"
Number of records to skip for pagination. Minimum 0.

​
Response

Returns a PaginatedResponse wrapping a list of TransactionEntity objects.
​
data
TransactionEntity[]
List of transactions for the current page.
​
total
integer
required
Total number of transactions matching the applied filters.
​
limit
integer
required
The limit value used in this response.
​
offset
integer
required
The offset value used in this response.

​
Example

curl --request GET \
  --url "https://api.saveapp.example/api/transactions?limit=20&offset=0" \
  --header "Authorization: Bearer <token>"

​
Create a transaction

Record a new financial transaction for a group member. The transaction is immediately saved with a PENDING status — it does not affect the group balance until it is approved. POST /api/transactions
This endpoint is rate-limited to 10 requests per minute. Implement exponential back-off on your client when retrying after a 429 Too Many Requests response.
Supply an idempotency_key on every request that may be retried (e.g., after a network timeout). If the server has already processed a request with the same key, it returns the original transaction instead of creating a duplicate.

​
Request body

​
memberName
string
required
Full name of the member as stored in the system. The API looks up the member record by this name.
​
type
string
required
Type of transaction. Must be one of: CONTRIBUTION, PAYOUT, LOAN_REPAYMENT, PENALTY, SHORTFALL_RESOLUTION.
​
amount
number
required
Amount in the group’s currency. Must be greater than 0 and must not exceed the system-configured MAX_TRANSACTION_AMOUNT.
​
description
string
Optional note describing the transaction (2–200 characters).
​
paymentMethod
string
required
Payment channel, e.g. mobile_money or cash.
​
idempotency_key
string
A unique string (max 100 characters) you generate per request. Enables safe retries without creating duplicate transactions.

​
Response

Returns the created TransactionEntity with status: "PENDING".
​
id
string
required
Unique identifier for the newly created transaction.
​
member_id
string
required
ID of the member this transaction was created for.
​
type
string
required
The transaction type as submitted.
​
amount
number
required
The transaction amount as submitted.
​
description
string
The description as submitted, if provided.
​
payment_method
string
The payment method as submitted.
​
status
string
required
Always PENDING on creation.
​
date
string
required
ISO 8601 datetime when the transaction was created.

​
Example

curl --request POST \
  --url "https://api.saveapp.example/api/transactions" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "memberName": "Jane Nakato",
    "type": "CONTRIBUTION",
    "amount": 50000,
    "description": "October contribution",
    "paymentMethod": "mobile_money",
    "idempotency_key": "contrib-jane-oct-2024"
  }'

​
Approve a transaction

Approve a pending transaction. This endpoint requires admin privileges. The system uses unanimous approval — a transaction is only executed once every active admin has called this endpoint for it. POST /api/transactions/{id}/approve When unanimous approval is reached, the following side effects occur automatically:
  • CONTRIBUTION — the group balance is credited and the member’s contribution_paid total is increased. The member’s credit score is then updated: an on-time payment (before the active cycle’s contribution_due_date) awards positive points; a late payment deducts points.
  • PAYOUT — the group balance is debited.
  • LOAN_REPAYMENT — the group balance is credited.
  • PENALTY — the group balance is credited and the member’s shortfall_amount is increased.
A push notification is sent to the member when their transaction is fully approved.

​
Path parameters

​
id
string
required
The UUID of the transaction to approve.

​
Request body

​
adminEmail
string
required
Email address of the admin submitting this approval (2–100 characters).
​
txId
string
Optional external transaction reference ID.

​
Response

​
success
boolean
required
true when the approval was recorded successfully.
​
message
string
required
Either "Transaction approved and executed successfully" (when unanimous approval is reached) or "Approval recorded. Waiting for other admins to approve." (when more approvals are still needed).

​
Example

curl --request POST \
  --url "https://api.saveapp.example/api/transactions/txn_a1b2c3d4/approve" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "adminEmail": "admin@savegroup.ug"
  }'