> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairosafrika.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Quickstart

> Get started with Kairos Afrika APIs in minutes

## Sign Up and Generate Your API Key

To get started with Kairos Afrika APIs, you'll need to sign up and generate your API credentials:

1. **Sign up for an account** at the [SMS Dashboard](https://sms.kairosafrika.com)
2. **Generate your API credentials** from your dashboard
3. **Choose the right authentication method** based on the API you're using

## Authentication

Different APIs use different authentication methods:

### SMS API Authentication

SMS API uses API key and secret headers:

* `x-api-key`: Your API key
* `x-api-secret`: Your API secret

### Payment API Authentication

Payment API uses Basic authentication with base64 encoded credentials:

* `Authorization: Basic <base64(username:password)>`
* Credentials are manually generated and shared with you

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.kairosafrika.com/v1/external/sms/quick" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-api-secret: YOUR_API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "254700000000",
      "from": "Kairos",
      "message": "Hello from Kairos Afrika!",
      "type": "Quick",
      "isGlobal": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kairosafrika.com/v1/external/sms/quick', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-api-secret': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '254700000000',
      from: 'Kairos',
      message: 'Hello from Kairos Afrika!',
      type: 'Quick',
      isGlobal: false
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.kairosafrika.com/v1/external/sms/quick',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'x-api-secret': 'YOUR_API_SECRET',
          'Content-Type': 'application/json'
      },
      json={
          'to': '254700000000',
          'from': 'Kairos',
          'message': 'Hello from Kairos Afrika!',
          'type': 'Quick',
          'isGlobal': False
      }
  )
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.kairosafrika.com/v1/external/sms/quick',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(array(
      'to' => '254700000000',
      'from' => 'Kairos',
      'message' => 'Hello from Kairos Afrika!',
      'type' => 'Quick',
      'isGlobal' => false
    )),
    CURLOPT_HTTPHEADER => array(
      'x-api-key: YOUR_API_KEY',
      'x-api-secret: YOUR_API_SECRET',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>
  ```
</CodeGroup>

## Environment Setup

<Warning>
  Always use the staging environment for testing before going live with production.
</Warning>

### Staging Environment

* **Base URL**: `https://api.staging.kairosafrika.com/v1`
* **Purpose**: Testing and development
* **Rate Limits**: More lenient for testing

### Production Environment

* **Base URL**: `https://api.kairosafrika.com/v1`
* **Purpose**: Live applications
* **Rate Limits**: Standard production limits

## Quick Examples

### Send an SMS

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.staging.kairosafrika.com/v1/external/sms/quick" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-api-secret: YOUR_API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "254700000000",
      "from": "YourBrand",
      "message": "Welcome to our service!",
      "type": "Quick",
      "isGlobal": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const sms = await fetch('https://api.staging.kairosafrika.com/v1/external/sms/quick', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-api-secret': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '254700000000',
      from: 'YourBrand',
      message: 'Welcome to our service!',
      type: 'Quick',
      isGlobal: false
    })
  });

  const result = await sms.json();
  console.log('Message ID:', result.messageId);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.staging.kairosafrika.com/v1/external/sms/quick',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'x-api-secret': 'YOUR_API_SECRET',
          'Content-Type': 'application/json'
      },
      json={
          'to': '254700000000',
          'from': 'YourBrand',
          'message': 'Welcome to our service!',
          'type': 'Quick',
          'isGlobal': False
      }
  )

  result = response.json()
  print('Message ID:', result.get('messageId'))
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.staging.kairosafrika.com/v1/external/sms/quick',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(array(
      'to' => '254700000000',
      'from' => 'YourBrand',
      'message' => 'Welcome to our service!',
      'type' => 'Quick',
      'isGlobal' => false
    )),
    CURLOPT_HTTPHEADER => array(
      'x-api-key: YOUR_API_KEY',
      'x-api-secret: YOUR_API_SECRET',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  $result = json_decode($response, true);
  curl_close($curl);

  echo 'Message ID: ' . $result['messageId'];
  ?>
  ```
</CodeGroup>

### Initiate a Payment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.staging.kairosafrika.cloud/paygw/v1/payment" \
    -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 1,
      "referenceNo": "889909909229",
      "payee": "Kairos",
      "narration": "PIZZAMAN/CHICKMAN",
      "msisdn": "233559400612",
      "callbackId": "6607c05155dfd4919c18c44",
      "payer": "testOne"
    }'
  ```

  ```javascript JavaScript theme={null}
  const username = 'your_username';
  const password = 'your_password';
  const credentials = btoa(`${username}:${password}`);

  const payment = await fetch('https://api.staging.kairosafrika.cloud/paygw/v1/payment', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 1,
      referenceNo: '889909909229',
      payee: 'Kairos',
      narration: 'PIZZAMAN/CHICKMAN',
      msisdn: '233559400612',
      callbackId: '6607c05155dfd4919c18c44',
      payer: 'testOne'
    })
  });

  const result = await payment.json();
  console.log('Payment Response:', result);
  ```

  ```python Python theme={null}
  import requests
  import base64

  username = 'your_username'
  password = 'your_password'
  credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()

  response = requests.post(
      'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
      headers={
          'Authorization': f'Basic {credentials}',
          'Content-Type': 'application/json'
      },
      json={
          'amount': 1,
          'referenceNo': '889909909229',
          'payee': 'Kairos',
          'narration': 'PIZZAMAN/CHICKMAN',
          'msisdn': '233559400612',
          'callbackId': '6607c05155dfd4919c18c44',
          'payer': 'testOne'
      }
  )

  result = response.json()
  print('Payment Response:', result)
  ```

  ```php PHP theme={null}
  <?php
  $username = 'your_username';
  $password = 'your_password';
  $credentials = base64_encode($username . ':' . $password);

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(array(
      'amount' => 1,
      'referenceNo' => '889909909229',
      'payee' => 'Kairos',
      'narration' => 'PIZZAMAN/CHICKMAN',
      'msisdn' => '233559400612',
      'callbackId' => '6607c05155dfd4919c18c44',
      'payer' => 'testOne'
    )),
    CURLOPT_HTTPHEADER => array(
      'Authorization: Basic ' . $credentials,
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  $result = json_decode($response, true);
  curl_close($curl);

  echo 'Payment Response: ';
  print_r($result);
  ?>
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="SMS API" icon="message" href="/sms-api/introduction">
    Send SMS messages to customers across Africa
  </Card>

  <Card title="USSD API" icon="mobile" href="/ussd-api/introduction">
    Create interactive USSD applications
  </Card>

  <Card title="Payment API" icon="credit-card" href="/payment-api/introduction">
    Process payments via mobile money and other methods
  </Card>

  <Card title="Checkout API" icon="shopping-cart" href="/checkout-api/introduction">
    Create hosted checkout sessions for seamless payments
  </Card>
</CardGroup>