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.
https://sandbox.dola-pay.com/api/v12Numé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 test | Pays | Opérateur(s) | Résultat simulé | Comportement |
|---|---|---|---|---|
| 22900000001 | 🇧🇯 Bénin | Orange / MTN / MOOV | success | Simule un paiement réussi instantanément. |
| 22500000001 | 🇨🇮 Côte d'Ivoire | Orange / MTN / Wave | success | Simule un paiement réussi instantanément. |
| 22100000001 | 🇬🇳 Guinée | Orange / MTN | success | Simule un paiement réussi instantanément. |
| 22100000002 | 🇬🇳 Guinée | Orange / MTN | failed | Simule un échec de paiement (fonds insuffisants). |
| 22100000003 | 🇬🇳 Guinée | Orange / MTN | pending | Simule une transaction en attente (timeout USSD). |
| 22700000001 | 🇬🇼 Guinée-Bissau | MTN | success | Simule un paiement réussi instantanément. |
| 22100000001 | 🇲🇱 Mali | Orange / Wave | success | Simule un paiement réussi instantanément. |
| 22100000001 | 🇸🇳 Sénégal | Orange / Wave / Free | success | Simule un paiement réussi instantanément. |
| 22800000001 | 🇳🇪 Niger | Orange / Airtel | success | Simule un paiement réussi instantanément. |
| 22600000001 | 🇧🇫 Burkina Faso | Orange / Moov | redirect | Retourne une redirect_url de test (portail de paiement simulé). |
| 24000000001 | 🇨🇬 Congo (Brazza) | MTN / Airtel | success | Simule un paiement réussi instantanément. |
| 99900000099 | 🌍 Tous pays | Tous opérateurs | failed | Force 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".
// 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).
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 webhook5Recevoir 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_.
✓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.
