Quick Start

Créez votre premier paiement, vérifiez le flux de statut, et préparez-vous à l'utilisation de webhooks en production.

Introduction

Ce guide vous guide à travers le chemin d'intégration Genuka Pay le plus court et crédible :

récupérer votre clé secrète

créer un paiement

vérifier le statut résultant

configurer un endpoint webhook

préparer l'intégration pour la production

Obtenir les credentials

Récupérez et gérez votre clé secrète d'application depuis le dashboard.

Créer un paiement

Commencez avec une requête de paiement minimale en mode sandbox.

Suivre le statut

Validez comment votre backend observera les changements d'état des transactions.

Configurer les webhooks

Remplacez le polling en production par la livraison d'événements asynchrones.

Étape 1 : Récupérer votre clé secrète

Commencez dans le dashboard, pas avec un endpoint API brut.

Ouvrez la page API Keys depuis le dashboard.

De là, votre équipe peut :

révéler la secret_key courante

copier les credentials de manière sécurisée

renouveler la clé si nécessaire

inspecter l'historique récent de rotation

Important

Stockez la secret_key côté serveur uniquement. Ne l'enrobez jamais dans du code navigateur, des applications mobiles ou des dépôts publics.

Étape 2 : Créer votre premier paiement

Créer un paiement

curl -X POST "{{BASE_URL}}/api/v1/payments" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XAF",
    "payer_phone": "677001122",
    "external_id": "order_10001",
    "metadata": {
      "description": "Abonnement premium"
    }
  }'

Si operator_code est omis, le backend peut tenter de le détecter à partir du numéro du payeur si possible.

Exemple de réponse

Réponse de paiement

{
  "data": {
    "id": "01HR...",
    "amount": 1000,
    "currency": "XAF",
    "type": "PAYIN",
    "track_id": "TRX_01HR...",
    "status": "PENDING",
    "operator_code": "MTN_CM",
    "payer_phone": "677001122",
    "external_id": "order_10001",
    "metadata": {
      "description": "Abonnement premium"
    },
    "created_at": "2026-04-01T10:00:00Z"
  }
}

Étape 3 : Vérifier le statut

Récupérer le dernier statut du paiement

curl -X GET "{{BASE_URL}}/api/v1/payments/status/TRX_01HR..." \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE"

Champs typiques renvoyés :

transaction_id - identifiant unique de la transaction

track_id - ID de suivi pour le client

status - statut actuel (PENDING, SUCCESS, FAILED)

provider_status - statut opérateur

amount - montant demandé

currency - devise (XAF, XOF, etc.)

updated_at - dernière mise à jour

Étape 4 : Configurer les webhooks

Ne vous fiez pas uniquement au polling en production. Dans Genuka Pay, les webhooks se configurent via la page Webhooks du dashboard.

Flux principal :

créer un endpoint

choisir les événements

activer ou désactiver l'endpoint

régénérer le secret si nécessaire

L'API reste disponible pour l'automatisation :

curl -X POST "{{BASE_URL}}/api/v1/webhook-endpoints" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend de production",
    "target_url": "https://merchant.example.com/webhooks/genuka",
    "events": ["transaction.success", "transaction.failed"],
    "is_active": true
  }'

Recommandation production

En production, considérez la livraison webhook comme la source de vérité pour les changements de statut finaux. Le polling doit servir de mécanisme de récupération ou de réconciliation.

Étape 5 : Préparer le lancement en production

Avant d'envoyer du trafic réel :

✅ complétez votre KYC

✅ vérifiez les devises et zones supportées

✅ stockez et renouvelez votre clé de manière sécurisée

✅ configurez et validez vos webhooks depuis le dashboard

✅ testez avec de petits montants

Consultez la Checklist de lancement pour les exigences complètes.

Introduction

Obtenir les credentials

Créer un paiement

Suivre le statut

Configurer les webhooks

Étape 1 : Récupérer votre clé secrète

Étape 2 : Créer votre premier paiement

Exemple de réponse

Étape 3 : Vérifier le statut

Étape 4 : Configurer les webhooks

Étape 5 : Préparer le lancement en production

Étapes suivantes

Authentification

Paiements

Webhooks

KYC et lancement

On this page