​

Initiate Payment

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"
  }'

​

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

{
    "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

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

​

401 Unauthorized - Invalid Credentials

{
    "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