Ce guide s’adresse aux équipes de la banque qui tient les comptes dédiés des programmes Hajra : agence, back-office des prélèvements, informatique et crédit immobilier. Les captures montrent la plateforme de démonstration, avec des données fictives.
1. Le rôle de la banque
La banque partenaire tient l’argent ; Hajra tient le registre et prépare les opérations. Hajra ne détient jamais les fonds des acheteurs et n’accepte jamais d’espèces.
| Ce que fait la banque | Comment elle le fait avec Hajra |
|---|---|
| Tenir un compte dédié par programme, au nom du promoteur | Le RIB est enregistré par l’équipe Hajra et affiché aux acheteurs |
| Exécuter les prélèvements mensuels des acheteurs | Fichier d’ordres préparé par la plateforme, retour des rejets |
| Recevoir les virements et versements au guichet | Les acheteurs indiquent leur référence HJR dans le libellé |
| Partager le relevé du compte dédié | Fichier CSV ou API, rapprochement automatique par Hajra |
| Libérer les fonds au promoteur selon le chantier | Selon la convention ; l’avancement publié est visible dans la plateforme |
| Financer le solde de l’acheteur à la remise des clés | Attestation de régularité de paiement vérifiable en ligne |
La banque n’a pas besoin de compte sur hajra.tn : elle échange des fichiers, utilise l’API avec une clé dédiée, et vérifie les attestations sur une page publique.
L’acheteur
Apport, mensualités et achats de hajras, avec sa référence HJR.
Le compte dédié du programme
Ouvert à la banque partenaire, au nom du programme. Un compte par programme.
Le promoteur
Finance le chantier, avec la garantie bancaire d’achèvement.
Hajra ne détient jamais l’argent. La plateforme prépare les prélèvements, lit le relevé du compte dédié, rapproche chaque paiement de son contrat et tient le registre des hajras. Jamais d’espèces : chaque dinar est tracé.
L’argent ne circule qu’entre les acheteurs, le compte dédié et le promoteur ; la plateforme échange avec la banque des ordres, des relevés et des rejets.
2. Comptes dédiés et prélèvements
Ouvrir un compte dédié
- Le promoteur ouvre un compte par programme, à son nom, affecté aux paiements des acheteurs de ce programme.
- La banque communique le RIB et l’intitulé à l’équipe Hajra, qui les enregistre sur le programme.
- Le RIB apparaît ensuite dans l’espace de chaque acheteur et sur ses documents : tous les paiements y arrivent.
Le cycle mensuel des prélèvements
- Mandats : chaque acheteur signe en ligne un mandat de prélèvement (RIB de son compte, jour du mois parmi le 1, le 5, le 10 ou le 25, nombre de hajras).
- Ordres : quelques jours avant chaque date, le promoteur génère dans Hajra le fichier d’ordres du jour. Il reprend tous les mandats de cette date, les achats en plus et les prélèvements représentés, au prix en vigueur.
- Exécution : la banque exécute les ordres au crédit du compte dédié.
- Retour : la banque renvoie le résultat, avec les rejets et leur motif. Hajra crédite les hajras des prélèvements passés et prévient les acheteurs rejetés par l’application, SMS et WhatsApp.
- Représentation : une fois le compte de l’acheteur approvisionné, le promoteur représente le prélèvement dans le lot suivant.

Le fichier d’ordres suit aujourd’hui un format de démonstration. Il sera aligné sur le cahier des formats de la banque (télécompensation) lors de la mise en place de la convention : transmettez-le à l’équipe Hajra.
3. Transmettre les relevés
Les crédits du compte dédié (virements et versements des acheteurs) sont rattachés à chaque contrat grâce à la référence HJR que l’acheteur porte dans le libellé. Deux voies, au choix :
Par fichier
Le promoteur importe dans Hajra le relevé exporté de la banque en ligne : un fichier CSV avec trois colonnes, date, libellé, montant. Les débits et les lignes en double sont ignorés.
Par l’API (recommandé dès que possible)
La banque envoie les crédits du jour à POST https://hajra.tn/api/v1/statements, avec une clé portant la permission statements:write :
{
"programId": "…",
"lines": [
{ "bookedAt": "2026-11-20", "label": "VIR AMIRA BEN ALI HJR-27-000123", "amountTnd": 1536.0 }
],
"reconcile": true
}Avec reconcile: true, Hajra rapproche aussitôt chaque ligne de la commande qui porte la même référence et le même montant, crédite les hajras et prévient l’acheteur. Les lignes restantes sont traitées par le promoteur ; au-delà de 7 jours, elles sont signalées à l’équipe Hajra.
Bon à savoir : un envoi quotidien suffit. Renvoyer une ligne déjà reçue ne crée pas de doublon.
4. API et webhooks
La documentation complète est sur hajra.tn/developpeurs, et la spécification OpenAPI sur https://hajra.tn/api/v1/openapi.json.

Obtenir une clé
- Demandez une clé à l’équipe Hajra, à contact@hajra.tn, en précisant les permissions utiles et les programmes concernés.
- La clé
hjr_live_…est affichée une seule fois : conservez-la dans votre coffre de secrets. Hajra n’en garde qu’une empreinte. - Chaque requête la porte dans l’en-tête
Authorization: Bearer hjr_live_…. Une clé se révoque à tout moment ; en cas de doute, demandez-en une nouvelle.
Les points d’accès utiles à la banque
| Requête | Permission | Ce qu’elle donne |
|---|---|---|
GET /programs | programs:read | Programmes, prix de la hajra du jour et prochain prix annoncé, avancement du chantier, compte dédié |
GET /contracts | contracts:read | Contrats, hajras détenues, seuil des clés, mandat de prélèvement |
GET /payments | payments:read | Paiements : apports, prélèvements, virements, rejets |
POST /statements | statements:write | Envoi des crédits du compte dédié, avec rapprochement |
GET /stats | stats:read | Indicateurs pour un tableau de bord |
Les listes sont paginées avec limit (200 au plus) et offset.
Webhooks
Hajra peut appeler une adresse de la banque à chaque événement : réservation signée (contract.created), paiement encaissé (payment.paid), prélèvement rejeté (payment.rejected), nouveau prix annoncé (price.announced). Chaque envoi est signé : l’en-tête X-Hajra-Signature porte t=<horodatage>,v1=<HMAC-SHA256>, calculé sur <horodatage>.<corps> avec le secret whsec_… remis à la création. Refusez tout envoi dont la signature ne correspond pas ou dont l’horodatage a plus de 5 minutes.
5. Financer le solde et vérifier une attestation
À la remise des clés, l’acheteur a payé 25 % du logement, chaque mois, sur un compte que la banque tient elle-même. Pour le crédit des 75 % restants, il présente une attestation de régularité de paiement, éditée depuis son espace.
Ce que dit l’attestation
- le contrat, le logement et le programme ;
- les hajras payées sur le total et le montant total payé ;
- la date du premier paiement et le nombre de paiements encaissés ;
- les prélèvements présentés, dont rejetés, et le taux de régularité ;
- le rythme mensuel convenu et la situation au regard du seuil des clés.
La vérifier en 30 secondes
- Ouvrez hajra.tn/attestation (lien « Vérifier une attestation » en bas de chaque page du site).
- Saisissez le code imprimé en bas de l’attestation, puis Vérifier.
- Attestation authentique : le contrat, la date d’émission, les hajras payées et le montant s’affichent ; comparez-les au document. Code non reconnu : le document n’a pas été émis par Hajra ou a été modifié.

Les chiffres sont ceux du jour d’émission. Pour une situation à jour, demandez une nouvelle attestation à l’acheteur. Vous pouvez aussi rapprocher les montants de vos propres relevés du compte dédié. L’attestation ne vaut pas offre de crédit : la décision reste celle de la banque.
Questions fréquentes
Hajra peut-elle déplacer l’argent du compte dédié ? Non. Hajra prépare des fichiers et tient le registre ; seuls la banque et le titulaire du compte, selon la convention, déplacent les fonds.
Que faire d’un crédit sans référence HJR ? Transmettez-le comme les autres : il apparaît chez le promoteur, qui l’affecte à un acheteur ou le met de côté.
Qui contacter ? L’équipe Hajra, à contact@hajra.tn, pour les clés d’API, les formats de fichiers et la convention.