Sandbox - Neka Paie

Vue d'ensemble

L'environnement sandbox reproduit le parcours Orange Money sans mouvement de fonds réels. Il vous permet de :

Tester l'authentification HMAC sans risque
Forcer différents statuts (SUCCESS, FAILED, EXPIRED) via des MSISDN spécifiques
Recevoir des webhooks de test sur votre URL configurée
Valider votre intégration avant la mise en production

Le sandbox reproduit un paiement en deux étapes. En production, aucun téléphone n'est débité sur la réponse 202 : le client reçoit un push USSD et doit le confirmer avec son code secret. Testez donc explicitement l'état d'attente (PENDING) et le cas « client qui ne confirme jamais », pas seulement le chemin nominal.

Caractéristiques

Base URL	`https://nekapaie.com/api/v1`
Préfixe API Key	`nk_test_*`
Frais	Aucun
Limite	Illimité, sans KYC
Persistance	Transactions stockées 30 jours

Numéros de test

Utilisez ces MSISDN pour forcer un comportement précis lors de vos tests :

MSISDN	Comportement attendu	Statut final
`+22376123456`	Paiement validé immédiatement par le client	SUCCESS
`+22376111111`	Solde insuffisant côté client	FAILED
`+22376222222`	Client refuse le paiement (annulation USSD)	FAILED
`+22376333333`	Aucune réponse client (timeout 5 min)	EXPIRED
`+22376444444`	Reste en PENDING pendant 30 sec puis SUCCESS	SUCCESS
`+22376555555`	Erreur opérateur (HTTP 503 simulé)	PENDING → FAILED
`+22376987654`	Bénéficiaire valide pour Cash-Out	SUCCESS

Bonus : tout autre numéro +22376xxxxxxxx aboutit à un SUCCESS aléatoire après 5-15 secondes.

Scénarios prêts à tester

Scénario 1 : Paiement réussi

JSONPOST /api/v1/payments/cashin
{
  "merchant_order_id": "test_success_001",
  "amount": 50000,
  "customer_msisdn": "+22376123456",
  "country_code": "ML"
}
→ 202 PENDING → webhook 5s plus tard avec status SUCCESS

Scénario 2 : Solde insuffisant

JSONPOST /api/v1/payments/cashin
{
  "merchant_order_id": "test_failed_001",
  "amount": 50000,
  "customer_msisdn": "+22376111111",
  "country_code": "ML"
}
→ 202 PENDING → webhook avec status FAILED, failure_reason "Solde insuffisant"

Scénario 3 : Idempotence

JSON# Premier appel
POST /payments/cashin {"merchant_order_id": "test_idempo_001", ...}
→ 202 transaction_id: abc-123

# Même appel rejoué
POST /payments/cashin {"merchant_order_id": "test_idempo_001", ...}
→ 202 transaction_id: abc-123  (la même !)

Scénario 4 : Cash-Out

JSONPOST /api/v1/payments/cashout
{
  "merchant_order_id": "payout_001",
  "amount": 100000,
  "beneficiary_msisdn": "+22376987654",
  "currency": "XOF",
  "reason": "Test sandbox"
}
→ 202 PENDING → webhook SUCCESS

Webhooks en sandbox

Pour tester votre handler webhook localement :

Option A : Tunneling avec ngrok

BASH"># Démarrer un tunnel HTTPS vers votre serveur local
ngrok http 3000

# Copier l'URL forwarding (ex: https://abc123.ngrok.io)
# Configurer dans votre espace marchand :
# Webhook URL = https://abc123.ngrok.io/webhooks/nekapay

Option B : Simulateur intégré

Depuis votre espace marchand → ouvrir une transaction → bouton « Renvoyer le webhook ».

Limites du sandbox

Pas de mouvement réel — les soldes affichés sont simulés.
Données purgées tous les 30 jours — n'utilisez pas pour de la production.
Latences artificielles — les webhooks arrivent typiquement en 3 à 15 secondes.
Filiales — seul Mali (ML) est actif en démo. Les autres seront ouvertes progressivement.