Developer Documentation

Settlements

Settlements

Settlements prepare merchant payouts, provider settlements, commission settlements, and operational adjustments.

Lifecycle

• pending: generated but not submitted or paid.
• processing: payout is being prepared or sent to a provider.
• paid: settlement has been paid and audited.
• failed: settlement failed.
• cancelled: settlement was cancelled before payment.

Failed or reversed transactions must not be settled. Existing settled records must not be duplicated.

Admin Endpoints

• GET /v1/admin/settlements
• GET /v1/admin/settlements/{id}
• POST /v1/admin/settlements/generate
• POST /v1/admin/settlements/{id}/mark-paid
• POST /v1/admin/settlements/{id}/cancel

Merchant Endpoints

• GET /v1/merchants/me/settlements
• GET /v1/merchants/me/settlements/{id}

Commission Settlement

Commission records are stored separately in commission_records so earned, settled, and reversed commission can be reported without mutating the immutable ledger.

Admin endpoints:

• GET /v1/admin/commissions
• POST /v1/admin/commissions/{id}/reverse