Logo GenukaGenuka Pay
Getting Started

Authentication

Authenticate Genuka Pay API requests securely with your application secret key.

Introduction

Authenticated Genuka Pay calls use your application public_key plus an HMAC-SHA256 signature generated with your secret_key.

Required Headers

Authenticated Request Headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Manage Credentials

Manage credentials from API Keys, not from a public API endpoint.

Open that page to reveal the current secret_key, review rotation history, or generate a new key when needed.

What the API Keys Page Usually Exposes

The API keys page commonly exposes:

  • id
  • name
  • environment (SANDBOX or LIVE)
  • status
  • public_key
  • secret_key
  • billable
  • rotations

Signing a Request

sign.ts
import crypto from "crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const method = "POST";
const path = "/api/v1/payments"; // include the query string if there is one
const body = JSON.stringify({ amount: 1000, currency: "XAF", payer_phone: "+237677001122" });

const signature = crypto
  .createHmac("sha256", process.env.GENUKA_SECRET_KEY!)
  .update(timestamp + method + path + body)
  .digest("hex");

await fetch(`${process.env.GENUKA_BASE_URL}${path}`, {
  method,
  headers: {
    "X-Public-Key": process.env.GENUKA_PUBLIC_KEY!,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json",
  },
  body, // exactly the string you signed
});

Send exactly the body you signed: re-serialising the object afterwards can change the bytes and break the signature. Every authentication failure returns 401 with {"message": "Unauthenticated."}.

Secret Rotation

If you need to rotate a compromised or aging key, go to API Keys.

Rotation replaces the secret_key immediately: the old one stops working at once, and the public_key does not change. Prepare the rollout of the new key before you click.

The recommended flow is:

  1. Reveal or generate the new secret_key
  2. Update backend environment variables or your secrets manager
  3. Restart affected services
  4. Verify payment, payout, and webhook flows

Operational rule

Treat secret rotation as a deployment event. Update the receiving backend, restart affected services, and verify webhook or payment flows immediately after rotation.

Example Authenticated API Call

Once you have retrieved the current secret_key from the dashboard, use it in backend API requests:

Authenticated Request
curl -X GET "https://api-pay.genuka.com/api/v1/payments" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE"

Environment Discipline

Keep your authentication workflow strict:

  • use separate credentials per environment
  • never send live traffic with sandbox credentials
  • never mix sandbox webhook receivers with live business flows

Recommendations

How is this guide?

Last updated on