Skip to main content
The Kulmi Pay sandbox is a fully isolated environment where you can test your integration end-to-end without moving real money. It mirrors the live API’s endpoints and responses, so switching to production requires only a credential and base URL change.
Never use live credentials in the sandbox, and never use sandbox credentials against the live API. Each environment validates that credentials match — a mismatch returns an authentication error.

​
Base URLs

EnvironmentBase URL
Sandboxhttps://sandbox.kulmipay.com
Livehttps://app.kulmipay.com
Swap the base URL in your API client or environment configuration to switch between environments.

​
Setting up sandbox credentials

1

Create a sandbox account

Go to sandbox.kulmipay.com and sign up. Sandbox accounts are separate from live accounts — you need a distinct registration for each environment.
2

Create an API application

From your sandbox dashboard, navigate to API Applications and create a new application. You’ll receive a set of test credentials:
  • Client ID — identifies your sandbox application
  • Client Secret — authenticates your sandbox application
  • Public Key — in the format ISPubKey_test_...
  • API Secret Key — in the format ISSecretKey_test_...
3

Generate a sandbox token

Use the same /api/token/ flow as production, but point to the sandbox base URL:
curl -X POST \
  -d "grant_type=password&username=<SANDBOX-USERNAME>&password=<SANDBOX-PASSWORD>" \
  -u "<SANDBOX-CLIENT-ID>:<SANDBOX-CLIENT-SECRET>" \
  https://sandbox.kulmipay.com/api/token/
Use the returned access_token in the Authorization: Bearer header for all sandbox requests.

​
Sandbox test data

Use the values below to simulate common payment scenarios. These identifiers only work in the sandbox environment.

​
M-Pesa test phone numbers

Phone numberSimulated behavior
254723890353Payment succeeds
254700000000Payment fails (insufficient funds)
254711111111Payment times out

​
Test cards

Card numberExpiryCVVSimulated behavior
4111111111111111Any future dateAny 3 digitsPayment succeeds (Visa)
5500005555555559Any future dateAny 3 digitsPayment succeeds (Mastercard)
4000000000000002Any future dateAny 3 digitsPayment declined

​
Test amounts

There are no restrictions on amounts in the sandbox. You can use small values like 1 or 5 to keep test data clean.
Webhook notifications in the sandbox behave identically to production. Configure your webhook endpoint to a publicly accessible URL (or use a tunneling tool like ngrok during local development) to receive sandbox events.

​
Switching from sandbox to live

When you’re ready to process real transactions:
  1. Replace the sandbox base URL (https://sandbox.kulmipay.com) with the live URL (https://app.kulmipay.com) in your configuration.
  2. Replace your sandbox credentials (Client ID, Client Secret, Public Key, API Secret Key) with the corresponding live credentials from your live dashboard.
  3. Ensure your webhook endpoint URL is pointing to your production server.
  4. Complete any required business verification in your live account before processing payments.
If you store credentials in environment variables, you only need to update those values — no code changes required.