> ## 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.

# Initiate Payment

> Initiate a new payment transaction

# Initiate Payment

This endpoint allows you to initiate a new payment transaction.

**Endpoint:** `POST /v1/payment`

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.staging.kairosafrika.cloud/paygw/v1/payment \
    --header 'Authorization: Basic $(echo -n "username:password" | base64)' \
    --header 'Content-Type: application/json' \
    --data '{
      "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 response = 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 response.json();
  console.log(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(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);
  curl_close($curl);
  echo $response;
  ?>
  ```
</RequestExample>

## Request Body

* **amount** (number, required): The payment amount.
* **referenceNo** (string, required): Reference number for the payment.
* **payee** (string, required): Name of the payee receiving the payment.
* **narration** (string, required): Payment description or narration.
* **msisdn** (string, required): Msisdn identifier for the payment.
* **callbackId** (string, required): Callback identifier for payment status updates.
* **payer** (string, required): Name or identifier of the payer.

## Responses

### 200 OK - Payment Initiated Successfully

```json theme={null}
{
    "statusCode": "0001",
    "statusMessage": "PENDING",
    "transactionId": "20416369453214532143",
    "data": {
        "totalAmount": 45.68,
        "amount": 45,
        "charge": 0.68,
        "referenceId": "20416369453214532143"
    },
    "links": [
        {
            "rel": "self",
            "href": "/payment"
        }
    ]
}
```

### 400 Bad Request - Invalid Request Data

```json theme={null}
{
    "statusCode": "0400",
    "statusMessage": "Bad Request",
    "transactionId": null,
    "data": null,
    "links": []
}
```

### 401 Unauthorized - Invalid Credentials

```json theme={null}
{
    "statusCode": "0401",
    "statusMessage": "Unauthorized",
    "transactionId": null,
    "data": null,
    "links": []
}
```

## Response Fields

* **statusCode** (string): Status code indicating the result of the payment initiation
  * `"0001"`: Payment pending
  * `"0400"`: Bad request
  * `"0401"`: Unauthorized
* **statusMessage** (string): Human-readable status message
* **transactionId** (string): Unique transaction identifier for tracking
* **data** (object): Payment details when successful
  * **totalAmount** (number): Total amount including charges
  * **amount** (number): Base payment amount
  * **charge** (number): Processing charge amount
  * **referenceId** (string): Reference identifier for the payment
* **links** (array): HATEOAS links for related actions
  * **rel** (string): Relationship type
  * **href** (string): Link URL


## OpenAPI

````yaml POST /v1/payment
openapi: 3.0.3
info:
  title: Kairos Afrika Payment API
  description: >-
    Process payments and manage transactions through the Kairos Afrika platform.
    Switch between staging and production environments using the server
    dropdown.
  version: 1.0.0
  contact:
    name: Kairos Afrika Support
    email: support@kairosafrika.com
servers:
  - url: /
    description: API Base
security:
  - basicAuth: []
paths:
  /v1/payment:
    post:
      tags:
        - Payments
      summary: Initiate Payment
      description: Initiate a new payment transaction
      operationId: initiatePayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiatePaymentRequest'
      responses:
        '200':
          description: Payment initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiatePaymentResponse'
        '400':
          description: Bad request - Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    InitiatePaymentRequest:
      type: object
      required:
        - amount
        - referenceNo
        - payee
        - narration
        - msisdn
        - callbackId
        - payer
      properties:
        amount:
          type: number
          description: Payment amount
          example: 1
        referenceNo:
          type: string
          description: Reference number for the payment
          example: '889909909229'
        payee:
          type: string
          description: Name of the payee receiving the payment
          example: Kairos
        narration:
          type: string
          description: Payment description or narration
          example: PIZZAMAN/CHICKMAN
        msisdn:
          type: string
          description: Msisdn identifier for the payment
          example: '233559400612'
        callbackId:
          type: string
          description: Callback identifier for payment status updates
          example: 6607c05155dfd4919c18c44
        payer:
          type: string
          description: Name or identifier of the payer
          example: testOne
    InitiatePaymentResponse:
      type: object
      properties:
        statusCode:
          type: string
          description: Status code indicating the result of the payment initiation
          example: '0001'
        statusMessage:
          type: string
          description: Human-readable status message
          example: PENDING
        transactionId:
          type: string
          description: Unique transaction identifier for tracking
          example: '20416369453214532143'
        data:
          type: object
          nullable: true
          description: Payment details when successful
          properties:
            totalAmount:
              type: number
              description: Total amount including charges
              example: 45.68
            amount:
              type: number
              description: Base payment amount
              example: 45
            charge:
              type: number
              description: Processing charge amount
              example: 0.68
            referenceId:
              type: string
              description: Reference identifier for the payment
              example: '20416369453214532143'
        links:
          type: array
          description: HATEOAS links for related actions
          items:
            type: object
            properties:
              rel:
                type: string
                description: Relationship type
                example: self
              href:
                type: string
                description: Link URL
                example: /payment
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: INSUFFICIENT_FUNDS
        message:
          type: string
          description: Human-readable error message
          example: The customer has insufficient funds for this transaction
        details:
          type: object
          description: Additional error details
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using base64 encoded username:password

````