hajra

Guide d’utilisation · Banque partenaire

Guide de la banque partenaire

Comptes dédiés, prélèvements, relevés, API et webhooks, vérification des attestations pour le crédit du solde.

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 banqueComment elle le fait avec Hajra
Tenir un compte dédié par programme, au nom du promoteurLe RIB est enregistré par l’équipe Hajra et affiché aux acheteurs
Exécuter les prélèvements mensuels des acheteursFichier d’ordres préparé par la plateforme, retour des rejets
Recevoir les virements et versements au guichetLes 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 chantierSelon la convention ; l’avancement publié est visible dans la plateforme
Financer le solde de l’acheteur à la remise des clésAttestation 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.

Prélèvement, virement, versement en agence

Le compte dédié du programme

Ouvert à la banque partenaire, au nom du programme. Un compte par programme.

Selon la vente sur plan (loi n° 90-17)

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é

  1. Le promoteur ouvre un compte par programme, à son nom, affecté aux paiements des acheteurs de ce programme.
  2. La banque communique le RIB et l’intitulé à l’équipe Hajra, qui les enregistre sur le programme.
  3. 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

  1. 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).
  2. 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.
  3. Exécution : la banque exécute les ordres au crédit du compte dédié.
  4. 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.
  5. Représentation : une fois le compte de l’acheteur approvisionné, le promoteur représente le prélèvement dans le lot suivant.
Page Prélèvements de l’espace promoteur
Côté promoteur : le lot d’ordres du jour, généré avant chaque date de prélèvement.

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.

Page Développeurs de hajra.tn
La documentation de l’API : authentification, points d’accès et webhooks.

Obtenir une clé

  1. Demandez une clé à l’équipe Hajra, à contact@hajra.tn, en précisant les permissions utiles et les programmes concernés.
  2. La clé hjr_live_… est affichée une seule fois : conservez-la dans votre coffre de secrets. Hajra n’en garde qu’une empreinte.
  3. 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êtePermissionCe qu’elle donne
GET /programsprograms:readProgrammes, prix de la hajra du jour et prochain prix annoncé, avancement du chantier, compte dédié
GET /contractscontracts:readContrats, hajras détenues, seuil des clés, mandat de prélèvement
GET /paymentspayments:readPaiements : apports, prélèvements, virements, rejets
POST /statementsstatements:writeEnvoi des crédits du compte dédié, avec rapprochement
GET /statsstats:readIndicateurs 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

  1. Ouvrez hajra.tn/attestation (lien « Vérifier une attestation » en bas de chaque page du site).
  2. Saisissez le code imprimé en bas de l’attestation, puis Vérifier.
  3. 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é.
Résultat de la vérification d’une attestation
Une attestation authentique : contrat, date d’émission, hajras payées et montant attesté.

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.