Skip to main content
This guide walks you through everything you need to make your first live API call — from creating an account to triggering an M-Pesa payment prompt on a real phone. If you want to test without real money first, use the sandbox environment and replace the base URL with https://sandbox.kulmipay.com.
1

Create a Kulmi Pay account

Go to app.kulmipay.com and sign up for an account. Complete the business verification steps to unlock live payment processing.If you want to test first, you can skip verification and start with sandbox credentials at sandbox.kulmipay.com.
2

Create an API application

After logging in, navigate to API Applications in your dashboard and create a new application.Kulmi Pay will generate three credentials for you:
CredentialWhat it’s for
Client IDIdentifies your application when requesting a token
Client SecretAuthenticates your application — keep this private
Public KeyUsed for checkout and collection requests
Copy all three values and store them securely. You cannot retrieve the Client Secret again after leaving the page.
3

Get an access token

Exchange your credentials for a Bearer token by posting to /api/token/. Pass your CLIENT-ID and CLIENT-SECRET as HTTP Basic auth credentials, and your API caller username and password in the request body.
curl -X POST \
  -d "grant_type=password&username=<API-CALLER-USERNAME>&password=<API-CALLER-PASSWORD>" \
  -u "<CLIENT-ID>:<CLIENT-SECRET>" \
  https://app.kulmipay.com/api/token/
A successful response returns a JSON object containing your access_token. Use that value as a Bearer token in all subsequent requests.
4

Trigger an M-Pesa STK push

With your token in hand, you can now initiate a payment. The request below sends an STK push to a customer’s phone — they’ll see a prompt asking them to enter their M-Pesa PIN to complete the payment.Replace <token> with the access_token from the previous step, and update phone_number, amount, and api_ref with your real values.
curl -X POST https://app.kulmipay.com/api/v1/payment/collection/stk-push/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone_number": "254723890353",
    "amount": 10,
    "api_ref": "YOUR-UNIQUE-TRACKING-NUMBER"
  }'
FieldDescription
phone_numberCustomer’s phone number in international format (e.g. 254723890353)
amountAmount in KES — minimum KES 10
api_refYour unique reference for this transaction — use it to look up the payment later
Kulmi Pay will return a response confirming the STK push was initiated. The customer’s phone will ring within a few seconds with the payment prompt. Configure a webhook to receive the final payment status once the customer responds.

​
Next steps

Authentication

Understand token expiry, the public key flow, and how to handle auth errors.

Webhooks

Set up real-time notifications so your server knows when payments complete.

Collections overview

Explore all payment methods — cards, bank transfers, and payment links.

Sandbox

Test your full integration with simulated transactions before going live.