Settlements

Settlements are periodic payouts from the platform to your bank account. For WALLET merchants, funds accumulate in your wallet and are disbursed on demand. For MANUAL merchants, the platform creates settlements on a scheduled basis.

Settlement Object

{
  "id": "uuid",
  "ref_code": "STL-260601-00023",
  "settlement_date": "2026-06-01",
  "period_start": "2026-05-25T00:00:00Z",
  "period_end": "2026-05-31T23:59:59Z",
  "gross_amount_minor": 50000000,
  "mdr_total_minor": 350000,
  "platform_fee_minor": 100000,
  "aggregator_fee_minor": 150000,
  "refund_total_minor": 0,
  "disbursement_fee_minor": 25000,
  "net_payout_minor": 49625000,
  "order_count": 12,
  "bank_id": "uuid",
  "account_number": "1234567890",
  "account_name": "PT Example Merchant",
  "status": "PAID",
  "created_at": "2026-06-01T08:00:00Z",
  "updated_at": "2026-06-01T09:15:00Z"
}

Key Fields

Field	Description
gross_amount_minor	Total order amounts in the settlement period
mdr_total_minor	Total MDR charged to you (deducted from gross)
refund_total_minor	Total refunds processed (deducted from gross)
disbursement_fee_minor	Bank transfer fee for the settlement payout
net_payout_minor	What actually lands in your bank account

Formula: net_payout = gross_amount - mdr_total - refund_total - disbursement_fee

Settlement Status

Status	Description
PENDING	Scheduled, awaiting processing
PROCESSING	Being transferred
PAID	Successfully transferred to your bank
FAILED	Transfer failed — contact support
CANCELLED	Cancelled by platform

List Settlements

GET /v1/settlements

Query Parameters: page, limit (see Pagination)

Response:

{
  "success": true,
  "data": [ ... ],
  "meta": { "page": 1, "limit": 10, "total": 3, "total_pages": 1 }
}

Get Settlement

GET /v1/settlements/:id

Returns a single settlement. :id must be the settlement UUID.

Error: INVALID_ID (400) if not a valid UUID; NOT_FOUND (404) if not found or belongs to another merchant.