Logo GenukaGenuka Pay
API Reference

API Overview

Understand the structure of the Genuka Pay API, its resources, and its operational conventions.

Introduction

The Genuka Pay API is a JSON-based REST API organized around a few resource families: payments, hosted checkout, payouts, webhook endpoints, operator coverage and subscriptions.

Base URL

Base URL
https://api-pay.genuka.com/api/v1

Required Headers

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

The signature is computed with your application secret_key. Prefer the official SDKs when possible.

Response Language

Validation errors and most business error messages are available in French and English. Some messages are still returned in English only, including authentication errors, context errors (environment, application), and generic server errors. Rely on the HTTP status and the error fields, not on the message text.

Pick the language with the Accept-Language header:

Set the Language With a Header
Accept-Language: en
  • Standard values are accepted, weights included: fr-FR,fr;q=0.9,en;q=0.8 resolves to fr.
  • A regional variant is reduced to its language: fr-CM resolves to fr, en-US to en.
  • A language weighted q=0 is treated as refused.
  • An unsupported language, or *, is ignored without an error.

If you cannot control that header, pass the language in a cookie:

Set the Language With a Cookie
Cookie: language=en

The cookie is only used when the header is missing, is *, or names no supported language. The API reads, in this order: the Accept-Language header, then the Accept-Language cookie, then the language cookie. The first value naming a supported language wins. If none does, the API answers in its default language.

The official SDKs do not send this header. To pick a language with them, pass a custom fetch (TypeScript) or a custom HttpTransport (PHP) that adds it:

Set the Language With the TypeScript SDK
const genuka = new GenukaClient({
  publicKey: process.env.GENUKA_PUBLIC_KEY!,
  secretKey: process.env.GENUKA_SECRET_KEY!,
  fetch: (url, init) =>
    fetch(url, {
      ...init,
      headers: { ...(init?.headers as Record<string, string>), "Accept-Language": "en" },
    }),
});

Endpoints Available with an API Key

Every endpoint below accepts the HMAC headers (X-Public-Key, X-Timestamp, X-Signature). Paths are relative to https://api-pay.genuka.com.

Payments

GET  /api/v1/payments
POST /api/v1/payments
POST /api/v1/payments/quote
GET  /api/v1/payments/status/{track_id}

There is no GET /api/v1/payments/{id} endpoint: a payment is read back by its track_id.

Hosted Checkout

POST /api/v1/checkout
GET  /api/v1/checkout/{token}

Payouts

GET  /api/v1/payouts
POST /api/v1/payouts
GET  /api/v1/payouts/balance
GET  /api/v1/payouts/{id}
POST /api/v1/payouts/{id}/cancel
POST /api/v1/payouts/{id}/retry

Webhook Endpoints

GET    /api/v1/webhook-endpoints
POST   /api/v1/webhook-endpoints
GET    /api/v1/webhook-endpoints/{id}
PUT    /api/v1/webhook-endpoints/{id}
PATCH  /api/v1/webhook-endpoints/{id}
DELETE /api/v1/webhook-endpoints/{id}
POST   /api/v1/webhook-endpoints/{id}/regenerate-secret
POST   /api/v1/webhook-endpoints/{id}/test

Operator Coverage

GET /api/v1/operator-providers

Subscriptions

Products, customers, subscriptions, invoices, subscription links and the customer portal: see Subscriptions.

What Stays in the Dashboard

Application keys (/api/v1/application), KYC (/api/v1/kyc/*), payment methods (/api/v1/payment-methods) and collection links only accept the dashboard session. Called with an API key, they answer 401. Manage them from the dashboard: API keys, KYC, Payment methods.

The whole integration API requires a complete company profile (legal type, country, industry): until it is complete, these endpoints answer 403.

Environments

Each company has two applications, so two key pairs:

environmentKey prefixEffect
SANDBOXpk_test_… / sk_test_…No real money, test numbers
LIVEpk_live_… / sk_live_…Real debits, KYC ceilings enforced

The environment is carried by the key: there is no header to send and no separate URL.

API Conventions

  • Amounts are sent and returned in currency units (1000 = 1,000 XAF), with an explicit ISO code XAF or XOF.
  • Dates are ISO 8601 in UTC (2026-09-19T10:00:00.000000Z). Only the signature's X-Timestamp header is in Unix seconds.
  • Phone numbers are in E.164 format (+237677001122).
  • Identifiers (id, token) are ULIDs.

Tracking IDs

Every payment and payout gets a track_id prefixed by the provider that processes it, followed by a lowercase ULID:

PrefixExample
PX, MV, TM, JK, EKJK-01k7c4t9m2y8x5b3n6q0r1s2t3
GPinternal identifier, when no provider is known yet

Treat the track_id as an opaque string: do not infer anything from its prefix, which can differ from one payment to the next for the same operator.

Response Envelope

A resource is returned under data:

{ "data": { "id": "01k7c4…", "status": "PROCESSING" } }

Some responses add a technical message next to data (for example "payin_fees_quoted"). Lists are also under data.

Errors

{
  "message": "The amount field must be at least 1.",
  "errors": {
    "amount": ["The amount field must be at least 1."]
  }
}

errors is only present on validation errors (422). See Error handling.

Idempotency

POST /api/v1/payments and POST /api/v1/payouts accept an Idempotency-Key header. Without it, your external_id is used as the key. A second request with the same key creates nothing: it returns the existing transaction. The official SDKs send this header through the idempotencyKey option.

HMAC Authentication

Every authenticated request uses HMAC-SHA256:

  1. Concatenate, with no separator: the X-Timestamp value, the uppercase HTTP method, the path with its query string (e.g. /api/v1/payments?per_page=20), then the raw request body (empty string if there is none)
    timestamp + HTTP_METHOD + path_with_query + raw_body
  2. Compute HMAC_SHA256(secret_key, message)
  3. Send the hexadecimal signature as X-Signature

The public key is not part of the signed string: it is only sent in X-Public-Key. The timestamp must be within 5 minutes of server time. An invalid signature, an out-of-window timestamp or an inactive key all produce the same 401 {"message": "Unauthenticated."}.

Use the official SDKs for this logic rather than implementing it by hand.

First Endpoints to Learn

How is this guide?

Last updated on