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.

Enable collection_event to receive notifications when a collection invoice is created or changes state. Collection events are sent for invoices with a positive value. They use the same invoice shape returned by the collection APIs, plus your configured challenge.

​
When it fires

  • A collection invoice is created.
  • The invoice state changes, for example from PENDING to COMPLETE or FAILED.

​
Payload

{
  "invoice_id": "GQ7KZ2XPNM",
  "state": "COMPLETE",
  "provider": "M-PESA",
  "charges": "33.00",
  "net_amount": "1467.00",
  "currency": "KES",
  "value": "1500.00",
  "account": "254712345678",
  "api_ref": "ORDER-1001",
  "clearing_status": "AVAILABLE",
  "mpesa_reference": "RKT123ABC",
  "host": "https://app.kulmipay.com",
  "retry_count": 0,
  "failed_reason": null,
  "failed_code": null,
  "failed_code_link": null,
  "created_at": "2026-05-28T08:23:11Z",
  "updated_at": "2026-05-28T08:24:05Z",
  "challenge": "your-configured-secret"
}

​
Important fields

FieldDescription
invoice_idInvoice alias ID. Use this with the payment status endpoint.
stateInvoice state, such as PENDING, PROCESSING, COMPLETE, or FAILED.
providerCollection provider, currently M-PESA or PESALINK.
valueGross collected amount.
net_amountAmount after applicable charges.
api_refYour reconciliation reference.
challengeYour configured challenge value. Verify it before processing the event.