Une seule requête
Une requête envoie la demande de paiement sur le téléphone de votre client. Vous suivez le résultat par webhook ou par interrogation du statut.
Faites des affaires avec l'Afrique : encaissez par mobile money depuis votre site ou votre application. Hostafri conçoit aussi vos sites, applications et plateformes sur mesure.
Une requête envoie la demande de paiement sur le téléphone de votre client. Vous suivez le résultat par webhook ou par interrogation du statut.
Une intégration et un tableau de bord pour collecter dans 12 pays d'Afrique centrale, de l'Ouest et de l'Est, avec les opérateurs locaux.
Avec une clé de test, la collecte est simulée : aucun client n'est débité. Un paiement échoué n'est jamais facturé.













De la clé d'API au premier paiement, tout est décrit dans la documentation.
Une clé de test (pk_test_) et une clé live (pk_live_). La clé live demande un compte vérifié (KYC).
Ajoutez son adresse IP dans Paramètres, Adresses IP autorisées. C'est obligatoire, même pour la clé de test.
Un POST en JSON, avec la clé dans l'en-tête Authorization. Voir l'exemple dans la documentation.
>> Exemple de requêteLe client confirme sur son téléphone. Vous recevez un webhook, ou vous interrogez le statut.
>> La réponse de l'APINous concevons des outils fiables et pratiques pour vous aider à vendre, gérer vos opérations et toucher plus de clients.
Sites vitrines professionnels, boutiques e-commerce, catalogues, portails et espaces clients adaptés aux téléphones et ordinateurs.
Applications Android et iOS avec comptes utilisateurs, tableaux de bord, notifications, paiements et fonctionnalités adaptées à votre activité.
Développement de plateformes de gestion, marketplaces, logiciels métiers, espaces administrateurs et systèmes automatisés.
Intégrez les paiements à votre site ou application, initiez des collectes et suivez les transactions à l'aide de notre API Hostafri Pay.
Mettez votre projet en ligne avec un hébergement web, un nom de domaine et une adresse email professionnelle.
Nous vous aidons à structurer votre projet, choisir les technologies adaptées, améliorer vos outils et assurer leur évolution.
Chaque projet sur mesure avance par étapes, avec des échanges réguliers et des validations.
Nous comprenons vos objectifs, vos utilisateurs et les fonctionnalités nécessaires.
Nous définissons la solution, le calendrier et le budget de votre projet.
Nous réalisons votre solution et vous permettons de suivre son avancement.
Nous mettons le projet en ligne et vous accompagnons pour la suite.
Nous concevons nos solutions en tenant compte des usages réels des entreprises et des utilisateurs africains : priorité au mobile, intégration des paiements locaux et simplicité d'utilisation.
Des expériences pensées pour le mobile et les moyens de paiement utilisés localement.
Des outils conçus pour accompagner le développement de votre activité.
Un accompagnement de la définition du besoin à la mise en production.
Développement, hébergement, intégration et solutions de paiement réunis.
Une commission, incluse dans le montant collecté. Vous recevez le montant moins la commission. Un paiement échoué n'est pas facturé.
| Pays | Devise | Commission | Précisions |
|---|---|---|---|
| XAF | 3,5 % | Déduite du montant collecté. | |
| CDF | 3,5 % | Déduite du montant collecté. | |
| XAF | 3,5 % | Déduite du montant collecté. | |
| XOF | 3,2 % | Déduite du montant collecté. | |
| XOF | 0,5 % | Le client paie en plus 3 % de frais opérateur, affichés sur son téléphone. | |
| XOF | 0,5 % | Le client paie en plus 3 % de frais opérateur, affichés sur son téléphone. | |
| XOF | 0,5 % | Le client paie en plus 3 % de frais opérateur, affichés sur son téléphone. | |
| XOF | 0,5 % | Le client paie en plus 3 % de frais opérateur, affichés sur son téléphone. | |
| TZS | 3,2 % | Déduite du montant collecté. | |
| RWF | 3,5 % | Déduite du montant collecté. | |
| UGX | 3,2 % | Déduite du montant collecté. | |
| ZMW | 3,5 % | Déduite du montant collecté. |
Montant crédité = montant collecté − (montant collecté × commission). Le détail figure dans chaque réponse de l'API : fee et net_amount.
Avec une clé de test, la collecte est simulée : aucun client n'est débité et rien n'est crédité sur votre portefeuille.
Nos projets sur mesure sont chiffrés en FCFA après cadrage. Demander un devis
L'API de collecte envoie une demande de paiement sur le téléphone de votre client. Voici tout ce qu'il faut pour initier une collecte.
Envoyez la requête depuis votre serveur, jamais depuis un navigateur ou une application mobile : votre clé doit rester secrète.
curl -X POST https://hostafri.com/api/v1/collect \
-H "Authorization: Bearer pk_live_votre_cle" \
-H "Content-Type: application/json" \
-d '{
"operator": "MTN_CG",
"phone": "242064435000",
"amount": 5000,
"description": "Commande 1001",
"reference": "CMD-1001"
}'
<?php
$ch = curl_init('https://hostafri.com/api/v1/collect');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('HOSTAFRI_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'operator' => 'MTN_CG',
'phone' => '242064435000',
'amount' => 5000,
'description' => 'Commande 1001',
'reference' => 'CMD-1001',
]),
]);
$reponse = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $reponse['data']['id'] . ' : ' . $reponse['data']['status'];
// Node.js 18 ou plus
const reponse = await fetch("https://hostafri.com/api/v1/collect", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.HOSTAFRI_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
operator: "MTN_CG",
phone: "242064435000",
amount: 5000,
description: "Commande 1001",
reference: "CMD-1001"
})
});
const resultat = await reponse.json();
console.log(resultat.data.id, resultat.data.status);
import os
import requests
r = requests.post(
"https://hostafri.com/api/v1/collect",
headers={"Authorization": "Bearer " + os.environ["HOSTAFRI_API_KEY"]},
json={
"operator": "MTN_CG",
"phone": "242064435000",
"amount": 5000,
"description": "Commande 1001",
"reference": "CMD-1001",
},
)
print(r.json())
| Champ | Obligatoire | Description |
|---|---|---|
operator | Oui | Code de l'opérateur au format RÉSEAU_PAYS, par exemple MTN_CG ou AIRTEL_CG. La liste complète est plus bas. |
phone | Oui | Numéro mobile money du client. Règles selon le pays, ci-dessous. |
amount | Oui | Montant dans la devise du pays, de 1 à 100 000 000. |
description | Non | Libellé du paiement, 60 caractères au plus. |
reference | Non | Votre référence unique, de 1 à 100 caractères (lettres, chiffres, _ . : -). Renvoyer la même référence ne crée pas de doublon. |
otp | Selon l'opérateur | Code OTP du client, de 4 à 8 chiffres. Exigé pour ORANGE_BF et WAVE_BF. |
country | Non | Code pays à 2 lettres. Il se déduit de operator ; s'il est envoyé, il doit correspondre. |
customer_name, return_url | Non | Nom du client et adresse HTTPS de retour après paiement, utilisés par certains opérateurs. |
La règle dépend du pays du client. Les espaces, le signe + et le 00 initial sont acceptés.
Congo-Brazzaville, RD Congo, Cameroun, Bénin, Tanzanie, Rwanda, Ouganda, Zambie.
Le client saisit son numéro avec l'indicatif du pays. Sans indicatif, la requête est refusée avec l'erreur invalid_phone.
Togo, Sénégal, Burkina Faso, Côte d'Ivoire.
Les deux formes sont acceptées. Sans indicatif, il est ajouté automatiquement. Les chiffres du numéro ne sont jamais modifiés.
07 12 34 56 78 225 07 12 34 56 78Le code se compose du réseau et du pays : MTN_CG pour MTN au Congo-Brazzaville, AIRTEL_CD pour Airtel en RD Congo. Vous ne pouvez collecter que dans les pays où vous avez un portefeuille actif.
| Pays | Devise | Indicatif | Codes à envoyer dans operator |
|---|---|---|---|
| XAF | +242 |
|
|
| CDF | +243 |
|
|
| XAF | +237 |
|
|
| XOF | +229 |
|
|
| XOF | +228 |
|
|
| XOF | +221 |
|
|
| XOF | +226 |
|
|
| XOF | +225 |
|
|
| TZS | +255 |
|
|
| RWF | +250 |
|
|
| UGX | +256 |
|
|
| ZMW | +260 |
|
La liste à jour est aussi disponible par l'API : GET /api/v1/collect?operators=all.
Une collecte créée renvoie le code HTTP 201 et son identifiant. Le statut est d'abord pending : le client doit confirmer sur son téléphone. Il passe ensuite à success (le portefeuille est crédité) ou failed. Si payment_url est renseigné, redirigez le client vers cette adresse pour finaliser le paiement.
{
"success": true,
"livemode": true,
"data": {
"id": "col_9f3a6c1d2b4e5f708192a3b4",
"reference": "CMD-1001",
"transaction_reference": "DEP261030095907A1B2C3",
"livemode": true,
"status": "pending",
"amount": 5000,
"fee": 75,
"net_amount": 4925,
"currency": "XAF",
"country": "CG",
"operator": "MTN_CG",
"phone": "********5000",
"credited": false,
"payment_url": null,
"failure_reason": null,
"message": "Collecte initiée : en attente de la confirmation du client sur son téléphone.",
"created_at": "2026-10-30T09:59:07Z"
}
}
Pour connaître l'état d'une collecte, appelez GET /api/v1/collect?id=col_… ou GET /api/v1/collect?reference=CMD-1001, avec la même clé.
Hostafri appelle votre URL HTTPS à chaque étape : collect.initiated, collect.success et collect.failed. Sans réponse 2xx de votre part, l'envoi est retenté jusqu'à 6 fois sur environ 14 heures. Vérifiez toujours la signature de l'en-tête X-Hostafri-Signature (HMAC SHA-256 de l'horodatage, d'un point, puis du corps reçu, avec votre secret de webhook).
<?php
$secret = getenv('HOSTAFRI_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
// En-tête : "t=1761818347,v1=ab12…"
[$t, $v1] = array_map(
fn($p) => explode('=', $p, 2)[1],
explode(',', $_SERVER['HTTP_X_HOSTAFRI_SIGNATURE'] ?? 't=,v1=')
);
$attendu = hash_hmac('sha256', $t . '.' . $payload, $secret);
if (!hash_equals($attendu, $v1)) {
http_response_code(400);
exit;
}
$evenement = json_decode($payload, true); // $evenement['type'] : collect.success, collect.failed…
http_response_code(200);
Toute erreur renvoie {"success": false, "error": {"code": "…", "message": "…"}}.
| HTTP | Code | Cause et solution |
|---|---|---|
| 401 | invalid_api_key | Clé absente, révoquée ou mal formée. Envoyez-la dans Authorization: Bearer …. |
| 403 | ip_not_allowed | L'IP de votre serveur n'est pas autorisée. Le message indique l'adresse à ajouter. |
| 403 | kyc_not_verified, key_not_verified | Clé live : le compte ou la clé n'est pas encore vérifié. |
| 422 | invalid_operator | Code inconnu, ou pays qui ne correspond pas au code. |
| 422 | wallet_not_found | Vous n'avez pas de portefeuille actif pour ce pays. |
| 422 | invalid_phone | Numéro invalide, ou indicatif manquant dans un pays qui l'exige. |
| 422 | otp_required | L'opérateur exige un code OTP dans le champ otp. |
| 422 | invalid_amount | Montant hors limites ou trop faible une fois la commission déduite. |
| 422 | provider_rejected | L'opérateur a refusé le paiement (numéro, solde, montant). |
| 409 | reference_conflict | Cette référence a déjà servi avec un autre montant ou un autre opérateur. |
| 429 | too_many_pending | Trop de collectes en attente pour ce numéro. Patientez avant de réessayer. |
| 202 | warning | Service de paiement momentanément indisponible. La collecte est créée et son résultat arrive par webhook. |
Expliquez-nous votre besoin. Notre équipe pourra échanger avec vous sur les fonctionnalités, les délais et les prochaines étapes.