README

SDK officiel PHP pour l'API AvePay MCF — certification fiscale DGI Burkina Faso / SECEF.

• Client HTTP au-dessus de Guzzle, payload friendly (calculs auto) + échappatoire brute.
• PHP 8.1+. Intégration Laravel (ServiceProvider + Facade + config publishable).

Installation

composer require avepay/mcf

Quickstart

use AvePay\AvePay;
use AvePay\AvePayError;

$avepay = new AvePay(getenv('AVEPAY_API_KEY'), ['isf' => '1']);
$mcf = $avepay->mcf('EL02000015-1');

$receipt = $mcf->certify([
    'number'   => 'FV-2026-0001',
    'type'     => 'FV',                              // FV | FT | EV | ET (défaut FV)
    'operator' => ['id' => 1, 'name' => 'Awa'],
    'customer' => ['type' => 'PP', 'name' => 'Client Comptant'],
    'items'    => [
        ['name' => 'Riz 25kg', 'taxGroup' => 'B', 'unitPrice' => 15000, 'quantity' => 1],
    ],
    'payments' => [['method' => 'cash', 'amount' => 15000]],
]);

echo $receipt->sig;       // signature SECEF (codeSecef)
echo $receipt->qr;        // contenu QR
echo $receipt->totalTtc;  // 15000
print_r($receipt->counters); // ['tc'=>…, 'fvc'=>…, 'frc'=>…]

Mapping friendly → brut

• number → invoiceNumber, type → invoiceType, operator => ['id','name'] → operatorId/operatorName.
• items : amountTtc calculé (unitPrice * quantity), taxRate déduit du taxGroup (A = 0 %, B = 18 %). Groupe inconnu (C..N) → fournir taxRate.
• payments : alias cash→E, transfer→V, card→C, mobile→M, cheque→B, other→A (codes bruts acceptés).
• Toute clé brute (invoiceType, clientType, …) prime. Les clés snake_case sont aussi acceptées.

Avoir (credit note)

$avoir = $mcf->creditNote([
    'number'           => 'FA-2026-0001',
    'from'             => $receipt,            // dérive creditNoteRef = "{nim}-{fvc}"
    // ou: 'creditNoteRef' => 'EL02000015-1-291',
    'creditNoteNature' => 'COR',               // COR | RAN | RAM | RRR (défaut COR)
    'operator' => ['id' => 1, 'name' => 'Awa'],
    'customer' => ['type' => 'PP'],
    'items'    => [['name' => 'Riz 25kg', 'taxGroup' => 'B', 'unitPrice' => 15000]],
    'payments' => [['method' => 'cash', 'amount' => 15000]],
]);

Info / cancel-pending / me

$info = $mcf->info();          // McfInfo (mode, compteurs, marchand)
$mcf->cancelPending();         // annule une transaction 38h pendante
$me = $avepay->me();           // org + NIM scopés + état bridges

Erreurs

try {
    $mcf->certify($invoice);
} catch (AvePayError $e) {
    echo $e->errorCode();   // BRIDGE_OFFLINE, NIM_NOT_IN_SCOPE, …
    echo $e->httpStatus();
    echo $e->getMessage();
    echo $e->requestId();
    if ($e->isBridgeOffline()) { /* MCF hors ligne */ }
}

Retry réseau/5xx automatique avec backoff + Idempotency-Key réutilisée entre tentatives.

Webhooks

$event = $avepay->webhooks()->verify($rawBody, $request->header('X-Avepay-Signature'));
// $event['type'] : "cert.issued" | "mcf.connected" | "mcf.disconnected"

Laravel

Le package est auto-découvert (provider + facade). Publier la config :

php artisan vendor:publish --tag=avepay-config

Variables d'env : AVEPAY_API_KEY, AVEPAY_BASE_URL, AVEPAY_ISF, AVEPAY_WEBHOOK_SECRET, AVEPAY_TIMEOUT, AVEPAY_MAX_RETRIES.

use AvePay\Laravel\AvePay; // facade

$receipt = AvePay::mcf('EL02000015-1')->certify([...]);

Développement

composer install
vendor/bin/phpunit   # tests contre tests/fixtures/ (Guzzle MockHandler)