SofizPay Logo

SofizPay

SofizPay Logo
SofizPay
Documentation Technique
API de Paiement de Factures

Paiement de Factures de Services Publics en Algérie

Payez vos factures de services publics algériens (Sonelgaz, Algérie Télécom, ADE, SEAAL) rapidement et en toute sécurité via notre API unifiée

Flux Standard de Paiement en 3 Étapes

Étape 1: Récupération de la Facture en Direct

Vérifier le montant dû, les détails de la facture et le jeton crypté avant le paiement.

POST /api/operations/fetch/{service}/
Étape 2: Pré-Sauvegarde des Métadonnées de Suivi

Enregistrer les métadonnées clés (clé EBB Sonelgaz, code de paiement ADE, numéro AT, réf SEAAL).

POST /api/operations/facture-data/
Étape 3: Soumission du Règlement Financier

Exécuter l'opération financière avec votre clé secrète chiffrée (encrypted_sk).

POST /services/operation_post

Chiffrement RSA et Authentification SofizPay (RSA-OAEP)

Chiffrement de la Clé Secrète SofizPay (encrypted_sk)

RSA-OAEP SHA-256Base64 (344 caractères)Emplacement : Corps JSON

Pour sécuriser la clé secrète SofizPay et éviter sa transmission en clair, toutes les requêtes de consultation et de paiement de factures exigent le chiffrement de la clé secrète via la clé publique RSA officielle SofizPay (RSA-OAEP SHA-256), transmise en Base64 dans le corps JSON sous encrypted_sk.

Clé Publique RSA 2048-bit Officielle

bash
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv9toBr7vZ4XIkVzlzdGR
vNVaKw7A9Z3/Vnq3bK8fLaaUTmoweL3CEKSbz1lxYUjzuRzY/nmDuCpPS/7t0i5c
kWRifPaPgIoiUFr1fGLzjN+cttxtvbPQof2Zuxllbq5ox+XyZpc1eo8PjwhRobCB
djDZ1iSV1VkhOWanrnNXeXFzUnRYHQUZmQ8FWOFQ8D9vUZanmq/ZJ6nJ4SZoj2lV
dKrLBbh/MWtn9MmyrPrywoJYCnc7c+ylJIWnAhNv4jTafB5bqDTd6oSElV9lQqPf
diO93j+Q/uBoAZQZ2EqWY0E4Ooz4Dd9dHl7EiNiAh19G9VTcBFN/QfXOdyCGajwC
WwIDAQAB
-----END PUBLIC KEY-----
Vous pouvez intégrer cette clé publique ou la récupérer dynamiquement via GET https://epay.sofizpay.com/api/operations/public-key/

Exemples de code de chiffrement

python
1import base64
2from cryptography.hazmat.primitives.asymmetric import padding
3from cryptography.hazmat.primitives import serialization, hashes
4from cryptography.hazmat.backends import default_backend
5
6SOFIZ_PUBLIC_KEY_PEM = """-----BEGIN PUBLIC KEY-----
7MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv9toBr7vZ4XIkVzlzdGR
8vNVaKw7A9Z3/Vnq3bK8fLaaUTmoweL3CEKSbz1lxYUjzuRzY/nmDuCpPS/7t0i5c
9kWRifPaPgIoiUFr1fGLzjN+cttxtvbPQof2Zuxllbq5ox+XyZpc1eo8PjwhRobCB
10djDZ1iSV1VkhOWanrnNXeXFzUnRYHQUZmQ8FWOFQ8D9vUZanmq/ZJ6nJ4SZoj2lV
11dKrLBbh/MWtn9MmyrPrywoJYCnc7c+ylJIWnAhNv4jTafB5bqDTd6oSElV9lQqPf
12diO93j+Q/uBoAZQZ2EqWY0E4Ooz4Dd9dHl7EiNiAh19G9VTcBFN/QfXOdyCGajwC
13WwIDAQAB
14-----END PUBLIC KEY-----"""
15
16def encrypt_sofizpay_sk(secret_key: str, public_key_pem: str = SOFIZ_PUBLIC_KEY_PEM) -> str:
17    """Encrypts SofizPay Secret Key (S...) using RSA-OAEP SHA-256 for encrypted_sk"""
18    pub_key = serialization.load_pem_public_key(
19        public_key_pem.strip().encode('utf-8'),
20        backend=default_backend()
21    )
22    ciphertext = pub_key.encrypt(
23        secret_key.strip().encode('utf-8'),
24        padding.OAEP(
25            mgf=padding.MGF1(algorithm=hashes.SHA256()),
26            algorithm=hashes.SHA256(),
27            label=None
28        )
29    )
30    return base64.b64encode(ciphertext).decode('utf-8')
31
32# Example usage in API request body:
33# payload = {"encrypted_sk": encrypt_sofizpay_sk("S..."), "customer_num": "00000000000"}

Phase 1 : API d'interrogation des factures (Fetch Bills)

POST https://epay.sofizpay.com/api/operations/fetch/{service}/

Ce point de terminaison permet d'interroger en temps réel les factures impayées directement auprès des organismes publics algériens, garantissant la vérification du montant exact avant le règlement.

POSThttps://epay.sofizpay.com/api/operations/fetch/sonelgaz/
Content-Type: application/jsonAuth : encrypted_sk (Corps JSON)

Requête d'interrogation (Fetch Request)

cURL
bash
curl --location 'https://epay.sofizpay.com/api/operations/fetch/sonelgaz/' --header 'Content-Type: application/json' --data '{
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "customer_num": "00000000000"
}'

Exemple de réponse (Factures impayées)

200 OK
json
{
  "bills": [
    {
      "value": "000000000000",
      "label": "[1500.00 DZD] [000000000000]",
      "amount": 1500.00,
      "bill_number": "000000000000",
      "customer_num": "00000000000",
      "ebb": "000",
      "isIdoom": false
    }
  ],
  "customer_num": "00000000000"
}
Remarque : La réponse renvoie un tableau bills contenant les détails de la facture et le montant dû en DZD, nécessaires pour l'enregistrement des métadonnées et le paiement final.

Paramètres de l'API Fetch

ParamètreEmplacementTypeDescriptionRequis Pour
encrypted_skCorps (Body)stringClé secrète chiffrée pour l'authentification et l'exécutionTous les services
customer_numCorps (Body)stringNuméro client Sonelgaz à 11 caractères (ex. 00000000000) extrait de la facture ou du code Data MatrixSonelgaz
bill_numberCorps (Body)stringNuméro de facture Sonelgaz (optionnel pour vérification ciblée)Sonelgaz (Optionnel)
ebbCorps (Body)stringClé de vérification EBB extraite du code-barres Sonelgaz (optionnel)Sonelgaz (Optionnel)
ndCorps (Body)stringNuméro de désignation de la ligne fixe / Idoom Algérie Télécom (ND ex. 021000000)Algérie Télécom
c_paiementCorps (Body)stringCode de paiement électronique (Code Paiement) figurant sur la facture d'eau ADEADE
customer_numCorps (Body)stringNuméro client ou référence de contrat pour la SEAAL (Alger et Tipaza)SEAAL

Étape 2: Pré-Sauvegarde des Métadonnées de Suivi — POST /api/operations/facture-data/

Enregistrer les métadonnées clés (clé EBB Sonelgaz, code de paiement ADE, numéro AT, réf SEAAL).

bash
curl --location 'https://epay.sofizpay.com/api/operations/facture-data/' --header 'Content-Type: application/json' --data '{
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "facture_number": "000000000000",
    "bill_number": "000000000000",
    "ebb": "000",
    "customer_number": "00000000000"
}'

Étape 3: Soumission du Règlement Financier — POST /services/operation_post

Sonelgaz

Sonelgaz

Société Nationale de l'Électricité et du Gaz

Exemple de Requête de Paiement

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 1500.00,
    "operator": "sonelgaz",
    "offer": "sonelgaz",
    "bill": "000000000000",
    "customerId": "",
    "customernumber": " ",
    "ebb": " "
}'
Opérateur de Service
"sonelgaz"
Champs Requis
encrypted_skamountoperator: "sonelgaz"offer: "sonelgaz"billebbcustomerId
Algérie Télécom

Algérie Télécom

Algérie Télécom (Idoom Fixe & Fibre)

Exemple de Requête de Paiement

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 645.00,
    "montant": 645.00,
    "operator": "AT",
    "offer": "AT",
    "phone": "021000000",
    "bill": "021000000",
    "bill_number": "021000000",
    "memo": "00:021000000"
}'
Opérateur de Service
"AT"
Champs Requis
encrypted_skamountmontantoperator: "AT"offer: "AT"phonebillmemo: "00:nd"
ADE

ADE

Algérienne Des Eaux

Exemple de Requête de Paiement

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 2500,
    "operator": "ade",
    "offer": "ade",
    "bill": "0000000000",
    "c_paiement": "0000000000",
    "customerId": "0000000000"
}'
Opérateur de Service
"ade"
Champs Requis
encrypted_skamountoperator: "ade"offer: "ade"billc_paiementcustomerId
SEAAL

SEAAL

Société des Eaux et de l'Assainissement d'Alger

Exemple de Requête de Paiement

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 1800,
    "operator": "seaal",
    "offer": "SEAAL",
    "phone": "00000000",
    "bill": "00000000",
    "memo": "00:00000000"
}'
Opérateur de Service
"seaal"
Champs Requis
encrypted_skamountoperator: "seaal"offer: "SEAAL"phonebillmemo: "00:num"

Paramètres de la Requête

ParamètreTypeDescriptionRequis Pour
encrypted_skstringClé secrète chiffrée pour l'authentification et l'exécutionTous les services
amountnumberMontant du paiement en DZDTous les services
operatorstringFournisseur de service: sonelgaz, AT, ade, ou seaalTous les services
offerstringType d'offre de service: sonelgaz, AT, ade, ou SEAALTous les services
billstringNuméro de facture ou référence de paiementTous les services
ebbstringClé de vérification EBB extraite du code-barres SonelgazSonelgaz
c_paiementstringCode de paiement électronique de la facture d'eau ADEADE
phonestringNuméro de téléphone fixe ou identifiant (Algérie Télécom, SEAAL)AT / SEAAL
memostringMémo de suivi au format 00:{numéro} (Algérie Télécom, SEAAL)AT / SEAAL
montantnumberMontant en DZD spécifiquement transmis pour Algérie Télécom / IdoomAlgérie Télécom

Réponse de Confirmation de Paiement (200)

json
{
    "status": "success",
    "message": "Bill payment completed successfully",
    "operation_id": "OP_DZ_000000000000",
    "transaction_id": "TXN_000000000",
    "transaction_status": "confirmed"
}

Note: Le paiement est traité via la passerelle SofizPay et un accusé de confirmation est généré immédiatement.