Technical Details

Technical information about security, error handling, data formats, and system architecture.

Architecture Overview

Product Provider (You)
    ↓ (CSV/API)
Kasi Collections API
    ↓
Smart Collections Engine
    ↓
Customer Bank Accounts
    ↓
Settlement Processor
    ↓
Product Provider (EFT Payment)

Security

HTTPS Only

All API traffic is encrypted using TLS 1.2+. HTTP requests are not supported.

API Key Authentication

Secure key-based access control:

• API keys are required for all requests
• Keys should be stored securely (environment variables)
• Never commit keys to version control
• Rotate keys regularly

Rate Limits

To ensure fair usage and system stability:

• Query endpoints: 100 requests/minute
• Update endpoints: 10 requests/minute

If you exceed these limits, you'll receive a 429 Too Many Requests response.

Data Encryption

• In Transit: All data encrypted via TLS
• At Rest: Data encrypted using industry-standard encryption
• Compliance: POPIA 2013 (South African data protection)

Error Handling

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid period_month format. Expected YYYY-MM",
    "details": {
      "field": "period_month",
      "expected": "2025-11",
      "received": "2025/11"
    },
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Common Error Codes

• VALIDATION_ERROR - Invalid input data format
• UNAUTHORIZED - Missing or invalid API key
• NOT_FOUND - Resource doesn't exist
• RATE_LIMIT_EXCEEDED - Too many requests
• INTERNAL_ERROR - Server-side error

Data Formats

Date Formats

• Period: YYYY-MM (e.g., 2025-11)
• Date: YYYY-MM-DD (e.g., 2025-11-05)
• DateTime: ISO 8601 (e.g., 2025-11-05T14:30:00Z)

Money Format

• Decimals: Always 2 decimal places
• Currency: ZAR (South African Rand)
• Examples: 150.00, 42500.00

Policy Status Values

• active - Policy in force
• lapsed - Non-payment
• cancelled - Customer cancelled

Collection Status Values

• PAID_FULL - Full amount collected
• PAID_PARTIAL - Partial amount collected (shortfall > 0)
• UNPAID - No amount collected
• CANCELLED - Policy cancelled during period

Data Retention

Retention Periods

• Minimum Retention: 30 days (dispute window)
• Recommended: 7 years (South African financial records compliance)
• Export Access: CSV files available for download at any time during retention period

Export Availability

All collection results and settlements can be exported as CSV files at any time during the retention period.

Product Information

Supported Products

Current API supports:

• Product: Old Mutual EasiFlex Funeral Plan
• Product Code: FUNERAL_01
• Type: Insurance
• Territory: South Africa
• Collection Period: Monthly
• Currency: ZAR

Additional products can be added - contact us for details.

Best Practices

API Key Management

# ✅ Good: Use environment variables
export API_KEY="your-key-here"
curl -H "X-API-Key: $API_KEY" ...

# ❌ Bad: Hardcode in scripts
curl -H "X-API-Key: your-key-here" ...

Error Handling

Always check HTTP status codes and handle errors appropriately:

response=$(curl -X POST ...)
status_code=$(echo $response | jq -r '.error.code')

if [ "$status_code" != "null" ]; then
  echo "Error: $status_code"
  exit 1
fi

Rate Limiting

Implement exponential backoff for rate limit errors:

if [ "$status_code" = "429" ]; then
  sleep $((2 ** retry_count))
  retry_count=$((retry_count + 1))
fi

Related Documentation

• Authentication - API key setup
• Policies Resource - Endpoint details
• Compliance - Agreement coverage
• Full API Reference - Interactive API documentation