SDKs
Utilisez les SDKs officiels Genuka Pay pour signer les requêtes API et intégrer les paiements plus vite.
Vue d’ensemble
Genuka Pay fournit des SDKs officiels côté serveur pour les runtimes backend courants.
Les SDKs gèrent :
- la signature HMAC-SHA256 des requêtes
- les headers
X-Public-Key,X-TimestampetX-Signature - la sérialisation JSON stable du body signé
- les clés d’idempotence pour la création de paiements
- des helpers pour paiements, payouts et hosted checkout
Côté serveur uniquement
Les SDKs utilisent votre secretKey d’application. Ne l’exposez jamais dans
du JavaScript navigateur, des apps mobiles ou des bundles frontend publics.
Repositories officiels
| Langage | Repository | Statut |
|---|---|---|
| JavaScript / TypeScript | usegenuka/genuka-pay-sdk-js | Public, CI protégée |
| PHP | usegenuka/genuka-pay-sdk-php | Public, CI protégée |
Les deux repositories protègent main avec pull request obligatoire, review obligatoire et job CI checks requis.
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" }
);Par défaut, le SDK pointe vers :
https://api-pay.genuka.comL'environnement (SANDBOX ou LIVE) est déterminé par la paire de clés, pas par l'URL. Passez baseUrl uniquement pour cibler une autre instance de l'API.
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');Par défaut, le SDK pointe vers :
https://api-pay.genuka.comL'environnement (SANDBOX ou LIVE) est déterminé par la paire de clés, pas par l'URL. Passez baseUrl uniquement pour cibler une autre instance de l'API.
Numéros de téléphone
Envoyez toujours les numéros au format international :
+237694010263
+241...
+235...N’envoyez pas de numéros locaux comme 694010263. Genuka Pay supporte plusieurs pays, donc le préfixe pays doit être explicite.
Ressources disponibles
Les deux SDKs exposent les ressources suivantes :
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 uniquement
$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');Ce que les SDKs ne couvrent pas encore : POST /payments/quote, GET /payouts/balance, POST /payouts/{id}/retry, GET /operator-providers, le test d'un endpoint webhook et l'ensemble du module Abonnements. Appelez ces endpoints directement, en signant comme décrit ci-dessous. Le SDK TypeScript n'a pas non plus de ressource pour les endpoints webhook, et ses types de paiement ne déclarent pas encore return_url / cancel_url (le champ est accepté par l'API).
Contrat de signature brut
Si vous construisez votre propre SDK, signez les requêtes avec :
timestamp + HTTP_METHOD + path_with_query + raw_bodyPuis calculez :
HMAC_SHA256(secretKey, message)Envoyez la signature hexadécimale dans X-Signature.
How is this guide?
Last updated on