Settlements Resource

Generate settlement statements, retrieve details, and export settlement data. Settlements include fee calculations and payment information.

Endpoints

POST /settlements - Generate settlement
GET /settlements/{id} - Get settlement details
GET /settlements/{id}/export - Download settlement CSV

Generate Settlement

Create a settlement statement for a specific period.

Endpoint: POST /settlements

Request:

POST /settlements
Content-Type: application/json

{
  "period_month": "2025-11"
}

Response:

{
  "settlement_number": "SETTLE-2025-11-001",
  "period_month": "2025-11",
  "total_collections": 42500.00,
  "distribution_fee": 10625.00,
  "collections_fee": 1487.50,
  "total_fees": 12112.50,
  "vat": 1816.88,
  "net_amount": 28570.62,
  "payment_date": "2025-12-03",
  "status": "pending"
}

Use Case: Generate monthly settlement statement
Agreement Reference: Section 6.4a

Fee Breakdown

Distribution Fee: 25% of total collections
Collections Fee: 3.5% of total collections
VAT: 15% of total fees
Net Amount: Total collections - fees - VAT (amount due to you)

Formula:

distribution_fee = total_collections × 0.25
collections_fee = total_collections × 0.035
total_fees = distribution_fee + collections_fee
vat = total_fees × 0.15
net_amount = total_collections - total_fees - vat

Get Settlement Details

Retrieve detailed information about a specific settlement.

Endpoint: GET /settlements/{settlementId}

Response:

{
  "id": "uuid-here",
  "settlement_number": "SETTLE-2025-11-001",
  "period_month": "2025-11",
  "total_collections": 42500.00,
  "distribution_fee": 10625.00,
  "collections_fee": 1487.50,
  "total_fees": 12112.50,
  "vat": 1816.88,
  "net_amount": 28570.62,
  "status": "paid",
  "payment_date": "2025-12-03",
  "payment_reference": "EFT-20251203-001",
  "created_at": "2025-12-01T10:00:00Z"
}

Settlement Status Values:

pending - Settlement generated, awaiting payment
paid - Payment processed
disputed - Under dispute

Use Case: Retrieve settlement details for reconciliation
Agreement Reference: Section 6.4

Download Settlement CSV

Export settlement data as CSV for accounting systems.

Endpoint: GET /settlements/{settlementId}/export

CSV Response:

settlement_number,period_month,total_collections,distribution_fee,collections_fee,total_fees,vat,net_amount,payment_date,payment_reference
SETTLE-2025-11-001,2025-11,42500.00,10625.00,1487.50,12112.50,1816.88,28570.62,2025-12-03,EFT-20251203-001

Use Case: Download settlement for accounting systems
Agreement Reference: Section 6.4c

Example: Month-End Settlement Workflow

# December 1: Export collections results
curl "https://api.kasipayments.co.za/v1/reports/collections?period_month=2025-11" \
  -H "X-API-Key: your-key" \
  -o november-collections.csv

# December 2: Generate settlement
curl -X POST https://api.kasipayments.co.za/v1/settlements \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"period_month": "2025-11"}' \
  > settlement.json

# December 2: Get settlement ID from response
SETTLEMENT_ID=$(cat settlement.json | jq -r '.id')

# December 3: Download settlement CSV
curl "https://api.kasipayments.co.za/v1/settlements/$SETTLEMENT_ID/export" \
  -H "X-API-Key: your-key" \
  -o settlement-november.csv

# December 3: EFT payment received to your account

Payment Timeline

Settlements and EFT payments are processed by the 3rd calendar day of the following month.

Fee Structure - Detailed fee calculations
Reports Resource - Export collection results
Monthly Workflows - Typical monthly cycle
Full API Reference - Interactive API documentation

Settlements

On this page