Glossaire

Vocabulaire minimal pour lire le reste sans buter. Les termes purement métier sont également définis (plus en détail) dans la spec fonctionnelle (doc/site/content/glossary.mdx).

Entités & domaine

PaymentSession — La ressource centrale. Représente un paiement en cours pour une commande marchand. Contient un montant total, une devise, un statut, et une liste de PaymentLeg. Implémentée dans api/src/domain/session/session.ts. Voir Modèle de domaine.

PaymentLeg (jambe) — Un moyen de paiement au sein d’une session. Deux types : gift_card (carte cadeau) ou psp (carte bancaire via un PSP). La somme des jambes doit couvrir le total. api/src/domain/session/leg.ts.

Split-tender — Le fait de payer une commande avec plusieurs instruments (ex. 50 € en carte cadeau + le reste en CB). C’est la raison d’être de Titreo E-Pay.

Money — Value object { amount, currency }. amount est toujours un entier en centimes, jamais un flottant. api/src/domain/shared/money.ts.

Merchant (marchand) — Le commerçant qui utilise Titreo E-Pay. Multi-tenant : chaque marchand a ses propres configs PSP (chiffrées), API keys, webhook, branding.

Emitter / émetteur — L’entité qui émet une carte cadeau (Titreo, et d’autres). Côté code, représenté par un GiftCardProvider.

PSP (Payment Service Provider) — Prestataire de paiement classique (Stripe, Adyen, PayPlug…). Côté code, un PaymentProvider.

Patterns techniques

Hexagonal (ports & adapters) — Architecture où le métier ne dépend que d’interfaces (ports), implémentées par des adapters concrets. Permet de remplacer Firebird, Stripe, etc. sans toucher au métier. Voir Architecture hexagonale.

Port — Une interface définissant un besoin du métier (ex. SessionRepository, PaymentProvider). Vit dans api/src/application/ports/.

Adapter — Une implémentation concrète d’un port (ex. FirebirdSessionRepo, StripeAdapter). Vit dans api/src/infrastructure/.

Outbox — Table de tâches fiables. Une opération sensible (débit, autorisation, capture, webhook) est inscrite atomiquement dans outbox puis exécutée par un worker, avec retry. Garantit qu’aucune action n’est perdue même si le process meurt. Voir Outbox & orchestration.

Worker — Process séparé qui consomme l’outbox (OutboxPoller) ou nettoie les sessions expirées. Points d’entrée dans api/src/workers/.

Use case — Une opération métier applicative (ex. CreateSession, SubmitSession). Orchestre domaine + ports. Vit dans api/src/application/.

Unit of Work (UoW) — Abstraction de transaction. unitOfWork.run(work) ouvre une transaction Firebird, donne des repos scopés à work, commit en cas de succès, rollback sinon.

Idempotence — Propriété qui garantit qu’exécuter deux fois la même opération a le même effet qu’une seule. Cruciale pour les paiements. Voir Idempotence.

Compensation / rollback — Annuler les effets déjà appliqués quand une étape ultérieure échoue (ex. annuler le débit gift si l’autorisation PSP échoue).

Sécurité

AEAD (AES-256-GCM) — Chiffrement authentifié utilisé pour stocker les credentials PSP et les champs sensibles de l’outbox. api/src/infrastructure/crypto/aead.ts.

KEK (Key Encryption Key) — Clé maîtresse (variable d’env PSP_CONFIG_KEK) qui chiffre les configs PSP par marchand.

HMAC — Signature symétrique des webhooks. La signature x-titreo-signature: t=<ts>,v1=<hex> permet au marchand de vérifier l’authenticité d’un webhook sortant.

Ed25519 — Signature asymétrique du manifest de bootstrap servi au navigateur. La clé privée est côté API, la clé publique est embarquée dans le loader.

API key — Jeton d’authentification marchand, format tep_live_…. Stocké hashé en base, jamais en clair. Porte des scopes (sessions:read, sessions:write, psp:write, …).

Scope — Permission attachée à une API key ou un token, vérifiée par le plugin HTTP require-scope.

Bootstrap navigateur

Manifest — Document signé Ed25519 servi par GET /v1/sessions/:id/bootstrap. Liste les adapters clients à charger (URL + intégrité SRI), leur config publique, et les tokens de thème.

Loader — Le code navigateur (dans checkout-sdk) qui vérifie la signature du manifest puis charge dynamiquement les adapters clients depuis le CDN.

Adapter client — Module ESM signé chargé dans le navigateur (adapter-stripe-client, etc.). Monte l’UI du PSP, tokenize la carte côté client, ne voit jamais de secret serveur.

Capture payload — Objet opaque { kind, data } retourné par un adapter client après tokenisation. Le cœur le transmet à l’adapter serveur correspondant, qui sait décoder son propre kind.