Introduction
API Reference
Complete reference documentation for the KPay API.
Complete KPay API documentation
Getting started
Base URL
All requests must be sent to this <strong>single</strong> URL — it is your API key (<code>kpay_test_</code> or <code>kpay_live_</code>) that determines the environment, not the URL:
https://admin.kpay.siteAuthentication
Every authenticated request transmits your two keys in the HTTP headers:
X-API-Key: kpay_test_xxxxxxxxxxxxxxxx
X-Secret-Key: sk_test_xxxxxxxxxxxxxxxxDetails: Authentication →
Environments
Two environments, distinguished by the <strong>key prefix</strong> (the URL is the same). By default your account is in <strong>sandbox</strong>; production unlocks after KYC validation.
Sandbox (test)
Keys prefixed <code>kpay_test_</code> / <code>sk_test_</code>. KPay routes to the test environment; use test numbers (the outcome depends on the number). No real money.
Production (live)
Keys prefixed <code>kpay_live_</code> / <code>sk_live_</code>, available after <strong>validated KYC</strong>. Real transactions with real numbers.
Response format
Success responses return the resource directly. Errors follow a standard envelope.
{
"id": "pay_abc123",
"reference": "KPAY-20260514-ABC123",
"status": "PENDING",
"amount": 5000,
"currency": "XAF",
"externalId": "ORDER-12345"
}The <code>message</code> field is always present. See API Errors.
HTTP Codes
Rate limiting
The API enforces a limit of <strong>100 requests/minute</strong> (20/min for gateway initialization, 60/min for gateway polling). When exceeded, a <code>429 Too Many Requests</code> response is returned.
Exponential backoff
API Resources
Versioning
The current version is <code>v1</code>, included in the endpoint path (e.g. <code>/api/v1/payments/init</code>). Future versions will be exposed via a new version segment.