Traitement efficace des paiements une seule fois (Traitement Efficace Des Paiements Une Seule Fois)

Dans la section précédente, nous avons vu que le pipeline de récupération fonctionne d'abord sur le principe de l'automatisation et que les runbooks basés sur des preuves entrent en jeu dans les murs d'unicité. Cette section aborde les garanties de messages qui sous-tendent le pipeline — et l'idée fausse la plus courante du secteur : la livraison exactement une fois.

Les courtiers vendeurs promettent une « sémantique exactement une fois ». Le fait est que dans un système distribué, il n'est pas physiquement garanti qu'un message sera traité exactement une fois. Le réseau tombe en panne, le travailleur plante, le courtier renvoie. La question n’est pas « combien de fois le message est-il arrivé » ; combien de fois le résultat du travail s'est-il produit.```text Exactly-once messaging → imkansız (at-least-once + failure = duplicate) Effectively-once outcome → mümkün (defense in depth)

## Concepts à la première mention```text
📦 At-Least-Once Delivery
Mesaj en az bir kez ulaşır; ağ hatasında tekrar gönderilebilir.

📦 Effectively-Once
Mesaj birden fazla kez işlense bile iş sonucu (charge, refund, order) yalnızca bir kez gerçekleşir.

📦 Defense in Depth
Tek bir mekanizmaya güvenmek yerine, birden fazla bağımsız koruma katmanı.

📦 Idempotent Consumer
Aynı mesajı ikinci kez aldığında aynı sonucu üreten, yan etki yaratmayan tüketici.
```La messagerie exactement une fois n'est pas une fonctionnalité de courtier ; Il s’agit d’une conception de système axée sur l’efficacité.

## Exactement une fois, pourquoi mentir

Un travailleur reçoit le message, le traite, envoie un accusé de réception, mais l'accusé de réception est perdu dans le réseau. Le courtier renvoie le message. Le travailleur traite une deuxième fois. C'est la nature de la livraison au moins une fois ; Peu importe à quel point le courtier prétend « exactement une fois », la duplication du côté du consommateur est inévitable.```text
Worker mesajı işler → sonuç: Captured
Ack ağda kaybolur
Broker mesajı tekrar gönderir
Worker tekrar işler → sonuç: ??? (çift charge riski)
```Le problème n’est pas de savoir combien de fois le message arrive ; c'est ce qui arrive à la seconde venue. S’il n’y a aucun effet secondaire lors de la deuxième visite, cela signifie que le traitement a été réalisé efficacement une fois.

## Défense en profondeur : une seule couche ne suffit pas

En fait, le résultat commercial est une combinaison de couches complémentaires. Ni l’un ni l’autre ne suffit ; Tous ensemble produisent le résultat « un message qui arrive au moins une fois a un effet au plus une fois ».```text
Katman 1: Idempotency key (API)
  → aynı key ile ikinci charge isteği reddedilir

Katman 2: Consumer dedup (messaging)
  → aynı message id ikinci kez işlenmez

Katman 3: DB uniqueness constraint
  → aynı idempotency key ile ikinci satır yazılamaz

Katman 4: Outbox pattern
  → event yalnızca transaction commit ile birlikte yayınlanır

Katman 5: Reconciliation
  → katman 1-4'ün kaçırdığı drift'i periyodik olarak düzeltir
```Si une couche échoue, l’autre prend le relais. Si la clé d'idempotence est omise, la contrainte d'unicité est prise en compte ; La réconciliation est corrigée si la contrainte est omise.

## La question pour chaque couche est différente

| Couche | Question | Protégé |
| --- | --- | --- |
| Clé d'idempotence | Encore la même intention ? | Double facturation au niveau de l'API |
| Déduplication du consommateur | Encore le même message ? | Double transaction au niveau de la messagerie |
| Contrainte d'unicité | Deuxième ligne avec la même clé ? | Double enregistrement au niveau de la base de données |
| Boîte d'envoi | L'événement a-t-il été publié sans engagement ? | Perte ou événement anticipé |
| Réconciliation | Local et PSP sont-ils incompatibles ? | Tout ce qui échappe |

## Comment écrire un consommateur idempotent

Règle du consommateur idempotent : même entrée, même sortie ; Aucun effet secondaire au deuxième appel.```text
PaymentCaptured webhook (messageId=wh_991)
  → dedup tablosuna bak: wh_991 işlendi mi?
  → evet → skip (log: duplicate suppressed)
  → hayır → finalize, dedup tablosuna yaz
```L'étape de finalisation elle-même doit être idempotente : si le paiement est déjà `Captured`, aucun événement ne doit être émis à nouveau, aucune commande ne doit être recréée. La table Dedup préserve la couche de messagerie ; le contrôle de l'état du terminal protège la logique métier.

## Boîte d'envoi : l'événement et l'état sont dans la même transaction

Le modèle de boîte d'envoi résout le dilemme « état mis à jour mais événement non publié » ou « événement publié mais état non mis à jour ». L'événement est écrit dans la table de boîte d'envoi avec la transaction locale ; Un éditeur distinct lit la boîte d'envoi et l'envoie au courtier.```text
BEGIN TRANSACTION
  UPDATE payment SET status=Captured
  INSERT INTO outbox (event=PaymentCaptured, paymentId=8812)
COMMIT
  → publisher outbox'ı okur → broker'a gönderir
  → gönderim başarılı → outbox satırını siler
```La boîte d'envoi ne fournit pas de messagerie unique, mais elle garantit la cohérence entre l'état et l'événement. La réconciliation rattrape ceux qui se sont échappés de la boîte d'envoi.

## Distinctions souvent confuses```text
❌ Broker exactly-once = sistem exactly-once
✓ Broker dedup + consumer idempotency + DB constraint = effectively-once

❌ Idempotency key her yerde yeterli
✓ Idempotency key API'yi korur; webhook ve async worker ayrı katman ister

❌ Effectively-once = perfect system
✓ Effectively-once = iş sonucu bir kez; tutarsızlık penceresi reconciliation ile kapanır
```## Garantie de livraison par rapport aux résultats commerciaux

| Garantie | Que promet-il ? Est-ce suffisant pour les paiements ? |
| --- | --- | --- |
| Au plus une fois | Une fois le message perdu, il peut être perdu | Non : paiement perdu |
| Au moins une fois | Le message peut être dupliqué au moins une fois | Non – seul |
| Exactement une fois (courtier) | Théoriquement, c'est pratiquement une rupture du côté du consommateur | Non |
| Effectivement une fois (système) | Résultat du travail une fois | Oui |

## Liste de contrôle efficace une fois

1. Les demandes de facturation API sont-elles protégées par une clé d'idempotence ?
2. Existe-t-il une déduplication de l'ID de message dans les webhooks et les consommateurs asynchrones ?
3. Existe-t-il une contrainte d'unicité sur la clé d'idempotence dans la table de paiement ?
4. Le changement d'état et l'événement sont-ils diffusés dans la même transaction que le modèle de boîte d'envoi ?
5. Le gestionnaire de finalisation saute-t-il sans réopérer dans l'état du terminal ?
6. La réconciliation recherche-t-elle périodiquement les dérives manquées par les couches 1 à 5 ?

## Ce qu'il faut retenir de cet article

1. La messagerie exactement une fois est un mensonge ; au moins une fois + échec = la duplication est inévitable.
2. En effet, une fois que des résultats commerciaux sont possibles grâce à une défense en profondeur, une seule couche ne suffit pas.
3. Chaque niveau de protection répond à une question différente ; ils doivent tous travailler ensemble.
4. La réconciliation est le dernier niveau ; Il complète, et non remplace, les couches précédentes.

> Même si votre courtier promet une seule fois, votre système de paiement ne devrait pas le croire : ce qu'il devrait croire, c'est construire efficacement les résultats commerciaux en profondeur.

Dans la section suivante, nous passons à la synthèse de ce parcours en 22 parties : liste de contrôle de conception du moteur de paiement de production.