Settlements | Lipafy

A settlement is a periodic payout from Lipafy to a capability provider. Every successful gateway call credits the provider’s wallet internally; settlement is the act of moving that balance out of Lipafy and into the provider’s M-Pesa account.

The lifecycle

[gateway call succeeds]
  -> caller debited
  -> provider's internal wallet credited, minus Lipafy's revenue share
  -> receipt written
  ->
[settlement period closes]
  -> successful capability requests are grouped into a settlement
  -> settlement status becomes pending
  ->
[payout processing]
  -> M-Pesa B2C payout to the provider's registered phone
  -> success: status becomes paid
  -> failure: status becomes failed

Settlement periods

Lipafy doesn’t enforce a fixed cadence in the protocol. Common choices:

Cadence	Use
Daily	High-volume providers who want fast cash flow
Weekly	Most providers; balances exposure
Monthly	Low-volume providers; minimizes M-Pesa transaction count

Each capability has a revenue_share_percent from 0 to 100. A value of 0 means the provider keeps everything; a value of 10 means Lipafy keeps 10% of every successful call’s price as lipafy_margin.

For a 500 KES capability with 10% share, a single successful call writes:

Wallet	Movement
Caller	`-500 KES` (`debit`)
Provider	`+450 KES` internal credit
Lipafy margin	`+50 KES` recorded on the settlement

The provider’s internal wallet balance accrues across calls and is moved out via settlement.

API

List your settlements

1 GET /v1/settlements
2 Authorization: Bearer <credential>

Returns settlements where the capability is owned by your account. Filter by status (pending, paid, failed), date range (from, to), and limit.

Get a single settlement

1 GET /v1/settlements/:id
2 Authorization: Bearer <credential>

Owners see their own settlement records.

Failure handling

status='pending' - settlement has been calculated and is awaiting payout.
status='paid' - payout succeeded.
status='failed' - payout failed at the payment rail. Keep your account phone number current so Lipafy can retry after the issue is fixed.

The other lane: Lipafy margin

The lipafy_margin accrued during settlement is not a separate provider settlement row. It is recorded on the same settlement record and is reconciled by Lipafy outside the provider payout flow.