DolaPay
DolaPay Developers

Environnement Sandbox

L'environnement Sandbox (ou "Mode Test") vous permet de tester votre intégration DolaPay de bout en bout — encaissements, décaissements et webhooks — sans utiliser de vrais fonds et sans impacter votre compte de production.

Clés de test

Commencent par dp_test_. À créer dans votre Sandbox Dashboard.

Numéros de test

Utilisez les numéros réservés de ce guide pour simuler succès, échec ou redirection.

100% Isolé

Aucune donnée de test n'apparaît dans votre espace Live ou dans l'admin DolaPay.

1Obtenir une clé API de test

Connectez-vous à votre Sandbox Dashboard (accessible via le menu de votre compte), puis allez dans Clés API pour générer une clé commençant par dp_test_.... Cette clé ne fonctionnera que sur l'URL Sandbox.

URL de base Sandbox
https://sandbox.dola-pay.com/api/v1

2Numéros de téléphone de test

En mode Sandbox, aucune validation USSD réelle n'a lieu. Le résultat de la transaction est déterminé par le numéro de téléphone que vous envoyez. Utilisez les numéros ci-dessous pour simuler les différents scénarios.

Numéro de testPaysOpérateur(s)Résultat simuléComportement
22900000001🇧🇯 BéninOrange / MTN / MOOV successSimule un paiement réussi instantanément.
22500000001🇨🇮 Côte d'IvoireOrange / MTN / Wave successSimule un paiement réussi instantanément.
22100000001🇬🇳 GuinéeOrange / MTN successSimule un paiement réussi instantanément.
22100000002🇬🇳 GuinéeOrange / MTN failedSimule un échec de paiement (fonds insuffisants).
22100000003🇬🇳 GuinéeOrange / MTN pendingSimule une transaction en attente (timeout USSD).
22700000001🇬🇼 Guinée-BissauMTN successSimule un paiement réussi instantanément.
22100000001🇲🇱 MaliOrange / Wave successSimule un paiement réussi instantanément.
22100000001🇸🇳 SénégalOrange / Wave / Free successSimule un paiement réussi instantanément.
22800000001🇳🇪 NigerOrange / Airtel successSimule un paiement réussi instantanément.
22600000001🇧🇫 Burkina FasoOrange / Moov redirectRetourne une redirect_url de test (portail de paiement simulé).
24000000001🇨🇬 Congo (Brazza)MTN / Airtel successSimule un paiement réussi instantanément.
99900000099🌍 Tous paysTous opérateurs failedForce toujours un échec. Utile pour tester la gestion des erreurs.

Important : Ces numéros fonctionnent uniquement en mode Sandbox (clé dp_test_). En production (clé dp_live_), ces numéros seront traités comme de vrais numéros clients.

3Tester un encaissement (Pay-in)

Utilisez l'endpoint /charges avec votre clé de test et un numéro de test. La transaction apparaîtra dans votre Sandbox Dashboard sous "Transactions".

javascript
// En mode Sandbox, deux changements sont nécessaires :
// 1. Utilisez votre clé de test (dp_test_...)
// 2. Pointez vers l'URL Sandbox

const SANDBOX_URL = "https://sandbox.dola-pay.com/api/v1";
const TEST_KEY = "dp_test_votre_cle_de_test";

const response = await fetch(`${SANDBOX_URL}/charges`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TEST_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 5000,
    currency: "XOF",
    provider: "Orange",
    customer_phone: "22900000001", // Numéro de test → retourne "success" immédiatement
    description: "Test paiement sandbox"
  })
});
const data = await response.json();
console.log(data.status); // "success" (immédiat, pas de vraie validation USSD)

4Tester un décaissement (Payout)

Utilisez l'endpoint /payouts avec un numéro de test. Le décaissement passera en processing puis en success (simulé via Webhook).

javascript
const response = await fetch("https://sandbox.dola-pay.com/api/v1/payouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer dp_test_votre_cle_de_test",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 10000,
    currency: "XOF",
    provider: "MTN",
    recipient_phone: "22900000002", // Numéro de test → simule un décaissement réussi
    reference: "TEST_PAYOUT_001"
  })
});
const data = await response.json();
console.log(data.status); // "processing" → passera à "success" via webhook

5Recevoir des Webhooks en mode test

Configurez une URL de Webhook dans la section Webhooks de votre Sandbox Dashboard. Les événements de test vous seront notifiés sur cette URL avec un secret de signature commençant par whsec_test_.

Astuce : Utilisez webhook.site ou smee.io pour recevoir et inspecter vos webhooks de test sans avoir besoin d'un serveur public.
Les webhooks de test sont totalement séparés des webhooks Live — ils n'interfèrent jamais avec votre intégration de production.

Passer en Production

Une fois vos tests concluants, la migration vers la production se fait en 2 étapes simples :

Remplacez la clé API

Changez dp_test_... par votre clé Live dp_live_... (générée dans le Dashboard Live).

Changez l'URL de base

Remplacez sandbox.dola-pay.com/v1 par api.dola-pay.com/v1.

C'est tout ! Aucun changement de logique n'est nécessaire. Les formats de requêtes et de réponses sont identiques entre le Sandbox et la Production.