Logo GenukaGenuka Pay
Guides

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, and X-Signature headers
  • 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

LanguageRepositoryStatus
JavaScript / TypeScriptusegenuka/genuka-pay-sdk-jsPublic, CI protected
PHPusegenuka/genuka-pay-sdk-phpPublic, CI protected

Both repositories protect main with pull requests, required reviews, and the checks CI job.

JavaScript / TypeScript

Install
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" }
);

By default, the SDK targets:

https://api-pay.genuka.com

The environment (SANDBOX or LIVE) is set by the key pair, not by the URL. Only pass baseUrl to target another API instance.

PHP

Install
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');

By default, the SDK targets:

https://api-pay.genuka.com

The 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:

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 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_body

Then compute:

HMAC_SHA256(secretKey, message)

Send the hexadecimal signature as X-Signature.

How is this guide?

Last updated on