Last updated July 2026

Grupy REST API Reference

The Grupy REST API allows developers and platform partners to programmatically manage group expense splits, automated savings goals, real-time contribution tracking, and instant payment settlements via PayShap and Chat2Pay.

API Scope & Features

Core Capabilities

Expense Splitting: Create equal or custom percentage bill splits, generate payment links, and track member settlements.
Group Savings & Stokvels: Set target savings milestones, schedule recurring contributions, and hold funds in regulated escrow.
Contribution Tracking: Fetch real-time ledgers, pending payments, and payment proof verifications.
Instant Payment Settlement: Process payouts and payments via PayShap RTC and WhatsApp Chat2Pay triggers.

Authentication

All API requests must be authenticated over HTTPS using Bearer tokens passed in the Authorization header:

Authorization: Bearer grupy_live_sec_89f1a23e4b56c7890d

Response Codes & Errors

The Grupy API returns standard HTTP status codes along with JSON error objects:

200 OK — Request processed successfully.
201 Created — Split or savings goal created.
400 Bad Request — Missing required parameters or invalid member allocation.
401 Unauthorized — Missing or invalid API key.
422 Unprocessable Entity — Insufficient group balance or settlement dispute.

Expense Splitting API

Create new group expense splits and calculate individual member shares:

POST /v1/splits

Create Expense Split

Request body example:

{
  "group_id": "grp_98231",
  "title": "Weekend Dinner at Cape Town Beach",
  "total_amount": 1250.00,
  "currency": "ZAR",
  "paid_by": "usr_401",
  "split_type": "EQUAL",
  "members": ["usr_401", "usr_402", "usr_403", "usr_404"]
}

POST /v1/splits/calculate

Calculate Member Shares

Computes precise breakdown per member including optional tip, tax, and weighted item adjustments.

POST /v1/splits/{id}/settle

Settle Payment

Executes an instant PayShap settlement to credit the payer once group members complete their contributions.

Group Savings & Contribution Tracking

Manage shared savings pools, vacation funds, and stokvel contributions:

GET /v1/savings/{id}/contributions

Track Contributions

Returns current savings progress, escrow balance, individual member contribution history, and pending dues.

{
  "savings_id": "svg_7721",
  "target_amount": 10000.00,
  "current_balance": 6500.00,
  "currency": "ZAR",
  "status": "IN_PROGRESS",
  "contributions": [
    { "user_id": "usr_401", "amount": 2500.00, "paid_at": "2026-07-28T14:20:00Z" },
    { "user_id": "usr_402", "amount": 2000.00, "paid_at": "2026-07-29T09:15:00Z" },
    { "user_id": "usr_403", "amount": 2000.00, "paid_at": "2026-07-30T11:45:00Z" }
  ]
}

POST /v1/savings/{id}/schedule

Auto-Debit Schedules

Configure recurring weekly or monthly contribution schedules with automated PayShap request-to-pay triggers.

Group Management

GET /v1/groups/{id}/summary

Group Balance Summary

Fetches consolidated balances across all active splits, savings pools, and member net positions within a WhatsApp group.

Payment Rails & Webhooks

Grupy integrates directly with South African payment rails (PayShap RTC & Chat2Pay) for immediate confirmation:

POST /v1/webhooks

Webhook Event Notifications

Subscribe to real-time events:

contribution.received — Fired when a member pays their share.
split.settled — Fired when a bill split is fully paid off.
savings.milestone_reached — Fired when a group reaches its target savings goal.
refund.processed — Fired when an unpaid contribution auto-refunds.