SDKs
Use the official Genuka Pay SDKs to sign API requests and integrate payments faster.
Overview
Genuka Pay provides official server-side SDKs for common backend runtimes.
The SDKs handle:
- HMAC-SHA256 request signing
X-Public-Key,X-Timestamp, andX-Signatureheaders- stable JSON body serialization for signed requests
- idempotency keys for payment creation
- typed helpers for payments, payouts, and hosted checkout
Server-side only
SDKs use your application secretKey. Never expose this key in browser
JavaScript, mobile apps, or public frontend bundles.
Official Repositories
| Language | Repository | Status |
|---|---|---|
| JavaScript / TypeScript | usegenuka/genuka-pay-sdk-js | Public, CI protected |
| PHP | usegenuka/genuka-pay-sdk-php | Public, CI protected |
Both repositories protect main with pull requests, required reviews, and the checks CI job.
JavaScript / TypeScript
pnpm add @genuka/pay-sdkimport { GenukaClient } from "@genuka/pay-sdk";
const genuka = new GenukaClient({
publicKey: process.env.GENUKA_PUBLIC_KEY!,
secretKey: process.env.GENUKA_SECRET_KEY!,
});
const payin = await genuka.payins.create(
{
amount: 2000,
currency: "XAF",
payer_phone: "+237694010263",
operator_code: "ORANGE_MONEY",
metadata: {
order_id: "ORD-1001",
},
},
{ idempotencyKey: "ORD-1001" }
);By default, the SDK targets:
https://api-pay.genuka.comThe environment (SANDBOX or LIVE) is set by the key pair, not by the URL. Only pass baseUrl to target another API instance.
PHP
composer require genuka/pay-sdkuse Genuka\Pay\GenukaClient;
$genuka = new GenukaClient(
publicKey: getenv('GENUKA_PUBLIC_KEY'),
secretKey: getenv('GENUKA_SECRET_KEY'),
);
$payin = $genuka->payins()->create([
'amount' => 2000,
'currency' => 'XAF',
'payer_phone' => '+237694010263',
'operator_code' => 'ORANGE_MONEY',
'metadata' => [
'order_id' => 'ORD-1001',
],
], idempotencyKey: 'ORD-1001');By default, the SDK targets:
https://api-pay.genuka.comThe environment (SANDBOX or LIVE) is set by the key pair, not by the URL. Only pass baseUrl to target another API instance.
Phone Numbers
Always send phone numbers in international format:
+237694010263
+241...
+235...Do not send local-only numbers such as 694010263. Genuka Pay supports multiple countries, so the country prefix must be explicit.
Available Resources
Both SDKs expose the following resources:
await genuka.payins.create(payload, { idempotencyKey: "order-1001" });
await genuka.payins.list({ per_page: 20 });
await genuka.payins.checkStatus("PX-xxx");
await genuka.payouts.create(payload, { idempotencyKey: "payout-1001" });
await genuka.payouts.list({ per_page: 20 });
await genuka.payouts.get("payout-id", { sync: true });
await genuka.payouts.cancel("payout-id");
await genuka.checkout.create(payload);
await genuka.checkout.get("checkout-token");$genuka->payins()->create($payload, idempotencyKey: 'order-1001');
$genuka->payins()->list(['per_page' => 20]);
$genuka->payins()->checkStatus('PX-xxx');
$genuka->payouts()->create($payload, idempotencyKey: 'payout-1001');
$genuka->payouts()->list(['per_page' => 20]);
$genuka->payouts()->get('payout-id', sync: true);
$genuka->payouts()->cancel('payout-id');
$genuka->checkout()->create($payload);
$genuka->checkout()->get('checkout-token');
// PHP only
$genuka->webhookEndpoints()->create($payload);
$genuka->webhookEndpoints()->list();
$genuka->webhookEndpoints()->get('endpoint-id');
$genuka->webhookEndpoints()->update('endpoint-id', $payload);
$genuka->webhookEndpoints()->delete('endpoint-id');
$genuka->webhookEndpoints()->regenerateSecret('endpoint-id');Not covered by the SDKs yet: POST /payments/quote, GET /payouts/balance, POST /payouts/{id}/retry, GET /operator-providers, webhook endpoint testing and the whole Subscriptions module. Call those endpoints directly, signing as described below. The TypeScript SDK also has no webhook endpoints resource, and its payment types do not declare return_url / cancel_url yet (the API accepts them).
Raw Signature Contract
If you are building your own SDK, sign requests using:
timestamp + HTTP_METHOD + path_with_query + raw_bodyThen compute:
HMAC_SHA256(secretKey, message)Send the hexadecimal signature as X-Signature.
How is this guide?
Last updated on