Documentation API Recharge Externe B-MO (Collections)

Présentation

L'API Recharge Externe B-MO (Collections / Cash-in) permet à une application partenaire ou un système marchand d'alimenter directement un compte ou portefeuille B-MO client.

Le cycle complet s'articule en 3 étapes clés :

1. Calcul du coût de la recharge (GET /thirdparty/collection/cost) : Estimation préalable des frais applicables avant le déclenchement financier.
2. Exécution de la recharge (POST /thirdparty/collection/operation) : Initiation du crédit sur le portefeuille client avec génération d'une référence transactionnelle unique.
3. Suivi du statut de l'opération (GET /thirdparty/operation) : Consultation de l'état final de la transaction via votre référence externe partenaire ou la référence B-MO.

URL de Base (selon l'environnement sélectionné) :

• TEST (Défaut) : https://svc.test.bestcash.me/external
• PAP : https://svc.pap.bestcash.me/external
• LIVE (Production) : https://svc.bmo.bestcash.me/external

Vous pouvez basculer d'un environnement à un autre à tout moment depuis le menu déroulant en haut des consoles d'essai <ApiPlayground /> ci-dessous.

En-têtes obligatoires :

• X-Auth-ApiKey : Votre clé d'API partenaire
• X-Auth-ApiSecret : Votre secret d'API partenaire
• Content-Type : application/json
• Accept : application/json

Règles d'intégration importantes

[!WARNING]

1. Aucun champ superflu dans le corps JSON de l'opération

Lors de l'appel à l'étape 2 (/operation), n'incluez aucun champ additionnel (tel que country ou currency) dans le corps JSON. Le compilateur et validateur Symfony de l'API rejette immédiatement toute requête contenant des champs non définis dans le schéma avec une erreur 400 VALIDATION FAILED (extra fields).

[!NOTE]

2. Formats des numéros de téléphone

• Étape 1 (/cost) : Le paramètre msisdn est transmis sans le signe + (ex: 2290196123456).
• Étape 2 (/operation) : Le champ targetMsisdn doit être fourni au format international avec le signe + (ex: +2290196123456).

1. Calculer le coût de la recharge (GET /thirdparty/collection/cost)

Estime les frais de transaction applicables avant de déclencher l'opération de rechargement.

• Méthode : GET
• URL : /external/thirdparty/collection/cost
• Paramètres de requête (Query params) :
  • amount (obligatoire) : Montant de la recharge en XOF (ex: 1000).
  • msisdn (obligatoire) : Numéro du destinataire sans le signe + (ex: 2290196123456).
  • country (obligatoire) : Code pays ISO 3166-1 alpha-2 du destinataire (ex: BJ). (Obligatoire sur le validateur API).

Exemple de requête cURL

curl -X GET "https://svc.test.bestcash.me/external/thirdparty/collection/cost?amount=1000&msisdn=2290196123456&country=BJ" \
  -H "X-Auth-ApiKey: <VOTRE_API_KEY>" \
  -H "X-Auth-ApiSecret: <VOTRE_API_SECRET>" \
  -H "Accept: application/json"

Exemple de réponse HTTP 200

{
  "cost": 0.0,
  "currencyCode": "XOF"
}

2. Effectuer la recharge (POST /thirdparty/collection/operation)

Initie le crédit sur le portefeuille client B-MO et génère la référence transactionnelle du système.

• Méthode : POST
• URL : /external/thirdparty/collection/operation
• Corps de la requête (JSON Body) :
  • amount (number, obligatoire) : Montant total de la recharge (ex: 1000).
  • externalReference (string, obligatoire) : Référence unique générée par votre plateforme pour identifier la transaction (ex: "RECH-PAP-2026-001").
  • targetFirstname (string, obligatoire) : Prénom du titulaire destinataire.
  • targetLastname (string, obligatoire) : Nom de famille du titulaire destinataire.
  • targetMsisdn (string, obligatoire) : Numéro de téléphone au format international avec + (ex: "+2290196123456").

Exemple de requête cURL

curl -X POST "https://svc.test.bestcash.me/external/thirdparty/collection/operation" \
  -H "X-Auth-ApiKey: <VOTRE_API_KEY>" \
  -H "X-Auth-ApiSecret: <VOTRE_API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": 1000,
    "externalReference": "RECH-PAP-2026-001",
    "targetFirstname": "Jean",
    "targetLastname": "Dupont",
    "targetMsisdn": "+2290196123456"
  }'

Exemple de réponse HTTP 200

{
  "prefixedAmount": "1 000 F CFA",
  "prefixedOperationCost": "0 F CFA",
  "operationCode": "",
  "status": "ONGOING",
  "operationCost": 0.0,
  "amount": 1000.0,
  "operationType": "COLLECTIONS",
  "reference": "BMO20260930110220474",
  "creationDate": "2026-09-30T11:02:20+00:00"
}

[!NOTE] Conservez la valeur du champ reference (ex: "BMO20260930110220474") ainsi que votre externalReference afin d'effectuer les rapprochements et le suivi du statut.

3. Vérifier le statut de l'opération (GET /thirdparty/operation)

Consulte l'avancement d'un rechargement à l'aide de votre référence partenaire unique (externalReference) ou de la référence système B-MO (reference).

• Méthode : GET
• URL : /external/thirdparty/operation
• Paramètres de requête (Query params) :
  • externalReference (string, optionnel) : La référence unique transmise lors de l'initiation (ex: "RECH-PAP-2026-001").
  • reference (string, optionnel) : La référence interne B-MO attribuée lors de l'opération (ex: "BMO20260930110220474").

Règle : Au moins un des deux identifiants (externalReference ou reference) doit être renseigné.

Exemple de requête cURL

curl -X GET "https://svc.test.bestcash.me/external/thirdparty/operation?externalReference=RECH-PAP-2026-001" \
  -H "X-Auth-ApiKey: <VOTRE_API_KEY>" \
  -H "X-Auth-ApiSecret: <VOTRE_API_SECRET>" \
  -H "Accept: application/json"

Exemple de réponse HTTP 200

{
  "status": "ONGOING",
  "operationCost": 0.0,
  "amount": 1000.0,
  "operationType": "COLLECTIONS",
  "reference": "BMO20260930110220474",
  "creationDate": "2026-09-30T11:02:20+00:00",
  "externalReference": "RECH-PAP-2026-001"
}

Dictionnaire des paramètres

Codes d'erreurs et Dépannage

Exemples d'intégration de bout en bout

const axios = require('axios');

const BASE_URL = 'https://svc.test.bestcash.me/external';
const HEADERS = {
  'X-Auth-ApiKey': 'VOTRE_API_KEY',
  'X-Auth-ApiSecret': 'VOTRE_API_SECRET',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

async function executeCollection() {
  try {
    // 1. Calcul du coût de la recharge
    console.log('--- 1. Estimation des frais de recharge ---');
    const costRes = await axios.get(`${BASE_URL}/thirdparty/collection/cost`, {
      params: {
        amount: 1000,
        msisdn: '2290196123456',
        country: 'BJ'
      },
      headers: HEADERS
    });
    console.log('Coût estimé :', costRes.data);

    // 2. Exécution de la recharge
    const externalReference = `RECH-DEV-${Date.now()}`;
    console.log(`--- 2. Exécution de la recharge (${externalReference}) ---`);
    const opRes = await axios.post(`${BASE_URL}/thirdparty/collection/operation`, {
      amount: 1000,
      externalReference: externalReference,
      targetFirstname: 'Jean',
      targetLastname: 'Dupont',
      targetMsisdn: '+2290196123456'
    }, { headers: HEADERS });

    console.log('Réponse opération :', opRes.data);
    const bmoReference = opRes.data.reference;

    // 3. Suivi du statut de l'opération
    console.log('--- 3. Vérification du statut ---');
    const statusRes = await axios.get(`${BASE_URL}/thirdparty/operation`, {
      params: { externalReference: externalReference },
      headers: HEADERS
    });
    console.log('Statut final :', statusRes.data);

  } catch (error) {
    console.error('Erreur :', error.response ? error.response.data : error.message);
  }
}

executeCollection();