Logo GenukaGenuka Pay
Guides

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-Timestamp et X-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

LangageRepositoryStatut
JavaScript / TypeScriptusegenuka/genuka-pay-sdk-jsPublic, CI protégée
PHPusegenuka/genuka-pay-sdk-phpPublic, CI protégée

Les deux repositories protègent main avec pull request obligatoire, review obligatoire et job CI checks requis.

JavaScript / TypeScript

Installation
pnpm add @genuka/pay-sdk
payments.ts
import { 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.com

L'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

Installation
composer require genuka/pay-sdk
payments.php
use 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.com

L'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 :

JavaScript / TypeScript
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");
PHP
$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_body

Puis calculez :

HMAC_SHA256(secretKey, message)

Envoyez la signature hexadécimale dans X-Signature.

How is this guide?

Last updated on