Documentation API Achat de Crédit & Pass (Airtime)

Spécifications d'intégration pour l'achat de crédit téléphonique, pass internet (DATA), bundles (COMBO) et cartes de recharge.

Présentation

L'API Airtime B-MO permet aux partenaires tiers d'effectuer des achats de crédit téléphonique, de forfaits internet (DATA), de combinaisons (COMBO) ou de recharge de crédits (TOPUP) pour tous les opérateurs mobiles supportés (MTN, Moov, Celtiis, etc.).

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

  • PAP (Pré-production / Défaut) : https://svc.pap.bestcash.me/external
  • TEST (Sandbox) : https://svc.test.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.

1. Liste des produits airtime disponibles (GET /external/thirdparty/airtime/{msisdn}/products/{productType})

Permet de consulter la liste des offres et produits de recharge éligibles pour le numéro du bénéficiaire.

  • Méthode : GET
  • URL : /external/thirdparty/airtime/{msisdn}/products/{productType}
  • Paramètres d'URL (Path params) :
    • msisdn (obligatoire) : Numéro du client bénéficiaire au format international (ex: +2290196666262)
    • productType (obligatoire) : Type de produit recherché :
      • TOPUP : Crédit de communication classique
      • DATA : Pass / Forfaits Internet
      • COMBO : Offres combinées (Appels + SMS + Data)
      • MOBILE_PIN : Code de recharge / PIN virtuel

Tester la liste des produits Airtime

Récupérez les offres compatibles avec un numéro de téléphone client.

Authentification (En-têtes B-MO)
Paramètres d'URL / Query Parameters (0)

Aucun paramètre d'URL configuré.

Exemple de réponse HTTP 200

[
  {
    "id": "17",
    "priceType": "range",
    "name": "200-30000 XOF Top Up",
    "minPrice": "200.00",
    "maxPrice": "30000.00"
  }
]

2. Calculer le coût d'une opération (GET /external/thirdparty/airtime/operation-cost)

Permet d'estimer les frais d'opération associés au montant du crédit ou forfait demandé.

  • Méthode : GET
  • URL : /external/thirdparty/airtime/operation-cost
  • Paramètres de requête (Query params) :
    • amount (obligatoire) : Montant de l'opération en XOF (ex: 1000)

Tester le calcul du coût Airtime

Estimez les frais associés à l'achat de crédit.

Authentification (En-têtes B-MO)
Paramètres d'URL / Query Parameters (1)

Exemple de réponse HTTP 200

{
  "cost": 0,
  "targetMonetaryArea": {
    "reference": "MONAXOF001",
    "name": "UEMOA",
    "currencyLongName": "Franc CFA",
    "currencyShortName": "F CFA",
    "currencyRate": null,
    "currencyCode": "XOF"
  }
}

3. Effectuer l'achat de crédit / forfait (POST /external/thirdparty/airtime)

Exécute l'opération d'achat d'airtime et crédite le compte du bénéficiaire.

  • Méthode : POST
  • URL : /external/thirdparty/airtime

Tester l'achat de crédit Airtime

Exécutez un achat de crédit ou de forfait en direct.

Authentification (En-têtes B-MO)
Paramètres d'URL / Query Parameters (0)

Aucun paramètre d'URL configuré.

Corps de la Requête (JSON Body)

Exemple de corps de requête (JSON)

{
  "amount": 1000,
  "product": "17",
  "beneficiary": "+2290196666262",
  "externalReference": "AIRTIME-REF-001"
}

Exemple de réponse HTTP 201

{
  "status": "CONFIRMED",
  "operationCost": 0,
  "amount": 1000,
  "operationType": "AIRTIME",
  "reference": "OPAIR20260723120508994",
  "creationDate": "2026-07-23T12:05:08+00:00",
  "externalReference": "AIRTIME-REF-001",
  "transactionId": "0",
  "productType": "Mobile Top Up",
  "productLabel": "200-30000 XOF Top Up",
  "operatorName": "Benin MTN",
  "recipientMsisdn": "+2290196666262",
  "recipientCountry": "BJ",
  "receivedAmount": 1000,
  "recipientCurrency": "XOF",
  "senderCurrency": "XOF",
  "statusId": "0"
}

4. Vérifier le statut d'une opération (GET /external/thirdparty/operation)

Permet de vérifier le statut d'une transaction Airtime soumise précédemment.

  • Méthode : GET
  • URL : /external/thirdparty/operation
  • Paramètres de requête (Query params) :
    • externalReference (optionnel) : Référence unique transmise lors de la création de la transaction
    • reference (optionnel) : Référence unique B-MO (ex: OPAIR20260723120508994)

Tester la vérification de statut Airtime

Consultez l'état d'un achat de crédit ou de pass.

Authentification (En-têtes B-MO)
Paramètres d'URL / Query Parameters (1)

Exemple de réponse HTTP 200

{
  "status": "CONFIRMED",
  "operationCost": 0,
  "amount": 1000,
  "operationType": "AIRTIME",
  "reference": "OPAIR20260723120508994",
  "creationDate": "2026-07-23T12:05:08+00:00",
  "externalReference": "AIRTIME-REF-001",
  "transactionId": "0",
  "productType": "Mobile Top Up",
  "productLabel": "200-30000 XOF Top Up",
  "operatorName": "Benin MTN",
  "recipientMsisdn": "+2290196666262",
  "recipientCountry": "BJ",
  "receivedAmount": 1000,
  "recipientCurrency": "XOF",
  "senderCurrency": "XOF",
  "statusId": "0"
}