Use Cases

Real-world examples showing how to use the Kasi Collections API in different scenarios.

Use Case 1: New Product Onboarding

Scenario: Onboard 1,000 policies for a new funeral plan product

Step 1: Prepare CSV File

Create a CSV file with all policy data:

customer_id,external_customer_ref,policy_number,product_code,collection_amount
CUST001,EXT001,POL001,FUNERAL_01,150.00
CUST002,EXT002,POL002,FUNERAL_01,150.00
...1000 rows...

Step 2: Bulk Import

curl -X POST https://api.kasipayments.co.za/v1/policies/import \
  -H "X-API-Key: your-key" \
  -F "file=@policies.csv"

Response:

{
  "imported": 1000,
  "failed": 0,
  "errors": []
}

Step 3: Execute Collections

curl -X POST https://api.kasipayments.co.za/v1/collections/execute \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"period_month": "2025-11"}'

Result: All 1,000 policies are queued for collection by the Smart Collections Engine.

Use Case 2: Failed Collection → Auto Retry → Success

Scenario: Customer's first collection attempt fails due to insufficient funds, but Smart Engine automatically retries after salary deposit.

Timeline

Day 5:  First attempt R150 → FAILED (insufficient funds)
Day 26: Auto-retry after salary deposit → SUCCESS ✅

Result

{
  "id": "coll_123",
  "collection_status": "PAID_FULL",
  "number_of_attempts": 2,
  "collection_amount_collected": 150.00,
  "first_attempt_date": "2025-11-05",
  "last_attempt_date": "2025-11-26",
  "last_failure_reason": null
}

Key Point: No manual intervention required - the Smart Engine handles it automatically.

Use Case 3: Partial Collections (Gig Worker)

Scenario: Customer with irregular income, R300/month premium

Collection Strategy

The Smart Collections Engine detects irregular income and splits collections:

Day 5:  Income R80 detected  → Collect R80
Day 12: Income R70 detected  → Collect R70
Day 18: Income R90 detected  → Collect R90
Day 25: Income R60 detected  → Collect R60

Result

{
  "collection_amount_due": 300.00,
  "collection_amount_collected": 300.00,
  "shortfall": 0.00,
  "collection_status": "PAID_FULL",
  "number_of_attempts": 4
}

Total collected: R300 ✅
Strategy: 4 partial debits
Status: PAID_FULL

Use Case 4: Month-End Settlement

Scenario: Complete month-end workflow for November 2025 collections

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

What you get: CSV file with all collection results for reconciliation.

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

Response:

{
  "settlement_number": "SETTLE-2025-11-001",
  "period_month": "2025-11",
  "total_collections": 42500.00,
  "net_amount": 28570.62,
  "payment_date": "2025-12-03",
  "status": "pending"
}

December 2: Get Settlement ID

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: Receive EFT Payment

EFT payment of R 28,570.62 is processed to your account with payment reference EFT-20251203-001.

Use Case 5: Policy Update (Premium Increase)

Scenario: Customer upgrades policy, increasing premium from R150 to R200

Update Policy

curl -X PATCH https://api.kasipayments.co.za/v1/policies/{policyId} \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_amount": 200.00
  }'

Response:

{
  "id": "uuid-here",
  "policy_number": "POL001",
  "collection_amount": 200.00,
  "status": "active",
  "updated_at": "2025-11-26T10:30:00Z"
}

Result: Next month's collections will use the new amount (R200).

Use Case 6: Policy Cancellation

Scenario: Customer cancels their policy mid-month

Cancel Policy

curl -X PATCH https://api.kasipayments.co.za/v1/policies/{policyId} \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled"
  }'

Result:

Policy marked as cancelled
No further collections attempted
Collection status shows CANCELLED in reports

Policies Resource - Endpoint details
Monthly Workflows - Typical monthly cycle
Quick Start Guide - Get started quickly
Full API Reference - Interactive API documentation

Use Cases

On this page