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

# Initialize Checkout Session

> Initialize a new checkout session for payment collection

# Initialize Checkout Session

This endpoint allows you to initialize a new checkout session for payment collection.

**Endpoint:** `POST /v1/checkout/initialize`

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.kairosafrika.com/v1/checkout/initialize \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "Checkout",
      "reference": "323435452432423242",
      "amount": 1,
      "description": "A brief description",
      "returnUrl": "https://url.com"
    }'
  ```
</RequestExample>

## Request Body

* **title** (string, required): Title for the checkout session.
* **reference** (string, required): Your internal reference for this checkout.
* **amount** (number, required): The checkout amount.
* **description** (string, required): A brief description of what the customer is paying for.
* **returnUrl** (string, required): URL to redirect customer after payment completion.

## Responses

* **201 Created**: Checkout session created.
* **400 Bad Request**: Invalid request data.


## OpenAPI

````yaml POST /v1/checkout/initialize
openapi: 3.0.3
info:
  title: Kairos Afrika Checkout API
  description: >-
    Create hosted checkout sessions for seamless payment collection. 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:
  - bearerAuth: []
paths:
  /v1/checkout/initialize:
    post:
      tags:
        - Checkout
      summary: Initialize Checkout Session
      description: Initialize a new checkout session for payment collection
      operationId: initializeCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitializeCheckoutRequest'
      responses:
        '201':
          description: Checkout session initialized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializeCheckoutResponse'
        '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:
    InitializeCheckoutRequest:
      type: object
      required:
        - title
        - reference
        - amount
        - description
        - returnUrl
      properties:
        title:
          type: string
          description: Title for the checkout session
          example: Checkout
        reference:
          type: string
          description: Your internal reference for this checkout
          example: '323435452432423242'
        amount:
          type: number
          format: float
          minimum: 0.01
          description: Checkout amount
          example: 1
        description:
          type: string
          description: A brief description of what the customer is paying for
          example: A brief description
        returnUrl:
          type: string
          format: uri
          description: URL to redirect customer after payment completion
          example: https://url.com
    InitializeCheckoutResponse:
      type: object
      properties:
        checkoutId:
          type: string
          description: Unique identifier for the checkout session
          example: 040956bf1210aa19c948da8d5769cea01313dc23022025
        checkoutUrl:
          type: string
          format: uri
          description: URL where customer can complete payment
          example: >-
            https://checkout.kairosafrika.com/pay/040956bf1210aa19c948da8d5769cea01313dc23022025
        status:
          type: string
          enum:
            - active
            - completed
            - expired
            - cancelled
          description: Current status of the checkout session
          example: active
        title:
          type: string
          description: Title of the checkout session
          example: Checkout
        reference:
          type: string
          description: Your internal reference for this checkout
          example: '323435452432423242'
        amount:
          type: number
          format: float
          description: Checkout amount
          example: 1
        description:
          type: string
          description: Description of what the customer is paying for
          example: A brief description
        returnUrl:
          type: string
          format: uri
          description: URL to redirect customer after payment completion
          example: https://url.com
        createdAt:
          type: string
          format: date-time
          description: When the checkout session was created
          example: '2024-01-15T10:30:00Z'
        expiresAt:
          type: string
          format: date-time
          description: When the checkout session expires
          example: '2024-12-25T23:59:59Z'
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: INVALID_AMOUNT
        message:
          type: string
          description: Human-readable error message
          example: The amount must be greater than 0
        details:
          type: object
          description: Additional error details
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Enter your API key as a Bearer token

````