Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kulmipay.com/llms.txt

Use this file to discover all available pages before exploring further.

Refunds are created through the KulmiPay chargebacks API. When you create a refund request, KulmiPay records the request against a completed invoice and starts the internal review or processing flow. Use this only for invoices that are already COMPLETE. The refund amount must be less than or equal to the original transaction amount.

​
Create a refund

POST /api/v1/chargebacks/ 
curl --request POST \
  --url https://app.kulmipay.com/api/v1/chargebacks/ \
  --header "Authorization: Bearer ISSecretKey_live_xxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "invoice_id": "GQ7KZ2XPNM",
    "amount": "1500.00",
    "reason": "Duplicate payment"
  }'

​
Request fields

FieldRequiredDescription
invoice_idYesInvoice alias ID for the completed payment. The API also accepts invoice for compatibility.
amountYesAmount to refund. Must be greater than zero and not more than the original transaction amount.
reasonYesShort refund reason.

​
Response

{
  "chargeback_id": "CB_12345",
  "session_id": "pay-session-123",
  "transaction": {
    "transaction_id": "txn_xyz789",
    "currency": "KES",
    "value": "1500.00",
    "status": "CHARGEBACK-PENDING"
  },
  "amount": "1500.00",
  "reason": "Duplicate payment",
  "status": "PENDING",
  "resolution": null,
  "staff_created": false,
  "created_at": "2026-05-28T09:00:00Z",
  "updated_at": "2026-05-28T09:00:00Z"
}
Store chargeback_id. You use it to retrieve the refund later.

​
Refund statuses

StatusMeaning
PENDINGThe refund request has been created.
PROCESSINGKulmiPay is processing the refund.
DISPUTEDThe refund needs review or supporting action.
OVERDUEThe refund request has exceeded the expected processing window.
COMPLETEDThe refund has been completed.
CANCELLEDThe refund request was cancelled.
M-Pesa refunds may move into processing automatically after creation. Use Retrieve Refunds or chargeback webhook events to track status changes.