Documentation API
Intégrez les paiements Mobile Money dans votre application en quelques minutes. Inscription gratuite, commission transparente de 10%.
Démarrage Rapide
Acceptez les paiements Mobile Money en 3 étapes et 5 minutes.
JOboost-Cash fonctionne avec un règlement unique en USD pour tous les marchands, quel que soit leur pays :
- Votre solde marchand est toujours en USD ($) — c'est la devise de référence, elle ne change pas.
- Vos clients paient dans leur devise locale (CDF, XAF, XOF, KES, NGN, etc.) — vous passez la devise du client via le paramètre
currency. - La conversion est automatique — le montant payé par le client est converti en USD au taux du jour et crédité sur votre solde.
- Retraits en USD — vous retirez votre solde en USD.
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.
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
| Étape | Action | API utilisée |
|---|---|---|
| 1 | L'utilisateur remplit le formulaire et clique sur "Payer" | — |
| 2 | Le script appelle POST /pay pour créer le paiement | /pay |
| 3 | L'URL checkout est construite avec les checkout_params | — |
| 4 | Le checkout s'ouvre en iframe overlay | checkout iframe |
| 5 | À la réception de joboost-cash-success, le paiement est confirmé | /confirm/{id} |
| 6 | Polling de secours vérifie le statut toutes les 5s | /verify/{id} |
| 7 | Message de succès ou d'erreur affiché | — |
Authentification
Chaque requête doit inclure votre clé API dans le header Authorization :
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
| Type de clé | Préfixe | Usage |
|---|---|---|
| Secrète Live | sk_live_ | Requêtes côté serveur (production) |
| Secrète Test | sk_test_ | Requêtes côté serveur (test) |
| Publique Live | pk_live_ | Côté client (formulaires) |
| Publique Test | pk_test_ | Côté client (test) |
sk_) côté client ! Utilisez les clés publiques (pk_) pour le frontend.
Initier un Paiement
Paramètres du corps (JSON)
| Paramètre | Type | Requis | Description |
|---|---|---|---|
amount | number | ✅ | Montant à payer (ex: 5000) |
phone | string | ✅ | Numéro du client (ex: "0999999999", "+243999999999") |
currency | string | ❌ | Utilisez 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 |
description | string | ❌ | Description du paiement |
reference | string | ❌ | Votre référence interne (ex: "CMD-001") |
callback_url | string | ❌ | URL de notification webhook spécifique |
customer_name | string | ❌ | Nom du client |
customer_email | string | ❌ | Email du client |
metadata | object | ❌ | Donné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."
}
}
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
| Message | Description |
|---|---|
joboost-cash-ready | Le formulaire de paiement est chargé et prêt |
joboost-cash-success | Le client a payé avec succès → appelez POST /confirm/{id} |
joboost-cash-close | Le client a fermé le formulaire |
{ type: 'joboost-cash-error', message: '...' } | Erreur pendant le paiement |
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.
// 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
{
"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
| Statut | Description |
|---|---|
| pending | En attente — le paiement vient d'être créé |
| processing | En cours — le client a reçu la demande USSD |
| success | Réussi — l'argent est sur votre solde |
| failed | Échoué — refusé ou erreur |
| expired | Expiré — 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énement | Description |
|---|---|
payment.success | Le paiement a été confirmé avec succès |
payment.processing | Le paiement est en cours de traitement |
payment.failed | Le paiement a échoué |
payment.expired | Le 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)
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
Filtres optionnels (query params)
| Paramètre | Type | Description |
|---|---|---|
page | number | Numéro de page (défaut: 1) |
per_page | number | Résultats par page (défaut: 20, max: 100) |
type | string | credit, debit, ou fee |
from | string | Date début — YYYY-MM-DD |
to | string | Date fin — YYYY-MM-DD |
Devises & Pays
JOboost-Cash supporte 14 devises de paiement client et 17 pays.
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
Franc Congolais
Dollar US
Euro
Livre Sterling
Franc CFA (CEMAC)
Franc CFA (UEMOA)
Shilling Kenyan
Cedi Ghanéen
Naira Nigérian
Franc Rwandais
Shilling Ougandais
Shilling Tanzanien
Kwacha Zambien
Leone Sierra-Léonais
Pays → Devise par défaut
| Pays | Code | Devise | Méthodes de paiement |
|---|---|---|---|
| 🇨🇩 RD Congo | CD | CDF, USD | M-Pesa, Orange Money, Airtel Money |
| 🇨🇬 Congo Brazza | CG | XAF | Airtel Money, MTN MoMo |
| 🇨🇲 Cameroun | CM | XAF | Orange Money, MTN MoMo |
| 🇨🇮 Côte d'Ivoire | CI | XOF | Orange Money, MTN MoMo, Wave |
| 🇸🇳 Sénégal | SN | XOF | Orange Money, Wave, Free Money |
| 🇰🇪 Kenya | KE | KES | M-Pesa, Airtel Money |
| 🇬🇭 Ghana | GH | GHS | MTN MoMo, Vodafone Cash, AirtelTigo |
| 🇳🇬 Nigeria | NG | NGN | Bank Transfer, USSD, Carte |
| 🇧🇯 Bénin | BJ | XOF | MTN MoMo, Moov Money |
| 🇧🇫 Burkina Faso | BF | XOF | Orange Money, Moov Money |
| 🇬🇦 Gabon | GA | XAF | Airtel Money, Moov Money |
| 🇷🇼 Rwanda | RW | RWF | MTN MoMo, Airtel Money |
| 🇺🇬 Ouganda | UG | UGX | MTN MoMo, Airtel Money |
| 🇹🇿 Tanzanie | TZ | TZS | M-Pesa, Airtel Money, Tigo Pesa |
| 🇿🇲 Zambie | ZM | ZMW | MTN MoMo, Airtel Money |
| 🇸🇱 Sierra Leone | SL | SLL | Orange Money, Africell Money |
| 🌍 International | INTL | USD, EUR, GBP | Visa, Mastercard |
Codes d'Erreur
| HTTP | Code | Description |
|---|---|---|
| 400 | invalid_json | Le corps de la requête n'est pas du JSON valide |
| 401 | auth_required | Header Authorization manquant |
| 401 | invalid_api_key | Clé API invalide ou expirée |
| 403 | account_disabled | Compte marchand désactivé |
| 404 | payment_not_found | Paiement introuvable |
| 404 | not_found | Route inexistante |
| 422 | validation_error | Données invalides (champ manquant, format incorrect) |
| 422 | amount_too_low | Montant inférieur au minimum autorisé |
| 422 | amount_too_high | Montant supérieur au maximum autorisé |
| 422 | insufficient_balance | Solde insuffisant pour le retrait |
| 422 | unsupported_currency | Devise non supportée |
| 429 | rate_limited | Trop de requêtes (100/minute) |
| 500 | server_error | Erreur serveur interne |
Format d'erreur
{
"success": false,
"error": {
"code": "validation_error",
"message": "Le champ 'amount' est obligatoire"
}
}
Limites
Limites de paiement par devise
| Devise | Minimum | Maximum |
|---|---|---|
CDF | 500 CDF | 5 000 000 CDF |
USD | $1 | $2 000 |
EUR | €1 | €2 000 |
GBP | £1 | £2 000 |
XAF | 100 XAF | 2 000 000 XAF |
XOF | 100 XOF | 2 000 000 XOF |
KES | 50 KES | 500 000 KES |
GHS | 1 GHS | 50 000 GHS |
NGN | 100 NGN | 5 000 000 NGN |
RWF | 500 RWF | 5 000 000 RWF |
UGX | 1 000 UGX | 10 000 000 UGX |
TZS | 500 TZS | 10 000 000 TZS |
ZMW | 5 ZMW | 100 000 ZMW |
SLL | 5 000 SLL | 50 000 000 SLL |
Limites générales
| Paramètre | Valeur |
|---|---|
| Expiration paiement | 30 minutes |
| Rate limit API | 100 requêtes / minute |
| Taille payload max | 1 MB |
| Délai retrait | 24 à 48 heures |