PENDING status and is executed only after all active admins have approved it. When a payout executes, the group balance is debited, the configured retention percentage is kept in the group fund, and the member receives a push notification.
Get the payout queue
Return a list of members who are currently eligible to receive a payout. This endpoint is restricted to admins.GET /api/payouts/queue
A member appears in this list when all three conditions are true:
roleismemberhas_received_payoutisfalseis_activeistrue
contribution_paid descending — members who have contributed the most appear first.
Response
Returns an array ofMemberEntity objects.
Example
Get cycle payout queue
Retrieve the ordered payout queue for a specific cycle. Members are ranked by their credit score at the time the queue was generated.GET /api/cycles/{cycle_id}/queue
Path parameters
Response
Returns an array ofPayoutQueueResponse objects ordered by position.
Example
Initiate a payout
Create a payout for a member. Admin only. The payout is saved inPENDING status and requires unanimous admin approval before funds are moved. A retention amount is automatically withheld based on the retention_percentage in the system configuration.
POST /api/payouts
If the group balance is insufficient to cover the requested amount, the API returns a
400 error that includes the exact shortfall: "Insufficient group balance. Need {shortfall} more". Resolve the shortfall by collecting additional contributions before retrying.Request body
Member’s phone number in Uganda format (
+256XXXXXXXXX or 256XXXXXXXXX). Used to look up the recipient.Gross payout amount. Must be greater than
0 and must not exceed the payout_amount value in the system configuration. The net amount disbursed to the member will be lower after the retention percentage is applied.When
true, any amount that cannot be paid immediately is deferred rather than cancelled.A unique string (max 100 characters) you generate per request. If a payout with this key already exists, the server returns
{"success": true, "message": "Payout initiated. Awaiting approval."} without creating a duplicate.Response
Example
Approve a payout
Submit an admin’s approval for a pending payout. Admin only. The system requires unanimous approval — the payout executes only once every active admin has approved it.POST /api/payouts/{id}/approve
When unanimous approval is reached:
- The group balance is debited by the gross payout amount.
- The configured
retention_percentageis kept in the group fund (retention_amountis stored on the payout record). - The member’s
has_received_payoutflag is set totrue. - A push notification is sent to the member.
"Approval recorded. {count}/{total} admins have approved."
Path parameters
Request body
Response
"Payout approved unanimously by all {n} admins and has been executed." when unanimous, or "Approval recorded. {count}/{total} admins have approved." when more approvals are still needed.
