Documentation API SBEE Postpayé (Factures Électricité)

Spécifications d'intégration et consoles interactives pour la consultation et le paiement de factures d'électricité postpayées SBEE.

Présentation

L'API SBEE Postpayé permet aux partenaires B-MO de consulter les factures d'électricité impayées d'un abonné SBEE (Société Béninoise d'Énergie Électrique), d'évaluer les frais de transaction applicables et d'effectuer le paiement global des factures sélectionnées.

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 Postpayé doit obligatoirement inclure les en-têtes HTTP suivants :

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

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

1. Récupérer les factures impayées (GET /external/thirdparty/sbee/postpaid/invoices)

Permet d'interroger le système SBEE avec la référence de l'abonné afin d'obtenir la liste complète de ses factures d'électricité non réglées.

  • Méthode : GET
  • URL : /external/thirdparty/sbee/postpaid/invoices
  • Paramètres de requête (Query params) :
    • customerReference (obligatoire) : Référence ou numéro de contrat de l'abonné SBEE (ex: "MFEYNJB7COYW").

Tester la recherche de factures impayées SBEE Postpayé

Consultez la liste des factures impayées d'un abonné et récupérez les références uniques et montants associés.

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

Description des paramètres de réponse

ChampTypeDescription
referenceAbonnestringRéférence de l'abonné SBEE (ex: "MFEYNJB7COYW").
namestringNom et prénom de l'abonné (ex: "John Doe").
invoicesarrayTableau d'objets représentants les factures impayées.
invoices[].amountstringMontant de la facture en XOF (ex: "7900").
invoices[].monthstringMois d'émission de la facture (ex: "04").
invoices[].yearstringAnnée d'émission de la facture (ex: "2026").
invoices[].referencestringRéférence unique de la facture à retransmettre lors du paiement (ex: "O1JR5RUVFV0QF").

Exemple de réponse HTTP 200 (Factures impayées trouvées)

{
  "referenceAbonne": "MFEYNJB7COYW",
  "name": "John Doe",
  "invoices": [
    {
      "amount": "7900",
      "month": "04",
      "year": "2026",
      "reference": "O1JR5RUVFV0QF"
    },
    {
      "amount": "4300",
      "month": "06",
      "year": "2026",
      "reference": "GU0UJDS3XZVRU6"
    }
  ]
}

2. Calculer le coût de l'opération (GET /external/thirdparty/sbee/postpaid/operation-cost)

Permet d'estimer les frais d'opération associés au montant de règlement des factures.

  • Méthode : GET
  • URL : /external/thirdparty/sbee/postpaid/operation-cost
  • Paramètres de requête (Query params) :
    • amount (obligatoire) : Montant total du paiement en XOF (ex: 10000).

Tester le calcul des frais d'opération SBEE Postpayé

Calculez les frais applicables et obtenez les informations sur la zone monétaire UEMOA.

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

Exemple de réponse HTTP 200

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

3. Effectuer le paiement des factures (POST /external/thirdparty/sbee/postpaid/operation)

Valide le paiement global des factures d'électricité sélectionnées.

Règles importantes d'utilisation :

  1. Le paramètre amount doit correspondre exactement à la somme des montants des factures soumises dans le tableau invoices (ex: 7900 + 4300 = 12200 XOF).
  2. Le paiement partiel d'une facture individuelle n'est pas autorisé par la SBEE.
  • Méthode : POST
  • URL : /external/thirdparty/sbee/postpaid/operation

Tester le paiement de factures SBEE Postpayé

Exécutez le paiement simultané de plusieurs factures impayées SBEE.

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 total cumulé des factures à régler (ex: 12200)
customerReferencestringOuiRéférence de l'abonné SBEE (ex: "MFEYNJB7COYW")
externalReferencestringOuiRéférence unique générée par votre application (ex: "SBEE-POSTPAY-REF-01")
invoicesarrayOuiListe des objets contenant les références des factures à régler
invoices[].referencestringOuiRéférence individuelle de chaque facture issue du check (ex: "O1JR5RUVFV0QF")

Exemple de réponse HTTP 200 (Paiement Confirmé)

{
  "status": "CONFIRMED",
  "operationCost": 1000.0,
  "amount": 12200.0,
  "operationType": "BILL_PAYMENT-ELECTRICITY_POSTPAID",
  "reference": "SBEEPOST20260729120000",
  "creationDate": "2026-07-29T12:00:00+00:00",
  "customerReference": "MFEYNJB7COYW",
  "externalReference": "SBEE-POSTPAY-REF-01",
  "customerName": "John Doe",
  "invoices": [
    {
      "reference": "O1JR5RUVFV0QF",
      "amount": 7900
    },
    {
      "reference": "GU0UJDS3XZVRU6",
      "amount": 4300
    }
  ]
}

4. Suivi et vérification du statut (GET /external/thirdparty/operation)

Recherchez le statut d'une transaction SBEE Postpayé à l'aide de votre référence unique partenaire (externalReference) ou de la référence B-MO (reference).

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

Tester la vérification de statut SBEE Postpayé

Vérifiez l'état d'un règlement de factures SBEE.

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

5. Exemples de Code d'Intégration

Node.js (Axios)

const axios = require('axios');

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

async function paySbeePostpaidInvoices() {
  try {
    const customerRef = 'MFEYNJB7COYW';
    
    // 1. Récupération des factures impayées
    console.log('1. Consultation des factures impayées SBEE...');
    const invRes = await client.get(`/thirdparty/sbee/postpaid/invoices?customerReference=${customerRef}`);
    const invoicesData = invRes.data;

    console.log(`Abonné: ${invoicesData.name}, Factures trouvées: ${invoicesData.invoices.length}`);

    // Calcul du montant total cumulé
    const totalAmount = invoicesData.invoices.reduce((sum, inv) => sum + parseFloat(inv.amount), 0);
    const invoiceRefs = invoicesData.invoices.map(inv => ({ reference: inv.reference }));

    // 2. Exécution du paiement
    console.log(`2. Paiement des factures (Montant total: ${totalAmount} XOF)...`);
    const extRef = `SBEE-POST-${Date.now()}`;
    
    const payRes = await client.post('/thirdparty/sbee/postpaid/operation', {
      amount: totalAmount,
      customerReference: customerRef,
      externalReference: extRef,
      invoices: invoiceRefs
    });

    console.log('Statut du paiement:', payRes.data.status);
    console.log('Référence B-MO:', payRes.data.reference);

  } catch (error) {
    console.error('Erreur lors du règlement SBEE Postpayé:', error.response?.data || error.message);
  }
}

paySbeePostpaidInvoices();

Python (Requests)

import requests
import time

BASE_URL = "https://svc.pap.bestcash.me/external"
HEADERS = {
    "X-Auth-ApiKey": "+2290196666262",
    "X-Auth-ApiSecret": "y7MwWuWeQORtpA==",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

customer_ref = "MFEYNJB7COYW"

# 1. Obtenir les factures impayées
inv_resp = requests.get(
    f"{BASE_URL}/thirdparty/sbee/postpaid/invoices",
    params={"customerReference": customer_ref},
    headers=HEADERS
)
inv_data = inv_resp.json()

print(f"Abonné: {inv_data.get('name')}")
invoices = inv_data.get("invoices", [])

total_amount = sum(float(inv["amount"]) for inv in invoices)
invoice_payload = [{"reference": inv["reference"]} for inv in invoices]

# 2. Exécuter le paiement
ext_ref = f"SBEE-POST-{int(time.time())}"
op_payload = {
    "amount": total_amount,
    "customerReference": customer_ref,
    "externalReference": ext_ref,
    "invoices": invoice_payload
}

op_resp = requests.post(
    f"{BASE_URL}/thirdparty/sbee/postpaid/operation",
    json=op_payload,
    headers=HEADERS
)

print("Statut:", op_resp.json().get("status"))
print("Référence:", op_resp.json().get("reference"))

cURL

# 1. Obtenir la liste des factures impayées
curl -X GET "https://svc.pap.bestcash.me/external/thirdparty/sbee/postpaid/invoices?customerReference=MFEYNJB7COYW" \
     -H "X-Auth-ApiKey: +2290196666262" \
     -H "X-Auth-ApiSecret: y7MwWuWeQORtpA==" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

# 2. Calculer les frais d'opération
curl -X GET "https://svc.pap.bestcash.me/external/thirdparty/sbee/postpaid/operation-cost?amount=10000" \
     -H "X-Auth-ApiKey: +2290196666262" \
     -H "X-Auth-ApiSecret: y7MwWuWeQORtpA==" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

# 3. Effectuer le paiement global des factures
curl -X POST "https://svc.pap.bestcash.me/external/thirdparty/sbee/postpaid/operation" \
     -H "X-Auth-ApiKey: +2290196666262" \
     -H "X-Auth-ApiSecret: y7MwWuWeQORtpA==" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
       "amount": 12200,
       "customerReference": "MFEYNJB7COYW",
       "externalReference": "SBEE-POSTPAY-REF-01",
       "invoices": [
         { "reference": "O1JR5RUVFV0QF" },
         { "reference": "GU0UJDS3XZVRU6" }
       ]
     }'

6. Codes et Messages d'Erreur

Message d'erreurDescriptionAction recommandée
AMOUNT TOO LOWLe montant du paiement est inférieur au total exact des factures soumises.Vérifier et transmettre le montant exact réclamé.
INSUFFICIENT AMOUNTLe solde disponible sur le compte marchand partenaire est insuffisant.Approvisionner le compte marchand avant d'exécuter la requête.
INVOICE NOT FOUNDLa référence de facture spécifiée n'existe pas ou est déjà réglée.Réexécuter la recherche de factures impayées pour obtenir la liste à jour.
401 UnauthorizedLes en-têtes X-Auth-ApiKey ou X-Auth-ApiSecret sont incorrects.Contrôler vos identifiants d'API partenaire.