Skip to main content

​
Partner API

​
Intro

The Khaime Partner API lets you create payments, manage subscriptions, and query transaction data from your server — everything under https://api.khaime.com/api/v1/partner.

​
Context

This is the same API a plugin integration (WooCommerce, WordPress) calls under the hood, so anything documented here applies whether you’re calling it directly or debugging plugin behavior. Requests are authenticated with an API key (see Authentication); the amounts, currencies, and fee concepts every endpoint uses are covered in Core Concepts; and payment completions are reported back asynchronously via webhooks rather than as a synchronous response to the charge call.

​
Hows

​
Base URL

All endpoint paths in this documentation are relative to this base URL.

​
Authentication

All requests require an API key in the X-API-Key header:
API keys start with pk_sandbox_ (test) or pk_live_ (production). Generate keys in your Khaime Dashboard.

​
Rate Limits

Each API key has its own rate_limit_per_hour, set when the key is created (auto-provisioned sandbox keys default to 1,000/hour). There is no separate per-second burst cap — the limit is a rolling count reset every hour. When you exceed it, the API returns 429 Too Many Requests with a retry_after (seconds until the limit resets).

​
Response Format

Most endpoints follow this structure:
Success
Error
error_code is the stable, machine-readable field to branch your error handling on — the message text may change over time. A few endpoints (notably authentication failures on the API key itself, before your key is even resolved) return a simpler { "error": "...", "message": "..." } shape without success or error_code — check the specific endpoint’s documented error cases.

​
HTTP Status Codes

​
Pagination

List endpoints support pagination via query parameters:

​
Whys

A per-key rate limit rather than a platform-wide one means one integration’s traffic spike doesn’t degrade every other partner sharing the same account, and it lets a merchant request a higher limit for a specific key without changing the default for everything else. Carrying error_code alongside message is what makes it safe to build automated error handling — you can match on error_code and treat the human-readable message as display text only, which won’t break if wording changes.

​
Why nots

The Partner API is not a webhook-free, purely synchronous payment API — charge creation returns a pending state, and the authoritative outcome (success, failure, refund) arrives over the webhook channel. Don’t poll a charge endpoint in a tight loop expecting the final state; listen for the webhook, or use the session-status endpoint sparingly. It also doesn’t apply the same response shape everywhere — the tables above describe the common case, but always check an individual endpoint’s page for its exact success/error fields before assuming the generic shape holds.