POC · Connecteur Temenos T24 (Kotlin)

Code source : poc-temenos-connector/ dans le monorepo VitaKYC.

Cinquième POC technique : le connecteur Temenos Transact, le core banking #1 des banques MENA (adopté par BH, Attijari, Biat, Zitouna, CIB Égypte, QNB, Emirates NBD, etc.). Lecture des transactions via l’IRIS Enquiry REST API et normalisation vers le modèle pivot VitaKYC.

1. Pourquoi Temenos en priorité

Temenos Transact (ex-T24) est dominant en MENA :

Banque	Core banking	Région
Banque de l’Habitat (BH)	Temenos T24	Tunisie
Attijari Bank TN / Attijariwafa MA	Temenos T24	TN / MA
Biat	Temenos T24	Tunisie
STB	Temenos T24	Tunisie
Zitouna	Temenos T24	Tunisie
CIB Égypte	Temenos T24	Égypte
QNB	Temenos Transact	UAE / Qatar
Emirates NBD (partie)	Temenos	UAE

Un connecteur Temenos = clé de voûte du module AML Transaction Monitoring pour ~60 % des clients cibles VitaKYC. Sans ça, pas d’ingestion réel-temps, pas de TxMon vendable.

2. Trois canaux d’intégration Temenos — notre choix

Canal	Maturité	Complexité	Temps réel	Choix VitaKYC
TOCF (MQ / JMS)	Legacy	Élevée (IBM MQ)	Oui	V1+ si client MQ-only
OFS (Open Financial Service)	Stable	Moyenne (protocole texte)	Oui	Non prioritaire
IRIS / Infinity REST API	Moderne (R21+)	Faible	Pull périodique	✅ MVP

Décision : IRIS REST est notre voie de déploiement par défaut. TOCF / MQ sera livré en V1 pour les banques encore en R18-R20.

3. Architecture du POC

4. Enquiries Temenos consommées

4.1 `STMT.ENT.BOOK` — écritures comptables (core transactionnel)

Écritures de compte détaillées sur une période. Équivalent au camt.053 / extrait de compte, en format natif T24.

Champs clés récupérés et normalisés :

Champ T24	Canonical VitaKYC
`transactionReference`	`txId`
`valueDate` (YYYYMMDD)	`timestamp` (ISO 8601)
`accountId`	`account.id`
`currencyCode`	`account.currency`
`amountLcy`	`amount.value`
`drCrMarker` `D`/`C`	`direction` `DEBIT`/`CREDIT`
`transactionCode`	`type` via mapping (cf. §5)
`channel`	`channel` via mapping
`narrative`	`purpose.description`
`theirReference`	`endToEndRef`
`counterparty_*`	`counterparty.*`

4.2 `CUSTOMER.POSITION` — enrichissement KYC

Fiche client T24 pour lier la transaction à un customer_id et enrichir le risque :

Champ	Usage
`customerId`, `fullName`, `nationality`	Identification
`customerStatus` (ACTIVE/DORMANT/CLOSED)	Alerte “dormant awakening”
`riskLevel` (LOW/MEDIUM/HIGH)	Pondération du scoring AML
`legalId` (CIN / RNE)	Lien avec KYC VitaKYC
`sectorCode`	Segmentation sectorielle

5. Mapping codes T24 → types canoniques

Table non exhaustive (à compléter au MVP par les experts T24 du client) :

T24 `transactionCode`	VitaKYC `type`
`1100`	`CASH_WITHDRAWAL`
`1101`	`CASH_DEPOSIT`
`1110`, `1111`, `1112`	`TRANSFER`
`1200`	`CARD_PAYMENT`
`1500`	`FX`
`2100`	`LOAN_DISBURSEMENT`
`2200`	`LOAN_REPAYMENT`
`3500`	`FEES`
`3800`	`INTEREST`
(autre)	`UNKNOWN`

6. Tests (11 cas passants)

Sortie ./gradlew test :

TemenosClientTest > OAuth2 · obtention du token avec client_credentials PASSED
TemenosClientTest > OAuth2 · token caché entre appels (pas de refetch) PASSED
TemenosClientTest > OAuth2 · erreur HTTP 401 → AuthFailed PASSED
TemenosClientTest > STMT.ENT.BOOK · parse 3 transactions avec mapping complet PASSED
TemenosClientTest > STMT.ENT.BOOK · Authorization Bearer + query params passés PASSED
TemenosClientTest > Enquiry introuvable (404) → EnquiryNotFound PASSED
TemenosClientTest > 429 → RateLimited PASSED
TemenosClientTest > CUSTOMER.POSITION · mapping complet PASSED
TemenosClientTest > Mapper · code T24 1112 (Transfer Out) → TRANSFER + DEBIT PASSED
TemenosClientTest > Mapper · dérive pays counterparty depuis BIC si absent PASSED
TemenosClientTest > Mapper · code T24 inconnu → type UNKNOWN (pas d'exception) PASSED
BUILD SUCCESSFUL

Chaque test utilise MockWebServer avec des fixtures JSON réalistes dans src/test/resources/fixtures/.

7. Sécurité et robustesse

OAuth2 client_credentials avec cache en mémoire + refresh 60 s avant expiration.
mTLS (en option, à activer selon politique tenant) via OkHttp.
Pagination automatique tant que body.size < header.totalSize.
Erreurs typées : AuthFailed, EnquiryNotFound, RateLimited, Transport, Parse → service métier peut prendre des décisions fines.
Timeout configurable (15 s par défaut).
Retry automatique sur 401 (possibilité token expiré) — 1 retry max pour éviter boucle.

8. Fixtures de référence

Le fixture stmt-ent-book-page1.json reproduit le scénario pass-through du STR goAML (même entreprise ACME Trading, mêmes counterparties BVI/PA/AE) — ce qui démontre que la chaîne complète fonctionne :

Temenos (ACME transactions)
     ↓ STMT.ENT.BOOK
     ↓ TemenosToCanonical
CanonicalTx (DEBIT, 840k USD, AE)
     ↓ aml-svc rule engine (pass-through, offshore, sanctions)
alert open
     ↓ compliance officer review + decision = true positive
     ↓ goAML STR builder
STR XML déposé à la FIU

Un seul et même scénario traverse les 3 POCs Kotlin (Temenos → Normalizer → goAML) et le module TCR FATCA — preuve intégrée de cohérence produit.

9. Exemple d’usage

val config = TemenosConfig(
    baseUrl = "https://temenos.bh.tn",
    tokenUrl = "https://temenos.bh.tn/oauth2/token",
    clientId = System.getenv("TEMENOS_CLIENT_ID"),
    clientSecret = System.getenv("TEMENOS_CLIENT_SECRET"),
    companyId = "TN00100",
)

val client = TemenosClient(config)

val entries = client.fetchStatementEntries(
    accountId = "AA2026000001",
    fromDateYmd = "20260401",
    toDateYmd = "20260422",
)

val canonicalTxs = entries.map {
    TemenosToCanonical.mapTransaction(it, customerId = "C123456")
}

// canonicalTxs → publier sur Kafka topic tx.normalized
// → aml-svc déclenche rules + ML

10. Roadmap pour la production

Support TOCF / MQ (IBM MQ + JMS) — livré en V1 pour clients encore en R18-R20.
Support OFS (texte + UTF-8) pour transactions unitaires temps réel.
Retry exponentiel + circuit breaker (Resilience4j) sur erreurs 5xx.
Pagination streaming : yield au fur et à mesure pour éviter de charger tout le batch en mémoire.
Mapping codes T24 : export depuis la table TRANSACTION.TYPE de chaque banque cliente (chaque banque peut avoir des codes custom).
Test avec vraie instance T24 (Temenos Cloud Sandbox) avant passage en prod chez la banque.
Intégration cert mTLS client-side.
Observabilité : métriques temenos_fetch_latency_ms, temenos_errors_total{type}, temenos_tx_ingested_total.

11. Pourquoi ce POC sécurise le marché TN

BH, Biat, Attijari TN, STB, Zitouna = tous Temenos. Ce POC = preuve concrète de notre capacité à intégrer sans développement custom côté banque (juste ouverture de l’API IRIS).
Courbe d’intégration : avec l’API IRIS, on passe de 3-6 mois de dev d’intégration (cas MQ/TOCF) à 2-4 semaines seulement.
Argument pricing : ce POC justifie notre module TxMon en tant que add-on premium récurrent (800 €/mois à 15 000 €/an selon plan).

POC validé le 2026-04-22 · 11 tests passants · OkHttp + MockWebServer + kotlinx-serialization.