API Overview
Understand the structure of the Genuka Pay API, its resources, and its operational conventions.
Introduction
The Genuka Pay API is a JSON-based REST API organized around a few resource families: payments, hosted checkout, payouts, webhook endpoints, operator coverage and subscriptions.
Base URL
https://api-pay.genuka.com/api/v1Required Headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATUREThe signature is computed with your application secret_key. Prefer the official SDKs when possible.
Response Language
Validation errors and most business error messages are available in French and English. Some messages are still returned in English only, including authentication errors, context errors (environment, application), and generic server errors. Rely on the HTTP status and the error fields, not on the message text.
Pick the language with the Accept-Language header:
Accept-Language: en- Standard values are accepted, weights included:
fr-FR,fr;q=0.9,en;q=0.8resolves tofr. - A regional variant is reduced to its language:
fr-CMresolves tofr,en-UStoen. - A language weighted
q=0is treated as refused. - An unsupported language, or
*, is ignored without an error.
If you cannot control that header, pass the language in a cookie:
Cookie: language=enThe cookie is only used when the header is missing, is *, or names no supported language. The API reads, in this order: the Accept-Language header, then the Accept-Language cookie, then the language cookie. The first value naming a supported language wins. If none does, the API answers in its default language.
The official SDKs do not send this header. To pick a language with them, pass a custom fetch (TypeScript) or a custom HttpTransport (PHP) that adds it:
const genuka = new GenukaClient({
publicKey: process.env.GENUKA_PUBLIC_KEY!,
secretKey: process.env.GENUKA_SECRET_KEY!,
fetch: (url, init) =>
fetch(url, {
...init,
headers: { ...(init?.headers as Record<string, string>), "Accept-Language": "en" },
}),
});Payments
Initiate payins, quote fees and monitor transaction status.
Hosted checkout
Create a Genuka Pay payment page and redirect your customer to it.
Payouts
Request a disbursement to a mobile money number and follow its approval.
Subscriptions
Bill customers on a recurring basis, with reminders and mobile money payment.
Webhooks
Configure endpoint subscriptions and receive asynchronous events.
Coverage
Read at runtime which operators are open in which country, and their ceilings.
Endpoints Available with an API Key
Every endpoint below accepts the HMAC headers (X-Public-Key, X-Timestamp, X-Signature). Paths are relative to https://api-pay.genuka.com.
Payments
GET /api/v1/payments
POST /api/v1/payments
POST /api/v1/payments/quote
GET /api/v1/payments/status/{track_id}There is no GET /api/v1/payments/{id} endpoint: a payment is read back by its track_id.
Hosted Checkout
POST /api/v1/checkout
GET /api/v1/checkout/{token}See Hosted checkout.
Payouts
GET /api/v1/payouts
POST /api/v1/payouts
GET /api/v1/payouts/balance
GET /api/v1/payouts/{id}
POST /api/v1/payouts/{id}/cancel
POST /api/v1/payouts/{id}/retryWebhook Endpoints
GET /api/v1/webhook-endpoints
POST /api/v1/webhook-endpoints
GET /api/v1/webhook-endpoints/{id}
PUT /api/v1/webhook-endpoints/{id}
PATCH /api/v1/webhook-endpoints/{id}
DELETE /api/v1/webhook-endpoints/{id}
POST /api/v1/webhook-endpoints/{id}/regenerate-secret
POST /api/v1/webhook-endpoints/{id}/testOperator Coverage
GET /api/v1/operator-providersSubscriptions
Products, customers, subscriptions, invoices, subscription links and the customer portal: see Subscriptions.
What Stays in the Dashboard
Application keys (/api/v1/application), KYC (/api/v1/kyc/*), payment methods (/api/v1/payment-methods) and collection links only accept the dashboard session. Called with an API key, they answer 401. Manage them from the dashboard: API keys, KYC, Payment methods.
The whole integration API requires a complete company profile (legal type, country, industry): until it is complete, these endpoints answer 403.
Environments
Each company has two applications, so two key pairs:
environment | Key prefix | Effect |
|---|---|---|
SANDBOX | pk_test_… / sk_test_… | No real money, test numbers |
LIVE | pk_live_… / sk_live_… | Real debits, KYC ceilings enforced |
The environment is carried by the key: there is no header to send and no separate URL.
API Conventions
- Amounts are sent and returned in currency units (
1000= 1,000 XAF), with an explicit ISO codeXAForXOF. - Dates are ISO 8601 in UTC (
2026-09-19T10:00:00.000000Z). Only the signature'sX-Timestampheader is in Unix seconds. - Phone numbers are in E.164 format (
+237677001122). - Identifiers (
id,token) are ULIDs.
Tracking IDs
Every payment and payout gets a track_id prefixed by the provider that processes it, followed by a lowercase ULID:
| Prefix | Example |
|---|---|
PX, MV, TM, JK, EK | JK-01k7c4t9m2y8x5b3n6q0r1s2t3 |
GP | internal identifier, when no provider is known yet |
Treat the track_id as an opaque string: do not infer anything from its prefix, which can differ from one payment to the next for the same operator.
Response Envelope
A resource is returned under data:
{ "data": { "id": "01k7c4…", "status": "PROCESSING" } }Some responses add a technical message next to data (for example "payin_fees_quoted"). Lists are also under data.
Errors
{
"message": "The amount field must be at least 1.",
"errors": {
"amount": ["The amount field must be at least 1."]
}
}errors is only present on validation errors (422). See Error handling.
Idempotency
POST /api/v1/payments and POST /api/v1/payouts accept an Idempotency-Key header. Without it, your external_id is used as the key. A second request with the same key creates nothing: it returns the existing transaction. The official SDKs send this header through the idempotencyKey option.
HMAC Authentication
Every authenticated request uses HMAC-SHA256:
- Concatenate, with no separator: the
X-Timestampvalue, the uppercase HTTP method, the path with its query string (e.g./api/v1/payments?per_page=20), then the raw request body (empty string if there is none)timestamp + HTTP_METHOD + path_with_query + raw_body - Compute
HMAC_SHA256(secret_key, message) - Send the hexadecimal signature as
X-Signature
The public key is not part of the signed string: it is only sent in X-Public-Key. The timestamp must be within 5 minutes of server time. An invalid signature, an out-of-window timestamp or an inactive key all produce the same 401 {"message": "Unauthenticated."}.
Use the official SDKs for this logic rather than implementing it by hand.
First Endpoints to Learn
How is this guide?
Last updated on