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.

Webhooks let KulmiPay push notifications to your server when supported account events happen. Instead of polling for every payment or transfer, you register an HTTPS endpoint and KulmiPay sends a JSON POST whenever a subscribed event changes state.

​
Supported events

Event flagDescription
collection_eventPayment invoice state changes for M-Pesa and PesaLink collections.
send_money_eventSend Money payment file state changes.
reversal_eventChargeback and reversal state changes.
wallet_transfer_eventWallet intra-transfer events.

​
Requirements

  • Your endpoint must accept POST requests.
  • Your endpoint must use HTTPS.
  • Your endpoint should respond with HTTP 200 or 201 quickly.
  • Your handler should be idempotent because events can be retried or replayed.
  • Use the challenge value in the payload to verify the request came from KulmiPay.

​
Payload shape

KulmiPay posts the event resource directly to your endpoint and adds the configured challenge value to the JSON body. The webhook event log stores the event topic, but the merchant endpoint receives the event payload itself. 
{
  "invoice_id": "GQ7KZ2XPNM",
  "state": "COMPLETE",
  "provider": "M-PESA",
  "value": "1500.00",
  "currency": "KES",
  "challenge": "your-configured-secret"
}

​
Next steps

How to Setup Webhook

Configure your endpoint and verify incoming events.

Payment Collection Events

Handle M-Pesa and PesaLink collection updates.

Send Money Events

Handle Send Money file status changes.

Wallet Intra-Transfer Events

Handle wallet transfer updates.