Documentation API SBEE Prépayé (Électricité)

Spécifications d'intégration et consoles interactives pour la vérification de compteur et le paiement de recharges électriques prépayées SBEE.

Présentation

L'API SBEE Prépayé permet d'interroger un compteur électrique SBEE (Société Béninoise d'Énergie Électrique), de vérifier les informations du client et de régler un achat de recharge d'électricité prépayée avec génération instantanée du jeton (Token STS).

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.

Authentification

Chaque requête vers l'API SBEE Prépayé doit obligatoirement inclure les en-têtes HTTP suivants :

  • X-Auth-ApiKey : Votre clé d'API partenaire (ex: +2290160606790)
  • X-Auth-ApiSecret : Votre secret d'API partenaire (ex: l/LshBHhTvhWcA==)
  • Content-Type : application/json
  • Accept : application/json

En cas d'identifiants incorrects ou manquants, l'API retourne un code HTTP 401 Unauthorized.

1. Vérification du compteur (GET /external/thirdparty/sbee/prepaid/check)

Avant toute opération de paiement, vous devez obligatoirement effectuer une vérification préalable du compteur. Cette étape permet d'obtenir les clés uniques (transId, verifyCode, verifyData) indispensables pour sécuriser l'opération de recharge.

  • Méthode : GET
  • URL : /external/thirdparty/sbee/prepaid/check
  • Paramètres de requête (Query params) :
    • meterNum (obligatoire) : Numéro du compteur SBEE (ex: "04227620724").
    • amount (obligatoire) : Montant souhaité pour la recharge en XOF (ex: 5000).

Tester la vérification de compteur SBEE Prépayé

Interrogez les données du compteur et récupérez le transId, verifyCode et verifyData nécessaires au paiement.

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

Description des paramètres de réponse

ChampTypeDescription
transIdstringIdentifiant unique de la session de vérification généré par la SBEE (ex: "20260729105507121200").
verifyCodestringCode de hachage et de sécurité à retransmettre lors du paiement.
verifyDatastringDonnée de vérification de session (ex: "VERIFY-538216").
customerNamestringNom de l'abonné associé au compteur (ex: "JOHN DOE").
vendQtystringEstimation du nombre de kWh fournis pour ce montant.
feeAMTstringFrais de service appliqués par l'opérateur (ex: "100").
arrearAMTstringMontant des éventuels arriérés ou dettes sur le compteur (ex: "0" ou "100000").
changeKeybooleanIndique s'il s'agit d'un premier achat ou si le compteur nécessite une mise à jour de clé.

Exemple de réponse HTTP 200 (Vérification réussie)

{
  "vendQty": "50",
  "feeAMT": "100",
  "customerName": "JOHN DOE",
  "arrearAMT": "0",
  "verifyData": "VERIFY-538216",
  "amount": 5000.0,
  "meterNum": "04227620724",
  "verifyCode": "66bd1e8d9addd8fa0fa5333984da9fbc",
  "transId": "20260729105507121200",
  "changeKey": false
}

2. Exécution du paiement et génération du Token (POST /external/thirdparty/sbee/prepaid/operation)

Transmettez les clés obtenues lors de la vérification (transId, verifyCode, verifyData) pour valider la transaction et générer le jeton de recharge (Token STS).

  • Méthode : POST
  • URL : /external/thirdparty/sbee/prepaid/operation

Tester le paiement et la génération du Token SBEE

Validez l'opération d'achat d'électricité et obtenez le code Token à saisir sur le compteur.

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)

Structure du corps de la requête (JSON)

ChampTypeObligatoireDescription
amountnumberOuiMontant du paiement (ex: 5000)
meterNumstringOuiNuméro du compteur SBEE (ex: "04227620724")
transIdstringOuiIdentifiant de transaction issu de la vérification
verifyCodestringOuiCode de vérification issu de la vérification
verifyDatastringOuiDonnée de vérification issue de la vérification
externalReferencestringOuiRéférence unique générée par le système partenaire (ex: "SBEE-TEST-01")
changeKeybooleanOuiBooléen (true ou false) retourné lors du check

Cas de Test Réels et Formats de Réponse

Scénario A : Achat Standard Réussi (Compteur 04227620724)

La transaction est confirmée (CONFIRMED) et délivre le code Token STS unique de 20 chiffres à saisir sur le compteur.

{
  "status": "CONFIRMED",
  "operationCost": 50.0,
  "amount": 5000.0,
  "operationType": "BILL_PAYMENT-ELECTRICITY_PREPAID",
  "reference": "20260729100236681600",
  "creationDate": "2026-07-29T10:02:36+00:00",
  "externalReference": "SBEE-TEST-SUCCESS-01",
  "meterNum": "04227620724",
  "customerName": "JOHN DOE",
  "token": "STS-61125302428329071267",
  "refCode": "REF-613887",
  "code": "0",
  "tariffCode": "DOM",
  "arrearAMT": "0",
  "vendQty": "50",
  "feeAMT": "100",
  "verifyCode": "66bd1e8d9addd8fa0fa5333984da9fbc",
  "verifyData": "VERIFY-538216"
}

Scénario B : Nouveau Compteur / Mise à jour de Clé (changeKey: true, Compteur 04227620735)

Lorsque changeKey vaut true, la réponse contient une série de tokens multiples séparés par des virgules pour mettre à jour la clé du compteur avant le chargement des unités.

{
  "status": "CONFIRMED",
  "operationCost": 50.0,
  "amount": 5000.0,
  "operationType": "BILL_PAYMENT-ELECTRICITY_PREPAID",
  "reference": "20260729100324205100",
  "creationDate": "2026-07-29T10:03:24+00:00",
  "externalReference": "SBEE-TEST-UPDATE-01",
  "meterNum": "04227620735",
  "customerName": "JOHN DOE",
  "token": "TK-47912712276250492143,TK-58243033670224272984,STS-55833094350594509770",
  "refCode": "REF-211036",
  "code": "0",
  "tariffCode": "DOM",
  "arrearAMT": "0",
  "vendQty": "50",
  "feeAMT": "100",
  "verifyCode": "a4d8755497b90aebd0d64cdde28dd295",
  "verifyData": "VERIFY-197566"
}

Scénario C : Traitement des Arriérés et Impayés (Compteur 04227620731)

Si l'abonné possède des arriérés, le montant réinjecté vient apurer la dette (arrearAMT: "4750"). Le paiement est validé et les données de compte sont ajustées.

{
  "status": "CONFIRMED",
  "operationCost": 50.0,
  "amount": 5000.0,
  "operationType": "BILL_PAYMENT-ELECTRICITY_PREPAID",
  "reference": "20260729101052702000",
  "creationDate": "2026-07-29T10:10:51+00:00",
  "externalReference": "SBEE-TEST-ARREAR-01",
  "meterNum": "04227620731",
  "customerName": "JOHN DOE",
  "token": "STS-49180455446170720868",
  "refCode": "REF-680959",
  "code": "0",
  "tariffCode": "DOM",
  "arrearAMT": "4750",
  "vendQty": "0",
  "feeAMT": "100",
  "verifyCode": "5477d19cd2fd2aa772e6b9f0c88fa032",
  "verifyData": "VERIFY-723510"
}

Scénario D : Échec d'opération (Compteur 04227620725)

En cas de rejet du réseau SBEE ou de paramètre invalide, le statut renvoyé est FAILED.

{
  "status": "FAILED",
  "operationCost": 50.0,
  "amount": 5000.0,
  "operationType": "BILL_PAYMENT-ELECTRICITY_PREPAID",
  "reference": "20260729100402634100",
  "creationDate": "2026-07-29T10:04:02+00:00",
  "externalReference": "SBEE-TEST-FAIL-01",
  "meterNum": "04227620725",
  "customerName": null,
  "token": null,
  "refCode": null,
  "code": null,
  "tariffCode": null,
  "arrearAMT": null,
  "vendQty": null,
  "feeAMT": null,
  "verifyCode": "105c3aafb9ef6dfe15570eff1408e267",
  "verifyData": "VERIFY-229949"
}

3. Suivi et vérification du statut d'une opération (GET /external/thirdparty/operation)

Permet de rechercher le statut d'une opération SBEE précédemment exécutée à l'aide de votre référence partenaire (externalReference) ou de la référence système (reference).

  • Méthode : GET
  • URL : /external/thirdparty/operation
  • Paramètres de requête (Query params) :
    • externalReference (optionnel) : Référence unique transmise lors de la requête de paiement (ex: "SBEE-TEST-SUCCESS-01").
    • reference (optionnel) : Référence unique B-MO (ex: "20260729100236681600").

Tester la vérification de statut SBEE

Consultez le statut et le Token STS d'une transaction prépayée effectuée.

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

4. Exemples de Code d'Intégration

Node.js (Axios)

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://svc.test.bestcash.me/external',
  headers: {
    'X-Auth-ApiKey': '+2290160606790',
    'X-Auth-ApiSecret': 'l/LshBHhTvhWcA==',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

async function buySbeePrepaidElectricity() {
  try {
    // 1. Vérification du compteur
    const meterNum = '04227620724';
    const amount = 5000;
    
    console.log('1. Vérification du compteur SBEE...');
    const checkRes = await client.get(`/thirdparty/sbee/prepaid/check?meterNum=${meterNum}&amount=${amount}`);
    const checkData = checkRes.data;

    console.log(`Abonné: ${checkData.customerName}, TransId: ${checkData.transId}`);

    // 2. Exécution du paiement
    console.log('2. Exécution de l\'opération de paiement...');
    const extRef = `SBEE-REF-${Date.now()}`;
    const payRes = await client.post('/thirdparty/sbee/prepaid/operation', {
      amount: amount,
      meterNum: meterNum,
      transId: checkData.transId,
      verifyCode: checkData.verifyCode,
      verifyData: checkData.verifyData,
      externalReference: extRef,
      changeKey: checkData.changeKey
    });

    console.log('Résultat du paiement:', payRes.data.status);
    console.log('Code Token généré:', payRes.data.token);

  } catch (error) {
    console.error('Erreur lors du traitement SBEE:', error.response?.data || error.message);
  }
}

buySbeePrepaidElectricity();

Python (Requests)

import requests
import time

BASE_URL = "https://svc.test.bestcash.me/external"
HEADERS = {
    "X-Auth-ApiKey": "+2290160606790",
    "X-Auth-ApiSecret": "l/LshBHhTvhWcA==",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

meter_num = "04227620724"
amount = 5000

# 1. Check compteur
check_resp = requests.get(
    f"{BASE_URL}/thirdparty/sbee/prepaid/check",
    params={"meterNum": meter_num, "amount": amount},
    headers=HEADERS
)
check_data = check_resp.json()
print("Client:", check_data.get("customerName"))

# 2. Exécution opération
ext_ref = f"SBEE-PY-{int(time.time())}"
op_payload = {
    "amount": amount,
    "meterNum": meter_num,
    "transId": check_data["transId"],
    "verifyCode": check_data["verifyCode"],
    "verifyData": check_data["verifyData"],
    "externalReference": ext_ref,
    "changeKey": check_data.get("changeKey", False)
}

op_resp = requests.post(
    f"{BASE_URL}/thirdparty/sbee/prepaid/operation",
    json=op_payload,
    headers=HEADERS
)
print("Statut:", op_resp.json().get("status"))
print("Token:", op_resp.json().get("token"))

cURL

# 1. Vérification du compteur
curl -X GET "https://svc.test.bestcash.me/external/thirdparty/sbee/prepaid/check?meterNum=04227620724&amount=5000" \
     -H "X-Auth-ApiKey: +2290160606790" \
     -H "X-Auth-ApiSecret: l/LshBHhTvhWcA==" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

# 2. Exécution du paiement
curl -X POST "https://svc.test.bestcash.me/external/thirdparty/sbee/prepaid/operation" \
     -H "X-Auth-ApiKey: +2290160606790" \
     -H "X-Auth-ApiSecret: l/LshBHhTvhWcA==" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
       "amount": 5000,
       "meterNum": "04227620724",
       "transId": "20260729105507121200",
       "verifyCode": "66bd1e8d9addd8fa0fa5333984da9fbc",
       "verifyData": "VERIFY-538216",
       "externalReference": "SBEE-TEST-SUCCESS-01",
       "changeKey": false
     }'

5. Codes et Messages d'Erreur

Message d'erreurDescriptionAction recommandée
AMOUNT TOO LOWLe montant spécifié est inférieur au montant minimum de recharge exigé.Augmenter le montant saisi (ex: minimum 500 XOF).
INSUFFICIENT AMOUNTLe solde disponible sur le compte marchand partenaire est insuffisant.Approvisionner le compte marchand avant de réinterroger.
The amount should be greater than 0Le montant de recharge doit être un nombre strictly positif.Transmettre une valeur numérique supérieure à 0.
401 UnauthorizedLes en-têtes d'authentification X-Auth-ApiKey ou X-Auth-ApiSecret sont invalides.Vérifier la clé API et le secret attribués.