Monthly Workflows

Understanding the typical monthly workflow helps you plan and automate your collections process.

Typical 5-Step Monthly Cycle

Day 1       POST /policies/import
            └─ Upload active policies for the month

Day 1-30    POST /collections/execute
            └─ Smart Engine collects throughout month
               (automatic retries, optimal timing)

Dec 1       GET /reports/collections?period_month=2025-11
            └─ Export results CSV for reconciliation

Dec 2       POST /settlements
            └─ Generate settlement statement

Dec 3       GET /settlements/{id}/export
            └─ Download settlement CSV
            └─ Receive EFT payment to your account

Payment Timeline

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

Step-by-Step Breakdown

Day 1: Import Policies

At the start of each month, upload your active policies:

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

What happens:

• Policies are validated and imported
• System prepares for collections
• Policies are queued for the Smart Collections Engine

Days 1-30: Collections Execution

Trigger collections at the start of the month:

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"}'

What happens:

• Smart Collections Engine analyzes customer income patterns
• Collections are scheduled optimally (1-2 days after income deposits)
• Automatic retries occur throughout the month
• Partial collections handled for irregular income customers
• Full collection targeted by month end

Day 1 of Next Month: Export Results

Export collection results for reconciliation:

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

What you get:

• CSV file with all collection results
• 13 required fields per collection
• Status, attempts, and failure reasons

Day 2 of Next Month: Generate Settlement

Create the settlement statement:

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"}'

What you get:

• Settlement number
• Total collections
• Fee breakdown (distribution, collections, VAT)
• Net amount due to you
• Payment date

Day 3 of Next Month: Download & Receive Payment

Download settlement CSV and receive EFT payment:

# Get settlement ID from previous response
SETTLEMENT_ID="settlement-id-here"

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

What happens:

• Settlement CSV downloaded for accounting
• EFT payment processed to your account
• Payment reference provided for reconciliation

Automation Tips

1. Schedule policy imports - Automate CSV uploads on the 1st of each month
2. Monitor collections - Set up alerts for failed collections
3. Automate exports - Schedule collection result exports
4. Track settlements - Automate settlement generation and downloads

Related Documentation

• Policies Resource - Endpoint details
• Use Cases - Real-world examples
• Fee Structure - Understanding fees
• Full API Reference - Interactive API documentation