​

Core Concepts

​

Intro

Five ideas explain almost everything else in these docs: how currencies and conversion work, how gateways get picked, what sandbox vs. live means, how amounts are represented, and how fees are calculated. Read this page once before you start calling endpoints.

​

Context

These docs primarily cover the Partner API and plugin integrations — for merchants who want to connect their existing stores (WooCommerce, WordPress, custom platforms) to Khaime’s payment and multicurrency capabilities. Every endpoint in the API Reference assumes you understand the concepts below — the charge, subscription, and pricing endpoints all take amounts and currencies shaped exactly the way this page describes.

​

Hows

​

Currencies & Conversion

Khaime operates with two currency concepts:

• Baseline Currency: The merchant’s home currency (e.g., USD). Products are priced in this currency. Payouts settle in this currency.
• Customer Currency: The currency the customer sees and pays in (e.g., NGN). Determined by IP geolocation or explicit selection.

Exchange rates are updated frequently and cached with volatility-aware TTLs — stable pairs are cached longer, volatile pairs refresh more often. Because rates can drift slightly between when you fetch a quote and when you submit a charge, Khaime accepts a small tolerance when reconciling a customer-currency amount against your baseline-currency total_amount rather than rejecting on any mismatch.

​

Gateway Routing

Khaime automatically selects the payment gateway based on the customer’s currency and location — currently Stripe and Paystack, with additional regional gateways (StartButton, Flutterwave) covering specific African currencies. Supported regions include Africa, North America, and Europe, among others. Merchants don’t need to configure individual gateways — Khaime handles the routing, and the charge response tells you which gateway was used (payment_gateway) so your client code knows whether to render Stripe Elements or redirect to a hosted checkout URL.

​

Environments

Sandbox uses test credentials for each gateway (Stripe test mode, Paystack test keys) — no real charges are made. Sandbox keys can be created by a business owner or a staff member with the right permission; live keys can only be created by the business owner, and only after KYC verification and a signed API agreement are on file.

​

Amounts

All monetary amounts in the API are expressed in the smallest currency unit: A handful of currencies (JPY, KRW, and other zero-decimal currencies) have no minor unit — the amount you send is the whole-currency amount as-is.

​

Fees

Every charge carries a transaction fee, calculated as a percentage of the amount plus a small fixed fee. Khaime doesn’t publish a fixed rate here because the actual percentage depends on currency, gateway, and any custom rate agreed for your business — a number quoted in these docs would go stale or mislead the moment your business’s rate differs from the default.

• Who pays: Configurable per merchant — the customer can absorb fees or the merchant can.
• Fee details are included in every charge response under fee_details, and you can fetch a breakdown ahead of time via the fees endpoint in the API Reference.

​

Webhooks

Khaime sends real-time notifications for payment events. Webhooks are:

• Signed with HMAC-SHA256 using your webhook secret
• Retried up to 3 times with 2-second delays between attempts
• Idempotent — each event has a unique event_id for deduplication

Learn more →

​

Whys

Splitting currency into “baseline” and “customer” rather than letting a merchant price everything in dozens of currencies keeps the merchant’s side simple — they think in one currency, Khaime handles the rest. Blending the platform’s take into the gateway rate (rather than stacking a separate platform fee on top of raw gateway pricing) is what lets Khaime quote one number per currency instead of asking every integration to compute two fees and reconcile rounding between them. And expressing amounts as integers in the smallest unit avoids the floating-point rounding errors that plague money math done in decimal major units.

​

Why nots

Khaime doesn’t let a merchant hand-pick a gateway per transaction — routing is automatic based on currency and location, by design, since manual gateway selection is exactly the maintenance burden this system exists to remove. It also doesn’t guarantee a fixed fee rate across all currencies, gateways, and merchants; rates can be customized per business and can change, so don’t hardcode a fee percentage in your integration — read fee_details from the response or call the fee-breakdown endpoint instead. Cached exchange rates mean the rate you saw in a pricing quote is not guaranteed to be the exact rate charged if there’s a delay before the actual charge — Khaime tolerates small drift automatically, but don’t build logic that assumes byte-for-byte rate matching.