POST /api/v1/payment/status

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.

Show invoice properties

invoice.invoice_id

string

Invoice alias ID, matching the value you submitted.

invoice.state

string

Current payment state. One of:

Value	Meaning
`PENDING`	The payment has been initiated but the customer has not yet approved it. Common for M-Pesa while the STK prompt is active.
`PROCESSING`	The payment has been approved and is being processed by the payment network.
`COMPLETE`	The payment succeeded and funds are in your wallet.
`FAILED`	The payment failed, was declined, or timed out.

invoice.value

string

Total amount charged, including fees where applicable.

invoice.currency

string

Settlement currency of the invoice, for example KES.

invoice.provider

string

Payment method used, for example M-PESA or PESALINK.

invoice.api_ref

string

Your reference string as submitted when the payment was initiated.

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

import requests

response = requests.post(
    "https://app.kulmipay.com/api/v1/payment/status/",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json={
        "invoice_id": "GQ7KZ2XPNM",
    },
)

data = response.json()
state = data["invoice"]["state"]

if state == "COMPLETE":
    print("Payment succeeded")
elif state == "FAILED":
    print("Payment failed")
else:
    print(f"Payment is {state}")

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.

​Authentication

​Request

​Response

​Code examples

​Example responses

Authentication

Request

Response

Code examples

Example responses