Introduction
L'API REST de SOCCO PAY permet d'intégrer les paiements Mobile Money (MTN, Orange, Wave, Moov), cartes bancaires (Visa, Mastercard), PayPal et Crypto (USDT, Bitcoin) dans vos applications.
Base URL : https://soccopay.com/api/v1
Toutes les requêtes doivent être faites en HTTPS. Les données sont échangées au format JSON.
Authentification
Chaque requête doit inclure vos clés API dans les en‑têtes :
X-PUBLIC-KEY: votre_clé_publique
X-PRIVATE-KEY: votre_clé_privée
Les clés sont disponibles dans votre tableau de bord SOCCO PAY → API Keys.
Solde du compte
GET
/balance.php
curl -X GET https://soccopay.com/api/v1/balance.php \
-H "X-PUBLIC-KEY: votre_clé_publique" \
-H "X-PRIVATE-KEY: votre_clé_privée"
Réponse
{
"success": true,
"balance": 125000.00,
"locked_balance": 5000.00,
"available_balance": 120000.00,
"currency": "XAF"
}
Liste des transactions
GET
/transactions.php?page=1&limit=10&status=success
curl -X GET "https://soccopay.com/api/v1/transactions.php?page=1&limit=10" \
-H "X-PUBLIC-KEY: ..." \
-H "X-PRIVATE-KEY: ..."
Créer un lien de paiement
POST
/payment-link.php
curl -X POST https://soccopay.com/api/v1/payment-link.php \
-H "X-PUBLIC-KEY: votre_clé_publique" \
-H "X-PRIVATE-KEY: votre_clé_privée" \
-H "Content-Type: application/json" \
-d '{
"title": "Commande #123",
"amount": 5000,
"success_url": "https://monsite.com/success",
"failed_url": "https://monsite.com/error"
}'
Réponse
{
"success": true,
"mode": "production",
"reference": "a1b2c3d4e5f6...",
"payment_url": "https://soccopay.com/pay_link.php?id=a1b2c3d4...",
"amount": 5000,
"currency": "XAF",
"redirect_url": null, // URL Wave si method = wave
"created_at": "2026-06-11 12:00:00"
}
Paiement via Wave NOUVEAU
Wave est un portefeuille mobile disponible en
Côte d'Ivoire (CI), Sénégal (SN) et
Gambie (GM). Contrairement aux autres opérateurs Mobile Money
(push / USSD), Wave fonctionne par redirection externe :
l'API renvoie une URL de paiement vers laquelle vous devez rediriger votre client.
⚡ Fonctionnement :
- Vous envoyez une requête
payin avec network=wave.
- L'API retourne
data.redirect_url (URL Wave).
- Vous redirigez le client vers cette URL (app Wave ou navigateur).
- Le statut final arrive de manière asynchrone via votre webhook.
Pays et réseaux supportés
| Pays |
Code |
Devise |
Réseau |
Workflow |
Frais |
| 🇨🇮 Côte d'Ivoire |
CI |
XOF |
wave |
redirect_url |
7 % |
| 🇸🇳 Sénégal |
SN |
XOF |
wave |
redirect_url |
7 % |
| 🇬🇲 Gambie |
GM |
GMD |
wave |
redirect_url |
7 % |
Endpoint
POST
/merchant.php
Exemple de requête (cURL)
curl -X POST https://soccopay.com/api/v2/merchant.php \
-H "X-PUBLIC-KEY: votre_clé_publique" \
-H "X-PRIVATE-KEY: votre_clé_privée" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"phone": "0708123456",
"country": "CI",
"network": "wave",
"currency": "XOF"
}'
Réponse (succès)
{
"success": true,
"status": "pending",
"message": "⏳ Paiement en cours de validation...",
"data": {
"reference": "SP20260611123456ABCD",
"amount": 5000,
"fee_percent": 7,
"fee_amount": 350,
"net_amount": 4650,
"currency": "XOF",
"country": "CI",
"network": "wave",
"phone": "0708123456",
"transaction_id": "CI-66F3A1B2C4D5E1727258400A1B2",
"status": "Pending",
"redirect_url": "https://pay.wave.com/c/cos-xxxxxxxx?a=5000&c=XOF&m=SoccoPay",
"action_required": true,
"action_type": "redirect",
"instruction": "Redirection vers Wave pour finaliser le paiement."
}
}
Intégration côté client (PHP)
Redirigez automatiquement l'utilisateur vers redirect_url dès qu'elle est présente :
<?php
$response = json_decode($apiResponse, true);
$redirectUrl = $response['data']['redirect_url'] ?? null;
if (!empty($redirectUrl)) {
// Redirection immédiate vers Wave
// (app Wave si installée, sinon navigateur/onglet)
header('Location: ' . $redirectUrl);
exit;
}
?>
Intégration côté client (JavaScript)
Pour ouvrir Wave dans l'app si elle est installée, avec fallback navigateur :
const res = await fetch('/api/v2/merchant.php', {
method: 'POST',
headers: {
'X-PUBLIC-KEY': publicKey,
'X-PRIVATE-KEY': privateKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 5000,
phone: '0708123456',
country: 'CI',
network: 'wave',
currency: 'XOF'
})
});
const data = await res.json();
if (data.success && data.data.redirect_url) {
// Tente l'ouverture dans l'app Wave
window.location.href = data.data.redirect_url;
// Fallback : nouvel onglet si navigation bloquée
setTimeout(() => {
window.open(data.data.redirect_url, '_blank', 'noopener');
}, 900);
}
Statut final (webhook asynchrone)
Une fois le paiement Wave finalisé, SOCCO PAY vous envoie un webhook POST
sur votre URL configurée, avec les données suivantes :
{
"event": "payment.success",
"reference": "SP20260611123456ABCD",
"amount": 5000,
"fee_percent": 7,
"fee_amount": 350,
"net_amount": 4650,
"currency": "XOF",
"country": "CI",
"network": "wave",
"customer_phone": "0708123456",
"provider_reference": "CI-66F3A1B2C4D5E1727258400A1B2",
"status": "Successful",
"message": "Paiement réussi.",
"timestamp": "2026-06-11 12:00:00"
}
🧪 Sandbox Wave :
utilisez le pays CI et le réseau wave en mode test.
L'URL redirect_url pointera vers l'environnement sandbox de Wave.
Vérifier une transaction
GET
/verify-transaction.php?reference=SP123456
curl -X GET "https://soccopay.com/api/v1/verify-transaction.php?reference=SP20260611123456" \
-H "X-PUBLIC-KEY: ..." \
-H "X-PRIVATE-KEY: ..."
Compte marchand
GET
/account.php
curl -X GET https://soccopay.com/api/v1/account.php \
-H "X-PUBLIC-KEY: ..." \
-H "X-PRIVATE-KEY: ..."
Retrait (API)
POST
/withdraw.php
curl -X POST https://soccopay.com/api/v1/withdraw.php \
-H "X-PUBLIC-KEY: ..." \
-H "X-PRIVATE-KEY: ..." \
-H "Content-Type: application/json" \
-d '{"amount":10000,"phone":"2376XXXXXXXX","network":"mtn_cm","pin":"1234"}'
Webhooks
Configurez une URL de notification dans votre tableau de bord. SOCCO PAY enverra une requête POST avec la signature X-Signature.
// Vérification en PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, 'VOTRE_SECRET_WEBHOOK');
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit;
}
Mode Sandbox (test)
Numéros de test pour le webhook :
| Numéro | Résultat |
|---|
670000001 | success |
670000002 | failed |
670000003 | pending |
670000004 | insufficient_funds |
670000005 | invalid_number |
670000006 | cancelled |
🧪 Webhook de test : POST /api/v1/webhook-test.php
Codes d'erreur
| Code | Signification |
|---|
401 | Clés API manquantes ou invalides |
403 | Accès interdit (KYC requis) |
422 | Données invalides |
404 | Ressource non trouvée |
500 | Erreur serveur |
Exemple complet d'intégration (PHP)
<?php
$publicKey = 'votre_clé_publique';
$privateKey = 'votre_clé_privée';
$ch = curl_init('https://soccopay.com/api/v1/payment-link.php');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Commande #1001',
'amount' => 10000,
'success_url' => 'https://monsite.com/merci',
'failed_url' => 'https://monsite.com/erreur'
]),
CURLOPT_HTTPHEADER => [
'X-PUBLIC-KEY: ' . $publicKey,
'X-PRIVATE-KEY: ' . $privateKey,
'Content-Type: application/json'
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
$paymentUrl = $data['payment_url'];
// Rediriger l'utilisateur vers $paymentUrl
header('Location: ' . $paymentUrl);
?>
Une fois le paiement terminé, l'utilisateur sera redirigé vers success_url ou failed_url avec les paramètres reference et status.