BCEAO PI-SPI QR Code Python Module

Le package Phyton bceao_pispi_qrcode fournit une interface robuste, sécurisée et conforme aux standards EMV pour intégrer les QR Codes PI-SPI, permettant aux applications python d'interagir avec l'écosystème PI-SPI de la BCEAO.

Structure du projet

└── 📁bceao-pispi-qrcode
    └── 📁bceao_pispi_qrcode
        └── 📁assets
            ├── __init__.py
            ├── ic_qr.png
            ├── logo_spi_dark.png
            ├── logo_spi_light.png
            ├── logo_spi.png
        └── 📁models
            ├── __init__.py
            ├── const.py
            ├── enums.py
            ├── exceptions.py
            ├── models.py
        ├── __init__.py
        ├── pispi_qr_generator.py
        ├── pispi_qr_payload.py
    └── 📁example
        ├── example.py
    └── 📁tests
        ├── __init__.py
        ├── test_generator.py
        ├── test_payload.py
    ├── .env
    ├── .gitignore
    ├── CHANGELOG.md
    ├── DEPLOIEMENT.md
    ├── LICENSE
    ├── MANIFEST.in
    ├── pyproject.toml
    ├── pyrightconfig.json
    ├── README.md
    ├── setup.cfg
    ├── setup.py
    └── TEST.md

Fonctionnalités principales

• Génération de QR Codes statiques et dynamiques.
• Construction de payloads conformes EMV.
• Décodage et vérification des payloads QR.
• Calcul automatique du CRC16 pour l'intégrité des données.
• Validation des alias (UUID v4) pour la sécurité des comptes.
• Gestion complète des exceptions avec codes d'erreur structurés.
• Génération de QR Codes en SVG pour export ou impression.

Ce package est conçu pour les systèmes de paiement dans les pays de l'UEMOA.

Intégration

1️⃣ Installation

Dans le dossier racine :

pip install build
python -m build
pip install bceao-pispi-qrcode

2️⃣ Importer la bibliothèque

from bceao_pispi_qrcode import *

3️⃣ Générer un payload QR

    input_data = PispiQrPayloadInput(
        qr_type= PispiQrType.STATIC,              # QR Code dynamique
        alias= '111c3e1b-4312-49ec-b75e-4c8c74c10fd7', # Alias du compte (UUID v4)
        country_code= PispiQrCountry.CI,               # Code pays
        amount= 5000,                             # Montant de la transaction (optionnel)
        reference_label= 'TX000000001',            # Label de référence (optionnel pour statique, obligatoire pour dynamique)
    )
    payload = PispiQrPayload.encode(input_data)

PispiQrPayloadInput

4️⃣ Générer un QR Code en SVG

    svg_qr = PispiQrGenerator.svg(
        payload,
        size= 200,                  # Taille du QR
        logo_size= 40,           # Taille du logo PI-SPI
        background_color= 'white',
        dot_color= 'black',
        margin= 10,
    )

Vous pouvez ensuite l'afficher dans un widget SvgPicture

5️⃣ Décoder un payload QR

result = PispiQrPayload.decode(payload)
print(result.to_dict())
print(result.alias)
print(result.amount)

PispiQrPayloadDecodeResult

6️⃣ Valider un alias

    is_valid = PispiQrPayload.isValidAlias(
        '111c3e1b-4312-49ec-b75e-4c8c74c10fd7'
    )

Exemple

from bceao_pispi_qrcode.pispi_qr_payload import PispiQrPayload
from bceao_pispi_qrcode.pispi_qr_generator import PispiQrGenerator

from bceao_pispi_qrcode.models.enums import PispiQrCountry, PispiQrType
from bceao_pispi_qrcode.models.models import PispiQrPayloadInput


input = PispiQrPayloadInput(
    PispiQrType.DYNAMIC,
    "550e8400-e29b-41d4-a716-446655440000",
    PispiQrCountry.CI,
    amount=2000,
    reference_label= "Tx-caise1"
)

payload = PispiQrPayload.encode(input)

print("================ PAYLOAD ENCODÉ ==============")
print(payload)

decode = PispiQrPayload.decode(payload)
print("================ PAYLOAD DECODÉ ==============")
print(decode.to_dict())

svg = PispiQrGenerator.svg(payload,background_color='white')
print("================ PAYLOAD SVG STRING ==============")
print(svg)

Support

Pour toute question, problème ou contribution :

Email : piz@bceao.int

GitHub : [https://github.com/pi-spi/qrcode-python.git]