Documentation API

Intégrez les paiements Mobile Money dans votre application en quelques minutes. Inscription gratuite, commission transparente de 10%.

17 pays 14 devises Inscription gratuite HTTPS/TLS REST API

Démarrage Rapide

Acceptez les paiements Mobile Money en 3 étapes et 5 minutes.

💱 Comprendre le système de devises

JOboost-Cash fonctionne avec un règlement unique en USD pour tous les marchands, quel que soit leur pays :

Exemple : Un client au Congo paie 5 000 CDF (~2.34 $) → après commission de 10%, vous recevez ~2.11 USD sur votre solde. (Taux : 2 135 CDF = 1 $)

Étape 1 — Créez un compte

Inscrivez-vous gratuitement sur le dashboard et récupérez vos clés API (test + live).

Étape 2 — Initiez un paiement

const response = await fetch('https://api-cash.joboost.org/pay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer VOTRE_CLE_API',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10,
    phone: '0999999999',
    currency: 'USD',
    description: 'Commande #1234'
  })
});

const { data } = await response.json();
console.log(data.payment_id);   // "pay_a1b2c3d4e5f6"
console.log(data.checkout_url); // URL du formulaire de paiement
<?php
// Avec cURL
$ch = curl_init('https://api-cash.joboost.org/pay');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer VOTRE_CLE_API',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount'      => 10,
        'phone'       => '0999999999',
        'currency'    => 'USD',
        'description' => 'Commande #1234'
    ])
]);
$response = json_decode(curl_exec($ch), true);
echo $response['data']['payment_id']; // "pay_a1b2c3d4e5f6"
import requests

r = requests.post('https://api-cash.joboost.org/pay',
    json={
        'amount': 10,
        'phone': '0999999999',
        'currency': 'USD',
        'description': 'Commande #1234'
    },
    headers={'Authorization': 'Bearer VOTRE_CLE_API'}
)
data = r.json()
print(data['data']['payment_id'])  # "pay_a1b2c3d4e5f6"
curl -X POST https://api-cash.joboost.org/pay \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "phone": "0999999999",
    "currency": "USD",
    "description": "Commande #1234"
  }'

Étape 3 — Affichez le checkout et confirmez

// Construire l'URL du checkout avec les paramètres
let checkoutUrl = data.checkout_url;
if (data.checkout_params && !checkoutUrl.includes('?')) {
  checkoutUrl += '?' + new URLSearchParams(data.checkout_params).toString();
}

// Ouvrir en iframe overlay
const iframe = document.createElement('iframe');
iframe.src = checkoutUrl;
document.body.appendChild(iframe);

// Écouter le succès via postMessage
window.addEventListener('message', async (event) => {
  if (event.data === 'joboost-cash-success') {
    // Confirmer le paiement côté API
    await fetch(`https://api-cash.joboost.org/confirm/${data.payment_id}`, {
      method: 'POST',
      headers: { 'Authorization': 'Bearer VOTRE_CLE_API' }
    });
    // 🎉 Paiement réussi ! Le montant est crédité sur votre solde
  }
});

Intégration Express 1 fichier

Copiez ce fichier HTML unique et vous avez un bouton de paiement fonctionnel. Aucune dépendance, aucun build, aucun serveur — juste un fichier .html à ouvrir dans le navigateur. Fonctionne même en local (localhost) pour tester de vrais paiements.

⚡ Copier → Coller → Ça marche ! Remplacez VOTRE_CLE_API par votre clé live (sk_live_...), ouvrez le fichier dans votre navigateur (même en local), et testez un vrai paiement.

🧪 Tester en local — Vous pouvez utiliser vos clés live directement depuis localhost ou en ouvrant le fichier test.html dans votre navigateur. L'API accepte les appels depuis n'importe quelle origine (CORS ouvert). C'est le moyen le plus rapide de valider votre intégration avant de déployer.

Ce que fait ce fichier

ÉtapeActionAPI utilisée
1L'utilisateur remplit le formulaire et clique sur "Payer"
2Le script appelle POST /pay pour créer le paiement/pay
3L'URL checkout est construite avec les checkout_params
4Le checkout s'ouvre en iframe overlaycheckout iframe
5À la réception de joboost-cash-success, le paiement est confirmé/confirm/{id}
6Polling de secours vérifie le statut toutes les 5s/verify/{id}
7Message de succès ou d'erreur affiché
💡 Personnalisez ! Ce fichier est un point de départ. Changez les couleurs, ajoutez vos produits, intégrez-le dans votre site existant. Le code JavaScript fonctionne partout : WordPress, Shopify, HTML statique, React, Vue, etc.

Authentification

Chaque requête doit inclure votre clé API dans le header Authorization :

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Type de cléPréfixeUsage
Secrète Livesk_live_Requêtes côté serveur (production)
Secrète Testsk_test_Requêtes côté serveur (test)
Publique Livepk_live_Côté client (formulaires)
Publique Testpk_test_Côté client (test)
⚠️ Sécurité Ne partagez jamais vos clés secrètes (sk_) côté client ! Utilisez les clés publiques (pk_) pour le frontend.

Initier un Paiement

POST /pay

Paramètres du corps (JSON)

ParamètreTypeRequisDescription
amountnumberMontant à payer (ex: 5000)
phonestringNuméro du client (ex: "0999999999", "+243999999999")
currencystringUtilisez toujours USD (défaut). Le client verra le montant converti dans sa devise locale au checkout. Les devises locales (CDF, XAF, XOF, KES, etc.) sont aussi acceptées si besoin. Voir toutes les devises
descriptionstringDescription du paiement
referencestringVotre référence interne (ex: "CMD-001")
callback_urlstringURL de notification webhook spécifique
customer_namestringNom du client
customer_emailstringEmail du client
metadataobjectDonnées libres (JSON)

Réponse (succès)

{
  "success": true,
  "data": {
    "payment_id": "pay_a1b2c3d4e5f6",
    "amount": 10,
    "amount_charged": 11,
    "fee": 1,
    "net_amount": 9,
    "net_amount_usd": 9,
    "currency": "USD",
    "settlement_currency": "USD",
    "status": "processing",
    "customer_phone": "0999999999",
    "payment_method": null,
    "description": "Commande #1234",
    "reference": null,
    "checkout_url": "https://...",
    "checkout_params": { "...": "..." },
    "expires_at": "2026-03-03T15:30:00",
    "created_at": "2026-03-03T15:00:00",
    "message": "Paiement en cours de traitement. Le client a reçu la demande de confirmation."
  }
}
💡 Comment utiliser currency ?

Le champ currency représente la devise dans laquelle votre client va payer. Vous, en tant que marchand, recevez toujours en USD.

Exemple concret : un client au Congo veut payer 5 000 CDF (soit ~2.34 $) :

{ "amount": 5000, "phone": "0999999999", "currency": "CDF" }
// → Le client paie 5 500 CDF (montant + 10% frais plateforme)
// → 5 000 CDF ≈ 2.34 USD au taux du jour (2 135 CDF = 1 $)
// → Commission marchand 10% : 0.23 USD
// → Vous recevez 2.11 USD net sur votre solde

Mais dans vos codes d'intégration, utilisez toujours "currency": "USD" et un montant en dollars. Le client verra le montant converti dans sa devise locale au moment du checkout. Le même principe s'applique pour toutes les devises (XAF, XOF, KES, NGN, etc.).

Checkout (iframe)

Après avoir initié un paiement, construisez l'URL avec les checkout_params reçus et affichez le formulaire en iframe. Le client choisit sa méthode de paiement (M-Pesa, Orange Money, Carte, etc.) et confirme.

// 1. Construire l'URL complète avec les paramètres
const { checkout_url, checkout_params, payment_id } = data;
let url = checkout_url;
if (checkout_params && !url.includes('?')) {
  url += '?' + new URLSearchParams(checkout_params).toString();
}

// 2. Créer l'overlay iframe
const overlay = document.createElement('div');
overlay.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,0.7);z-index:9999;display:flex;align-items:center;justify-content:center';

const iframe = document.createElement('iframe');
iframe.src = url;
iframe.style.cssText = 'width:420px;height:650px;border:none;border-radius:16px';

overlay.appendChild(iframe);
document.body.appendChild(overlay);

// 3. Écouter le résultat via postMessage
window.addEventListener('message', (event) => {
  if (event.data === 'joboost-cash-ready')   { /* Checkout chargé */ }
  if (event.data === 'joboost-cash-success') { /* Paiement réussi → appeler /confirm */ }
  if (event.data === 'joboost-cash-close')   { overlay.remove(); }
});

Messages postMessage reçus

MessageDescription
joboost-cash-readyLe formulaire de paiement est chargé et prêt
joboost-cash-successLe client a payé avec succès → appelez POST /confirm/{id}
joboost-cash-closeLe client a fermé le formulaire
{ type: 'joboost-cash-error', message: '...' }Erreur pendant le paiement
💡 Conseil Zéro conformité PCI nécessaire ! Le formulaire de paiement est entièrement hébergé sur nos serveurs. Vous n'avez aucune donnée de carte ou de Mobile Money à gérer.

Confirmer un Paiement

Après que le client a complété le paiement via le checkout iframe, appelez cet endpoint pour confirmer et créditer votre solde.

POST /confirm/{payment_id}
// Confirmer après le checkout iframe
const confirm = await fetch(`https://api-cash.joboost.org/confirm/${paymentId}`, {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_CLE_API' }
});

const result = await confirm.json();
// {
//   success: true,
//   data: {
//     payment_id: "pay_a1b2c3d4e5f6",
//     status: "success",
//     net_amount_usd: 9,
//     currency: "USD",
//     settlement_currency: "USD",
//     message: "Paiement confirmé avec succès !"
//   }
// }

Vérifier un Paiement

GET /verify/{payment_id}
{
  "success": true,
  "payment": {
    "payment_id": "pay_a1b2c3d4e5f6",
    "amount": 10,
    "amount_charged": 11,
    "net_amount": 9,
    "net_amount_usd": 9,
    "currency": "USD",
    "settlement_currency": "USD",
    "status": "success",
    "customer_phone": "0999999999",
    "description": "Commande #1234",
    "reference": "CMD-001",
    "payment_method": "mobile_money",
    "created_at": "2026-03-03T14:55:00",
    "completed_at": "2026-03-03T15:02:30",
    "expires_at": "2026-03-03T15:25:00",
    "metadata": {}
  }
}

Statuts possibles

StatutDescription
pendingEn attente — le paiement vient d'être créé
processingEn cours — le client a reçu la demande USSD
successRéussi — l'argent est sur votre solde
failedÉchoué — refusé ou erreur
expiredExpiré — non confirmé dans les 30 min

Webhooks

Quand un paiement change de statut, un POST est envoyé à votre Webhook URL (configurée dans le dashboard).

Payload reçu

{
  "event": "payment.success",
  "payment_id": "pay_a1b2c3d4e5f6",
  "amount": 10,
  "net_amount": 9,
  "net_amount_usd": 9,
  "fee": 1,
  "currency": "USD",
  "settlement_currency": "USD",
  "status": "success",
  "customer_phone": "0999999999",
  "reference": "CMD-001",
  "metadata": {},
  "timestamp": "2026-03-03T15:02:30+02:00"
}

Événements possibles

ÉvénementDescription
payment.successLe paiement a été confirmé avec succès
payment.processingLe paiement est en cours de traitement
payment.failedLe paiement a échoué
payment.expiredLe paiement a expiré (30 min)

Vérifier la signature HMAC

Chaque webhook inclut un header X-JOboost-Signature (HMAC SHA256) pour vérifier l'authenticité :

// PHP — Vérification du webhook
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_JOBOOST_SIGNATURE'];
$expected  = hash_hmac('sha256', $payload, 'VOTRE_WEBHOOK_SECRET');

if (hash_equals($expected, $signature)) {
    // ✅ Webhook authentique
    $data = json_decode($payload, true);
    // Traiter le paiement...
} else {
    http_response_code(401);
    die('Signature invalide');
}

Solde (USD)

GET /balance

Retourne votre solde en USD. Tous les paiements sont automatiquement convertis en USD au taux du jour, quelle que soit la devise d'origine.

{
  "success": true,
  "data": {
    "balance": {
      "balance": 158.42,
      "total_received": 412.50,
      "total_withdrawn": 250.00,
      "total_fees": 4.08,
      "currency": "USD"
    },
    "payments": {
      "total_payments": 42,
      "successful": 38,
      "today_count": 5,
      "total_received": 412.50,
      "reference_currency": "USD"
    }
  }
}

💱 Pourquoi USD uniquement ? — Tous les marchands JOboost-Cash, quel que soit leur pays, ont un solde en USD ($). C'est la devise de référence universelle. Vos clients paient dans leur devise locale (CDF, XAF, KES, NGN, etc.) et le montant est automatiquement converti en USD sur votre solde au taux du jour. Exemple : 5 000 CDF ≈ 2.34 $ (taux : 2 135 CDF = 1 $). Dans vos codes d'intégration, utilisez toujours "currency": "USD" — le client verra le montant dans sa devise locale au checkout.

Transactions

GET /transactions?page=1&per_page=20

Filtres optionnels (query params)

ParamètreTypeDescription
pagenumberNuméro de page (défaut: 1)
per_pagenumberRésultats par page (défaut: 20, max: 100)
typestringcredit, debit, ou fee
fromstringDate début — YYYY-MM-DD
tostringDate fin — YYYY-MM-DD

Devises & Pays

JOboost-Cash supporte 14 devises de paiement client et 17 pays.

💵 Règlement unique en USD

Quel que soit votre pays ou celui de votre client, votre solde marchand est toujours en USD ($). Le paramètre currency dans l'API définit la devise de paiement du client final, pas la vôtre. La conversion vers USD est automatique au taux du jour. Vous n'avez rien à configurer — laissez votre compte en USD et indiquez simplement la devise locale de votre client dans chaque requête de paiement.

Devises de paiement client

CDF
Franc Congolais
USD
Dollar US
EUR
Euro
GBP
Livre Sterling
XAF
Franc CFA (CEMAC)
XOF
Franc CFA (UEMOA)
KES
Shilling Kenyan
GHS
Cedi Ghanéen
NGN
Naira Nigérian
RWF
Franc Rwandais
UGX
Shilling Ougandais
TZS
Shilling Tanzanien
ZMW
Kwacha Zambien
SLL
Leone Sierra-Léonais

Pays → Devise par défaut

PaysCodeDeviseMéthodes de paiement
🇨🇩 RD CongoCDCDF, USDM-Pesa, Orange Money, Airtel Money
🇨🇬 Congo BrazzaCGXAFAirtel Money, MTN MoMo
🇨🇲 CamerounCMXAFOrange Money, MTN MoMo
🇨🇮 Côte d'IvoireCIXOFOrange Money, MTN MoMo, Wave
🇸🇳 SénégalSNXOFOrange Money, Wave, Free Money
🇰🇪 KenyaKEKESM-Pesa, Airtel Money
🇬🇭 GhanaGHGHSMTN MoMo, Vodafone Cash, AirtelTigo
🇳🇬 NigeriaNGNGNBank Transfer, USSD, Carte
🇧🇯 BéninBJXOFMTN MoMo, Moov Money
🇧🇫 Burkina FasoBFXOFOrange Money, Moov Money
🇬🇦 GabonGAXAFAirtel Money, Moov Money
🇷🇼 RwandaRWRWFMTN MoMo, Airtel Money
🇺🇬 OugandaUGUGXMTN MoMo, Airtel Money
🇹🇿 TanzanieTZTZSM-Pesa, Airtel Money, Tigo Pesa
🇿🇲 ZambieZMZMWMTN MoMo, Airtel Money
🇸🇱 Sierra LeoneSLSLLOrange Money, Africell Money
🌍 InternationalINTLUSD, EUR, GBPVisa, Mastercard

Codes d'Erreur

HTTPCodeDescription
400invalid_jsonLe corps de la requête n'est pas du JSON valide
401auth_requiredHeader Authorization manquant
401invalid_api_keyClé API invalide ou expirée
403account_disabledCompte marchand désactivé
404payment_not_foundPaiement introuvable
404not_foundRoute inexistante
422validation_errorDonnées invalides (champ manquant, format incorrect)
422amount_too_lowMontant inférieur au minimum autorisé
422amount_too_highMontant supérieur au maximum autorisé
422insufficient_balanceSolde insuffisant pour le retrait
422unsupported_currencyDevise non supportée
429rate_limitedTrop de requêtes (100/minute)
500server_errorErreur serveur interne

Format d'erreur

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Le champ 'amount' est obligatoire"
  }
}

Limites

Limites de paiement par devise

DeviseMinimumMaximum
CDF500 CDF5 000 000 CDF
USD$1$2 000
EUR€1€2 000
GBP£1£2 000
XAF100 XAF2 000 000 XAF
XOF100 XOF2 000 000 XOF
KES50 KES500 000 KES
GHS1 GHS50 000 GHS
NGN100 NGN5 000 000 NGN
RWF500 RWF5 000 000 RWF
UGX1 000 UGX10 000 000 UGX
TZS500 TZS10 000 000 TZS
ZMW5 ZMW100 000 ZMW
SLL5 000 SLL50 000 000 SLL

Limites générales

ParamètreValeur
Expiration paiement30 minutes
Rate limit API100 requêtes / minute
Taille payload max1 MB
Délai retrait24 à 48 heures