Development Guide

Development Environment Setup

Recommended: Always start development using our staging environment to avoid affecting live data.

Environment Configuration

Configure your application to use the appropriate environment:

// Environment configuration
const config = {
  staging: {
    // SMS, USSD, Checkout APIs
    baseUrl: 'https://api.staging.kairosafrika.com/v1',
    // Payment API
    paymentBaseUrl: 'https://api.staging.kairosafrika.cloud/paygw',
    apiKey: process.env.KAIROS_STAGING_API_KEY
  },
  production: {
    // SMS, USSD, Checkout APIs
    baseUrl: 'https://api.kairosafrika.com/v1',
    // Payment API
    paymentBaseUrl: 'https://api.kairosafrika.cloud/paygw',
    apiKey: process.env.KAIROS_PRODUCTION_API_KEY
  }
};

const environment = process.env.NODE_ENV === 'production' ? 'production' : 'staging';
const apiConfig = config[environment];

import os

# Environment configuration
CONFIG = {
    'staging': {
        # SMS, USSD, Checkout APIs
        'base_url': 'https://api.staging.kairosafrika.com/v1',
        # Payment API
        'payment_base_url': 'https://api.staging.kairosafrika.cloud/paygw',
        'api_key': os.getenv('KAIROS_STAGING_API_KEY')
    },
    'production': {
        # SMS, USSD, Checkout APIs
        'base_url': 'https://api.kairosafrika.com/v1',
        # Payment API
        'payment_base_url': 'https://api.kairosafrika.cloud/paygw',
        'api_key': os.getenv('KAIROS_PRODUCTION_API_KEY')
    }
}

environment = 'production' if os.getenv('ENV') == 'production' else 'staging'
api_config = CONFIG[environment]

<?php
// Environment configuration
$config = [
    'staging' => [
        // SMS, USSD, Checkout APIs
        'base_url' => 'https://api.staging.kairosafrika.com/v1',
        // Payment API
        'payment_base_url' => 'https://api.staging.kairosafrika.cloud/paygw',
        'api_key' => $_ENV['KAIROS_STAGING_API_KEY']
    ],
    'production' => [
        // SMS, USSD, Checkout APIs
        'base_url' => 'https://api.kairosafrika.com/v1',
        // Payment API
        'payment_base_url' => 'https://api.kairosafrika.cloud/paygw',
        'api_key' => $_ENV['KAIROS_PRODUCTION_API_KEY']
    ]
];

$environment = $_ENV['ENV'] === 'production' ? 'production' : 'staging';
$apiConfig = $config[$environment];
?>

Error Handling

Implement robust error handling for all API calls:

async function sendSMS(data) {
  try {
    const response = await fetch(`${apiConfig.baseUrl}/sms`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiConfig.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }

    return await response.json();
  } catch (error) {
    console.error('SMS sending failed:', error);
    throw error;
  }
}

import requests
from requests.exceptions import RequestException

def send_sms(data):
    try:
        response = requests.post(
            f"{api_config['base_url']}/sms",
            headers={
                'Authorization': f"Bearer {api_config['api_key']}",
                'Content-Type': 'application/json'
            },
            json=data,
            timeout=30
        )

        response.raise_for_status()
        return response.json()

    except RequestException as e:
        print(f"SMS sending failed: {e}")
        raise

Rate Limiting

Handle rate limits gracefully:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

import time
import requests
from requests.exceptions import RequestException

def api_call_with_retry(url, **kwargs):
    max_retries = 3

    for attempt in range(1, max_retries + 1):
        try:
            response = requests.request(**kwargs, url=url)

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Retrying after {retry_after} seconds...")
                time.sleep(retry_after)
                continue

            return response

        except RequestException as e:
            if attempt == max_retries:
                raise
            time.sleep(attempt)

Testing

Unit Testing

// tests/sms.test.js
const { sendSMS } = require('../src/sms');

// Mock the API
jest.mock('node-fetch');
const fetch = require('node-fetch');

describe('SMS API', () => {
  beforeEach(() => {
    fetch.mockClear();
  });

  test('should send SMS successfully', async () => {
    const mockResponse = {
      messageId: 'msg_123',
      status: 'sent'
    };

    fetch.mockResolvedValue({
      ok: true,
      json: () => Promise.resolve(mockResponse)
    });

    const result = await sendSMS({
      to: ['+254700000000'],
      message: 'Test message'
    });

    expect(result.messageId).toBe('msg_123');
    expect(fetch).toHaveBeenCalledWith(
      expect.stringContaining('/sms'),
      expect.objectContaining({
        method: 'POST'
      })
    );
  });
});

# tests/test_sms.py
import pytest
from unittest.mock import patch, Mock
from src.sms import send_sms

@patch('src.sms.requests.post')
def test_send_sms_success(mock_post):
    # Mock successful response
    mock_response = Mock()
    mock_response.json.return_value = {
        'messageId': 'msg_123',
        'status': 'sent'
    }
    mock_response.raise_for_status.return_value = None
    mock_post.return_value = mock_response

    result = send_sms({
        'to': ['+254700000000'],
        'message': 'Test message'
    })

    assert result['messageId'] == 'msg_123'
    mock_post.assert_called_once()

Logging and Monitoring

Implement comprehensive logging:

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'api-calls.log' }),
    new winston.transports.Console()
  ]
});

async function loggedApiCall(endpoint, data) {
  const startTime = Date.now();

  try {
    logger.info('API call started', { endpoint, data });
    const result = await makeApiCall(endpoint, data);

    logger.info('API call successful', {
      endpoint,
      duration: Date.now() - startTime,
      resultId: result.id
    });

    return result;
  } catch (error) {
    logger.error('API call failed', {
      endpoint,
      duration: Date.now() - startTime,
      error: error.message
    });
    throw error;
  }
}

Security Best Practices

Never commit API keys to version control. Always use environment variables.

API Key Management

Environment Variables: Store API keys in environment variables
Key Rotation: Regularly rotate your API keys
Least Privilege: Use separate keys for different environments
Monitoring: Monitor API key usage for unusual activity

Request Security

Always use HTTPS
Validate all input data
Implement request signing for sensitive operations
Use webhook signature verification

Troubleshooting

401 Unauthorized Error

Cause: Invalid or missing API keySolution:

Verify your API key is correct
Check that the Authorization header is properly formatted
Ensure you’re using the right key for the environment

429 Rate Limit Exceeded

Cause: Too many requests in a short periodSolution:

Implement exponential backoff
Check the Retry-After header
Consider upgrading your plan for higher limits

Webhook Not Receiving Events

Cause: Webhook endpoint issuesSolution:

Verify your webhook URL is accessible
Check webhook signature verification
Ensure your endpoint returns 200 status
Check webhook logs in your dashboard

Getting Started

SMS API

USSD Webhooks

Payment API

Email API

Checkout API

Development Environment Setup

Environment Configuration

Error Handling

Rate Limiting

Testing

Unit Testing

Logging and Monitoring

Security Best Practices

API Key Management

Request Security

Troubleshooting

​Development Environment Setup

​Environment Configuration

​Error Handling

​Rate Limiting

​Testing

​Unit Testing

​Logging and Monitoring

​Security Best Practices

​API Key Management

​Request Security

​Troubleshooting

Development Environment Setup

Environment Configuration

Error Handling

Rate Limiting

Testing

Unit Testing

Logging and Monitoring

Security Best Practices

API Key Management

Request Security

Troubleshooting