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 operational resource families: application credentials, payments, payouts, webhooks, and KYC.

Base URL

Base URL
{{BASE_URL}}/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.

Application

Inspect your current application and rotate its active secret key.

Payments

Initiate payins and monitor transaction lifecycle status.

Payouts

Disburse funds using stored methods or direct recipient information.

Webhooks

Configure endpoint subscriptions and receive asynchronous events.

KYC

Manage compliance workflows, completeness, and operational limits.

Main Resource Families

Application

  • GET /application
  • POST /application/rotate

Payments

  • GET /payments
  • POST /payments
  • GET /payments/status/{track_id}

Payouts

  • GET /payouts
  • POST /payouts
  • GET /payouts/{id}
  • POST /payouts/{id}/cancel

Webhook Endpoints

  • GET /webhook-endpoints
  • POST /webhook-endpoints
  • GET /webhook-endpoints/{id}
  • PUT /webhook-endpoints/{id}
  • DELETE /webhook-endpoints/{id}
  • POST /webhook-endpoints/{id}/regenerate-secret

KYC

  • GET /kyc/submission
  • POST /kyc/submission
  • POST /kyc/submission/documents
  • PUT /kyc/submission/documents
  • DELETE /kyc/submission/documents
  • POST /kyc/submission/submit
  • POST /kyc/submission/unlock
  • GET /kyc/limits

Response Shape

Many successful responses follow a data envelope:

Typical Success Envelope
{
  "data": {},
  "message": "Operation successful"
}

Validation failures and business errors usually look like:

Typical Error Envelope
{
  "message": "Validation failed",
  "errors": {
    "field": ["Error message"]
  }
}

Operational Rules

  • use explicit ISO currency codes such as XAF and XOF
  • treat payments and payouts as asynchronous operations
  • prefer webhooks over polling in production
  • include valid HMAC headers on authenticated routes
  • treat KYC state and current limits as operational gating conditions

First Endpoints to Learn

Authentication

Learn how credentials and environments are expected to behave.

Payments API

Start with collections if your integration begins with customer payments.

Webhooks

Design for asynchronous event delivery from the start.

How is this guide?

Authentication

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

Payments API

Initiate payins, retrieve transaction status, and model collection flows safely.

On this page

IntroductionBase URLRequired HeadersMain Resource FamiliesApplicationPaymentsPayoutsWebhook EndpointsKYCResponse ShapeOperational RulesFirst Endpoints to Learn