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.

Use this endpoint to check the status of a payment after initiating a collection. Pass the invoice_id returned by collect payment or STK push. For checkout-based payments, you can also pass checkout_id to validate that the invoice belongs to the correct session. Method: POST
URL: https://app.kulmipay.com/api/v1/payment/status/

​
Authentication

Authenticate with your Bearer token or, for client-side polling, pass the signature returned by the collect endpoint. 
Authorization: Bearer <secret_key>

​
Request

​
invoice_id
string
required
The invoice alias ID returned in the invoice.invoice_id field of the STK push response, or the invoice ID returned by collect/checkout flows.
​
checkout_id
string
The checkout session UUID. When provided, Kulmi Pay validates that the invoice belongs to this checkout session before returning status. Use this when polling from a hosted checkout flow.

​
Response

​
invoice
object
Current snapshot of the invoice.
​
meta
object
Session metadata for the payment.

​
Code examples

curl --request POST \
  --url https://app.kulmipay.com/api/v1/payment/status/ \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "invoice_id": "GQ7KZ2XPNM"
  }'

​
Example responses

Pending — the M-Pesa STK prompt is still active or the PesaLink payment is awaiting confirmation: 
{
  "invoice": {
    "id": "GQ7KZ2XPNM",
    "state": "PENDING",
    "value": "1500.00",
    "currency": "KES",
    "provider": "M-PESA",
    "api_ref": "order_20240416_001",
    "created_at": "2024-04-16T08:23:11.042Z"
  },
  "meta": {
    "id": "a3f7c819-4e2b-4d1a-9c3f-2b8e1d7a6f05",
    "customer": {
      "customer_id": "CUST_XJ82KP",
      "phone_number": "254712345678",
      "provider": "M-PESA"
    },
    "customer_comment": null,
    "created_at": "2024-04-16T08:23:11.055Z"
  }
}
Complete — the customer paid successfully: 
{
  "invoice": {
    "id": "GQ7KZ2XPNM",
    "state": "COMPLETE",
    "value": "1500.00",
    "currency": "KES",
    "provider": "M-PESA",
    "api_ref": "order_20240416_001",
    "created_at": "2024-04-16T08:23:11.042Z"
  },
  "meta": {
    "id": "a3f7c819-4e2b-4d1a-9c3f-2b8e1d7a6f05",
    "customer": {
      "customer_id": "CUST_XJ82KP",
      "phone_number": "254712345678",
      "provider": "M-PESA"
    },
    "customer_comment": null,
    "created_at": "2024-04-16T08:23:11.055Z"
  }
}
For time-sensitive flows, use webhooks instead of polling. Kulmi Pay sends an event to your endpoint the moment the payment state changes, which is faster and more reliable than a polling loop.