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.

A payout is the moment a member receives the group fund they have been building through regular contributions. Save App enforces a fair, ordered queue so that every eligible member gets their turn — and every disbursement is protected by the same unanimous admin approval that governs all financial actions. A configurable retention percentage is automatically held back in the group fund so the group always maintains a working balance.
Always check the group balance before initiating a payout. If the group fund does not have enough to cover the full payout amount, the API will return a 400 error with the exact shortfall so you can communicate it to the group.

​
View the payout queue

The payout queue lists all active members who have not yet received a payout in the current cycle, ordered from highest to lowest contribution_paid. This ordering ensures that the most consistent contributors are first in line. 
curl https://api.saveapp.co/api/payouts/queue \
  -H "Authorization: Bearer <admin_token>"
Response 
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Amara Nakato",
    "phone": "+256701234567",
    "role": "member",
    "group_name": "Kampala Savers",
    "contribution_paid": 200000.0,
    "shortfall_amount": 0.0,
    "has_received_payout": false,
    "is_active": true,
    "is_creator": false,
    "status": "active",
    "created_at": "2025-01-05T08:00:00Z",
    "reliability_label": "SAFE",
    "reliability_color": "#10B981",
    "is_eligible": true,
    "credit_score": 780
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "David Ochieng",
    "phone": "+256782345678",
    "role": "member",
    "group_name": "Kampala Savers",
    "contribution_paid": 150000.0,
    "shortfall_amount": 0.0,
    "has_received_payout": false,
    "is_active": true,
    "is_creator": false,
    "status": "active",
    "created_at": "2025-01-06T08:00:00Z",
    "reliability_label": "STABLE",
    "reliability_color": "#3B82F6",
    "is_eligible": true,
    "credit_score": 650
  }
]
When your group operates within a formal savings cycle, use GET /api/cycles/{cycle_id}/queue instead. The cycle-based queue is generated at cycle start using each member’s credit score at that point in time, giving a stable, pre-determined payout order that does not shift as contribution totals change throughout the cycle.

​
Execute a payout

Only admins can initiate payouts. The request creates a payout record in PENDING status; the funds are not actually disbursed until all admins approve. 
curl -X POST https://api.saveapp.co/api/payouts \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "memberPhone": "+256701234567",
    "amount": 200000,
    "deferRemaining": false,
    "idempotency_key": "payout-amara-20250110-001"
  }'
Response 
{
  "success": true,
  "message": "Payout initiated. Awaiting approval."
}

​
Request fields

FieldRequiredDescription
memberPhoneYesPhone number of the recipient in +256XXXXXXXXX format
amountYesGross payout amount (before retention is deducted)
deferRemainingNoWhen true, marks remaining queue entries as deferred after this payout executes (default false)
idempotency_keyNoUnique key to safely retry without creating duplicate payouts

​
Payout rules

The API enforces all of the following before creating the payout record:
  • The member must not have has_received_payout: true
  • amount must not exceed the group’s configured payout_amount limit
  • The group balance must be greater than or equal to amount
A retention amount is automatically deducted from every payout. The net amount the member actually receives is: 
net_amount = amount × (1 - retention_percentage / 100)
Both net_amount and retention_amount are stored on the payout record for full transparency. The retention stays in the group fund to keep a working balance.

​
Approve a payout

Like all financial actions in Save App, payouts require unanimous approval from every active admin. Each admin calls the approve endpoint independently. 
curl -X POST "https://api.saveapp.co/api/payouts/d5e6f7a8-b9c0-1234-def0-567890123456/approve" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adminEmail": "admin@kampalasampavers.co.ug"
  }'
While waiting for additional approvals: 
{
  "success": true,
  "message": "Approval recorded. 1/3 admins have approved."
}
Once all admins have approved: 
{
  "success": true,
  "message": "Payout approved unanimously by all 3 admins and has been executed."
}
When unanimous approval is reached, the group balance is debited, the member’s has_received_payout flag is set to true, and a push notification is sent to the member’s device.
A member whose has_received_payout is true will not appear in the /api/payouts/queue response and cannot receive another payout until the flag is reset at the start of a new cycle. Attempting to create a payout for such a member will return a 400 error.