Validez votre intégration en sécurité avant d’activer le trafic de production.

Mode test

Le mode test sert à valider les flux backend, l’idempotence, la réception webhook et la réconciliation avant du trafic live.

Headers requis

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Ce qu’il faut valider

initiation de paiement

initiation de payout

réception des webhooks

gestion des retries

réconciliation via track_id

mapping interne via external_id

le retour du payeur sur votre return_url / cancel_url, pour les opérateurs à redirection

Checklist suggérée

initier un paiement avec un petit montant

stocker le track_id

vérifier la livraison webhook

comparer le webhook avec GET /payments/status/{track_id}

tester les échecs et retries

confirmer votre état KYC avant le live

Numéros de test

En sandbox, l'issue du paiement est déterminée par le numéro du payeur. Aucun vrai débit, aucune notification sur un vrai téléphone.

Numéro	Opérateur	Résultat
`+237670000001`	MTN Cameroun	`SUCCESS`
`+237670000002`	MTN Cameroun	`FAILED`
`+237670000003`	MTN Cameroun	reste en `PROCESSING`
`+237670000004`	MTN Cameroun	échec, solde insuffisant
`+237690000001`	Orange Cameroun	`SUCCESS`
`+237690000002`	Orange Cameroun	`FAILED`
`+237690000003`	Orange Cameroun	reste en `PROCESSING`
`+237690000099`	Orange Cameroun	échec, solde insuffisant
`+2250700000001`	Côte d'Ivoire	`SUCCESS`
`+2250700000002`	Côte d'Ivoire	`FAILED`
`+2250700000003`	Côte d'Ivoire	reste en `PROCESSING`
`+2250700000004`	Côte d'Ivoire	échec, solde insuffisant

Tout autre numéro est refusé en sandbox : c'est voulu, cela évite de croire qu'un flux fonctionne alors qu'il n'a rien simulé.

Opérateurs à redirection : la page de test

Carte bancaire, Orange, Wave et Djamo envoient le payeur sur une page. En sandbox, redirect_url pointe sur une page de test Genuka Pay qui tient le rôle de l'opérateur : deux boutons, Payer et Annuler.

Ce que cela change :

Le paiement ne se règle pas tout seul. Il reste en PROCESSING tant que personne n'a cliqué — comme un vrai paiement Wave, qui attend le payeur.

Payer applique le résultat demandé par votre numéro de test : +2250700000004 échoue toujours en solde insuffisant, il échoue simplement là où un vrai paiement échouerait.

Annuler fait échouer le paiement avec le code PAYMENT_DECLINED.

Dans les deux cas, vous êtes renvoyé sur votre return_url / cancel_url avec status et reference, par exactement le même code qu'en production.

C'est le seul moyen de tester votre URL de retour

Envoyez toujours return_url quand vous testez un opérateur à redirection. Sans elle, la page de test vous renvoie sur la page d'accueil de Genuka Pay — ce qui est précisément ce que vivrait votre client en live.

Exemple

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": 100,
    "currency": "XAF",
    "payer_phone": "+237670000001",
    "external_id": "test_payment_001"
  }'

Passage en live

obtenir un KYC approuvé

confirmer les plafonds via GET /kyc/limits

configurer les webhooks de production

faire tourner les credentials si nécessaire

démarrer avec de petits montants

Mode test

On this page