How to Execute and Approve Member Payouts in Save App

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

Field	Required	Description
`memberPhone`	Yes	Phone number of the recipient in `+256XXXXXXXXX` format
`amount`	Yes	Gross payout amount (before retention is deducted)
`deferRemaining`	No	When `true`, marks remaining queue entries as deferred after this payout executes (default `false`)
`idempotency_key`	No	Unique 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.

Get Started

Core Concepts

Guides

How to Execute and Approve Member Payouts in Save App

View the payout queue

Execute a payout

Request fields

Payout rules

Approve a payout

​View the payout queue

​Execute a payout

​Request fields

​Payout rules

​Approve a payout

View the payout queue

Execute a payout

Request fields

Payout rules

Approve a payout