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
string
Filter by member ID. Admins only — members always see their own transactions regardless of this parameter.
integer
Start of the date range as a Unix timestamp in milliseconds (e.g.,
1700000000000).integer
End of the date range as a Unix timestamp in milliseconds.
integer
default:"20"
Maximum number of records to return. Minimum
1, maximum 100.integer
default:"0"
Number of records to skip for pagination. Minimum
0.Response
Returns aPaginatedResponse wrapping a list of TransactionEntity objects.
TransactionEntity[]
List of transactions for the current page.
integer
required
Total number of transactions matching the applied filters.
integer
required
The
limit value used in this response.integer
required
The
offset value used in this response.Example
Create a transaction
Record a new financial transaction for a group member. The transaction is immediately saved with aPENDING status — it does not affect the group balance until it is approved.
POST /api/transactions
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
string
required
Full name of the member as stored in the system. The API looks up the member record by this name.
string
required
Type of transaction. Must be one of:
CONTRIBUTION, PAYOUT, LOAN_REPAYMENT, PENALTY, SHORTFALL_RESOLUTION.number
required
Amount in the group’s currency. Must be greater than
0 and must not exceed the system-configured MAX_TRANSACTION_AMOUNT.string
Optional note describing the transaction (2–200 characters).
string
required
Payment channel, e.g.
mobile_money or cash.string
A unique string (max 100 characters) you generate per request. Enables safe retries without creating duplicate transactions.
Response
Returns the createdTransactionEntity with status: "PENDING".
string
required
Unique identifier for the newly created transaction.
string
required
ID of the member this transaction was created for.
string
required
The transaction type as submitted.
number
required
The transaction amount as submitted.
string
The description as submitted, if provided.
string
The payment method as submitted.
string
required
Always
PENDING on creation.string
required
ISO 8601 datetime when the transaction was created.
Example
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’scontribution_paidtotal is increased. The member’s credit score is then updated: an on-time payment (before the active cycle’scontribution_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’sshortfall_amountis increased.
Path parameters
string
required
The UUID of the transaction to approve.
Request body
string
required
Email address of the admin submitting this approval (2–100 characters).
string
Optional external transaction reference ID.
Response
boolean
required
true when the approval was recorded successfully.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).