Quick Start - Kulmi Pay

This guide walks you through the fastest way to make a working KulmiPay API call. You will create an account, get your API keys, and create a checkout session. If you want to test without real money first, use the sandbox environment and replace the base URL with https://sandbox.kulmipay.com.

Create a KulmiPay account

Go to app.kulmipay.com and sign up for an account. Complete business verification before processing live payments.For testing, create a separate sandbox account at sandbox.kulmipay.com.

Create an API application

In the dashboard, open API Applications and create an application.KulmiPay gives you two API keys:

Credential	What it’s for
Public Key	Browser-safe checkout and public collection requests. It starts with `ISPubKey_`.
Secret Key	Protected backend API requests. It starts with `ISSecretKey_`.

Store the secret key securely. Do not expose it in frontend code.

Create a checkout session

Use your public key to create a hosted checkout session.

curl -X POST https://sandbox.kulmipay.com/api/v1/checkout/ \
  --header 'Content-Type: application/json' \
  --data '{
    "public_key": "ISPubKey_test_xxxxxxxxxxxxxxxx",
    "amount": 1000,
    "currency": "KES",
    "email": "customer@example.com",
    "phone_number": "254712345678",
    "api_ref": "ORDER-1001",
    "redirect_url": "https://merchant.example/thank-you",
    "unique_api_ref": true
  }'

const response = await fetch("https://sandbox.kulmipay.com/api/v1/checkout/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    public_key: "ISPubKey_test_xxxxxxxxxxxxxxxx",
    amount: 1000,
    currency: "KES",
    email: "customer@example.com",
    phone_number: "254712345678",
    api_ref: "ORDER-1001",
    redirect_url: "https://merchant.example/thank-you",
    unique_api_ref: true
  })
});

const checkout = await response.json();
console.log(checkout.url);

import requests

response = requests.post(
    "https://sandbox.kulmipay.com/api/v1/checkout/",
    json={
        "public_key": "ISPubKey_test_xxxxxxxxxxxxxxxx",
        "amount": 1000,
        "currency": "KES",
        "email": "customer@example.com",
        "phone_number": "254712345678",
        "api_ref": "ORDER-1001",
        "redirect_url": "https://merchant.example/thank-you",
        "unique_api_ref": True,
    },
)

checkout = response.json()
print(checkout["url"])

<?php

require_once __DIR__ . "/vendor/autoload.php";

use KulmiPay\KulmiPayPHP\Checkout;
use KulmiPay\KulmiPayPHP\Customer;

$credentials = [
    "publishable_key" => "ISPubKey_test_xxxxxxxxxxxxxxxx",
    "sandbox" => true,
];

$customer = new Customer();
$customer->email = "customer@example.com";
$customer->phone_number = "254712345678";

$checkout = new Checkout();
$checkout->init($credentials);

$response = $checkout->create(
    1000,
    "KES",
    $customer,
    null,
    "https://merchant.example/thank-you",
    "ORDER-1001",
    null,
    null,
    "BUSINESS-PAYS",
    "BUSINESS-PAYS",
    null,
    true
);

echo $response->url;

The response includes a hosted url. Redirect the customer to that URL, or render checkout with the kulmipay browser SDK.

Call a protected endpoint

For backend-only endpoints, pass your secret key as a Bearer token.

curl --request GET \
  --url https://sandbox.kulmipay.com/api/v1/wallets/ \
  --header 'Authorization: Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx'

<?php

require_once __DIR__ . "/vendor/autoload.php";

use KulmiPay\KulmiPayPHP\Wallet;

$wallet = new Wallet();
$wallet->init([
    "token" => "ISSecretKey_test_xxxxxxxxxxxxxxxx",
    "sandbox" => true,
]);

$wallets = $wallet->retrieve();

Next steps

Authentication

Understand public keys, secret keys, and environment-specific credentials.

Client Libraries

Install and configure the browser checkout SDK or PHP SDK.

Checkout

Learn the full hosted checkout flow.

Sandbox

Test your integration before going live.

Introduction

Authentication

​Next steps

Authentication

Client Libraries

Checkout

Sandbox

Next steps