Quickstart

Intro

The fastest way to see Khaime work is to create a sandbox API key and fire off a single payment charge — no product catalog, no storefront setup required. This page takes you from zero to a completed test payment.

Context

This walks through the product-agnostic charge endpoint (POST /partner/payments/charge), the entry point most integrations start with because it doesn’t require you to have created a product in Khaime first — you just tell it an amount and a customer. It sits alongside the rest of the Partner API, which is authenticated the same way (see Authentication) and reports back over the same webhook system once a payment settles.

Hows

Get up and running in four steps.

1. Create Your API Key

Go to app.khaime.com and create your merchant account.

Navigate to API Settings

Go to Settings → API & Integrations → Partner API.

Generate a key

Click Create API Key. Choose Sandbox for testing, Live for production.You’ll receive:

API Key: pk_sandbox_abc123... (used in the X-API-Key header)
Webhook Secret: whsec_xyz789... (used to verify webhook signatures)

Store your webhook secret securely. It’s only shown once.

Live keys additionally require a completed KYC review and a signed API services agreement before they’ll mint — sandbox keys have no such requirement, so you can prototype immediately.

2. Create a Charge

Make your first API call:

curl -X POST https://api.khaime.com/api/v1/payments/charge \
  -H "X-API-Key: pk_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "total_amount": 5000,
    "total_currency": "USD",
    "description": "Test Payment",
    "reference": "test_001",
    "customer": {
      "email": "customer@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "country": "US"
    }
  }'

const response = await fetch('https://api.khaime.com/api/v1/payments/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pk_sandbox_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5000, // $50.00 in cents — what the customer pays, in `currency`
    currency: 'USD',
    total_amount: 5000, // what you're collecting, in your baseline currency
    total_currency: 'USD',
    description: 'Test Payment',
    reference: 'test_001',
    customer: {
      email: 'customer@example.com',
      first_name: 'Jane',
      last_name: 'Doe',
      country: 'US',
    },
  }),
});

const data = await response.json();
console.log(data.data.charge_id); // charge_a1b2c3d4

import requests

response = requests.post(
    'https://api.khaime.com/api/v1/payments/charge',
    headers={
        'X-API-Key': 'pk_sandbox_your_key_here',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 5000,
        'currency': 'USD',
        'total_amount': 5000,
        'total_currency': 'USD',
        'description': 'Test Payment',
        'reference': 'test_001',
        'customer': {
            'email': 'customer@example.com',
            'first_name': 'Jane',
            'last_name': 'Doe',
            'country': 'US',
        },
    },
)

data = response.json()
print(data['data']['charge_id'])

Amounts are in the smallest currency unit (cents for USD, kobo for NGN). 5000 = $50.00 USD.amount/currency is what the customer pays. total_amount/total_currency is what you’re collecting, in your account’s baseline currency — both are required. When they’re in the same currency (as above), they should match. When a customer pays in a different currency than your baseline, use /partner/pricing/calculate first to get the converted amount, and Khaime cross-checks it against total_amount before accepting the charge.

The response includes the gateway-specific data you need:

Response

{
  "success": true,
  "message": "Payment charge created successfully",
  "data": {
    "charge_id": "charge_a1b2c3d4",
    "payment_gateway": "embedded",
    "client_secret": "pi_xxx_secret_yyy",
    "publishable_key": "pk_test_...",
    "transaction_id": "456",
    "status": "pending",
    "mode": "sandbox"
  }
}

3. Handle the Payment

Based on the payment_gateway in the response:

Embedded Payment
Paystack

Use the client_secret and publishable_key to mount Khaime’s Payment Element:

<script src="https://js.khaime.com/v1/"></script>
<script>
  const khaime = Khaime(data.publishable_key);
  const elements = khaime.elements({ clientSecret: data.client_secret });
  const paymentElement = elements.create('payment');
  paymentElement.mount('#payment-element');
</script>

Redirect the customer to the payment_url:

window.location.href = data.payment_url;

Paystack redirects back to your callback_url after payment.

4. Receive the Webhook

After payment completes, Khaime sends a signed webhook to your configured URL:

{
  "event_type": "payment.succeeded",
  "event_id": "evt_5b1f9e2a-6b0e-4c1a-9f3d-2b7a8e1c4d6f",
  "api_version": "2026-03-28",
  "data": {
    "transaction_id": "456",
    "amount": 5000,
    "currency": "USD",
    "status": "success",
    "customer": {
      "email": "customer@example.com"
    }
  }
}

Learn more about webhooks →

Whys

The charge endpoint is deliberately product-agnostic: most integrations (a WooCommerce order, a custom cart, an invoice) already have their own idea of “what’s being sold” — Khaime doesn’t need you to duplicate that into a Khaime product just to take a payment. Requiring both amount/currency (customer-facing) and total_amount/total_currency (your baseline) up front, rather than inferring one from the other, is what lets Khaime validate a partner-supplied conversion server-side and reject a charge before money moves if the numbers don’t reconcile — a cheap check that catches an entire class of client-side currency bugs. Starting with a sandbox key rather than requiring a live key from step one means you can validate your whole integration — request shape, gateway handling, webhook delivery — before KYC and the API agreement are even in place.

Why nots

This flow does not create a Khaime product, add anything to a catalog, or manage inventory — it’s a payment primitive, not an order-management system. If you need product listings, use the product endpoints instead. It also isn’t the recurring-billing path: for subscriptions, see Subscriptions, which manages renewals and dunning rather than one-off charges. And it doesn’t verify webhook signatures for you — your endpoint must do that itself; see Webhook Security.

Multicurrency

Let customers pay in NGN, GHS, KES, EUR, and more.

Subscriptions

Set up recurring billing with automatic renewals.

WooCommerce Plugin

Zero-code integration for WordPress stores.

Webhook Security

Verify webhook signatures to prevent fraud.

Getting Started

Payments

Webhooks

Quickstart

Quickstart

Intro

Context

Hows

1. Create Your API Key

2. Create a Charge

3. Handle the Payment

4. Receive the Webhook

Whys

Why nots

Multicurrency

Subscriptions

WooCommerce Plugin

Webhook Security

​Quickstart

​Intro

​Context

​Hows

​1. Create Your API Key

​2. Create a Charge

​3. Handle the Payment

​4. Receive the Webhook

​Whys

​Why nots

Multicurrency

Subscriptions

WooCommerce Plugin

Webhook Security

Quickstart

Intro

Context

Hows

1. Create Your API Key

2. Create a Charge

3. Handle the Payment

4. Receive the Webhook

Whys

Why nots