Abstraction du fournisseur sans fuite SDK (kit de développement logiciel) : la limite de la passerelle (Abstraction Du Fournisseur Sans Fuite Sdk Kit DE Developpement Logiciel La Limite DE La Passerelle)

Dans la section précédente, nous avons vu la différence entre la preuve de paiement et l'état du paiement : la preuve provenant du PSP est quelque chose de différent de la propre décision du système. La question de cette section concerne une limite plus fondamentale : l'orchestrateur de paiement doit-il voir le SDK d'une PSP ?

La réponse courte est non. Tout ce que l'Orchestrateur sait devrait être ceci : un paiement demandé, un résultat renvoyé. Quelle PSP a produit ce résultat avec quelle version du SDK et quel client HTTP ; Ce n'est pas le travail de l'orchestrateur, mais la responsabilité de la passerelle du fournisseur.```text Checkout Orchestrator │ ChargeRequest (semantik) ▼ Provider Gateway │ PSP SDK / HTTP client ▼ PSP A veya PSP B

## Concepts à la première mention```text
📦 Provider Gateway
PSP SDK'sını, kimlik doğrulamasını ve provider'a özgü akışları sahiplenen tek servis.

📦 Semantik Arayüz
Orchestrator'ın gördüğü, hiçbir provider tipine referans vermeyen sözleşme.

📦 Anti-Corruption Layer
Dış sistemin veri modelinin, kendi domain dilinizi kirletmesini engelleyen çeviri katmanı.

📦 Adapter
Provider'a özgü isteği semantik isteğe, provider'a özgü yanıtı semantik sonuca çeviren kod.
```La « fuite du SDK » n'est pas une technicité ici : dès le moment où le type `ChargeObject` d'une PSP apparaît dans le code de l'orchestrateur, changer cette PSP ne signifie plus changer un seul fichier, mais toucher au plus profond de l'orchestrateur.

## Pourquoi la fuite du SDK est une dette sournoise

Lors de la mise en place d'une passerelle fournisseur, le plus court est de déplacer les objets SDK de la PSP dans l'orchestrateur tels quels : importer le type `ChargeResponse` et l'utiliser directement, lire un champ, vérifier l'état. C'est rapide la première semaine. Mais dès que ce type entre dans la signature de l'orchestrateur, un lien de version caché se crée entre les deux services : le SDK est mis à jour, le nom de domaine change, l'orchestrateur rencontre une erreur de compilation, ou pire, une erreur de logique silencieuse.```text
❌ Orchestrator kodu
if (pspResponse.charges.data[0].outcome.network_status === 'approved') { ... }

✓ Orchestrator kodu
if (chargeResult.status === ChargeStatus.Captured) { ... }
```La deuxième ligne ne contient aucun nom de fournisseur. La passerelle du fournisseur sait quel domaine de quelle PSP examiner ; L'orchestrateur ne connaît que le résultat sémantique.

## Pourquoi les flux cartes et wallet partagent la même interface mais pas le même flux

Le paiement par carte est généralement synchrone : la demande est émise, le résultat d'autorisation/refus revient en quelques centaines de millisecondes. Les paiements par portefeuille ou par banque (flux où l'utilisateur est redirigé vers la page PSP) sont asynchrones : la première requête renvoie uniquement un statut « en attente » et une URL de redirection ; Le vrai résultat arrive quelques minutes plus tard via un webhook.```text
Kart akışı
  ChargeRequest → [senkron çağrı] → ChargeResult (Captured/Declined)

Wallet akışı
  ChargeRequest → ChargeResult (Pending + redirectUrl)
         ...
  Webhook → ChargeResult (Captured/Failed) [asenkron, sonradan]
```L'interface sémantique représente les deux avec la même forme `ChargeResult` ; Le champ portant la différence est `status` (`Pending` existe comme troisième cas). Orchestrator ne se soucie pas du tout de la question « Cette PSP utilise-t-elle la redirection » ; Il répond uniquement à la question « le résultat est-il désormais définitif ou en attente ? »

## Quels champs ne doivent jamais être traversés lors de la conception de l'interface

Les codes d'erreur spécifiques au fournisseur, les identifiants d'objet spécifiques au fournisseur (par exemple, le format d'identification de charge interne de la PSP), les structures de métadonnées spécifiques au fournisseur ne doivent jamais s'échapper de l'interface sémantique. Au lieu de cela, la passerelle conserve ces informations dans ses propres journaux, dans sa propre zone de diagnostic ; L'orchestrateur renvoie uniquement un résultat correspondant à son identifiant de corrélation.```text
Gateway içinde tutulan (dışarı sızmaz)
  provider_raw_code, provider_object_id, provider_response_headers

Orchestrator'a geçen (semantik)
  ChargeResult { status, amount, currency, providerRef }
````providerRef` est la seule exception : il s'agit d'une chaîne de référence opaque, stockée à des fins de support et de diagnostic, mais sans jamais de branchement.

## Distinctions souvent confuses```text
❌ SDK'yı bir sınıfa sarmak (wrap) yeterlidir
✓ Sarmalama tip sızıntısını çözmez; davranış hâlâ provider'a özgü kalabilir

❌ Abstraction = interface tanımlamak
✓ Abstraction = orchestrator'ın hiçbir zaman bilmemesi gereken şeyi seçmek

❌ Tek PSP varsa abstraction gereksizdir
✓ Tek PSP'de bile abstraction, test edilebilirlik ve mock'lanabilirlik sağlar
```## Différence entre Wrapper et abstraction réelle

| Critère | Emballage fin | Abstraction sémantique |
| --- | --- | --- |
| Fuite de pointe | ont généralement | Aucun |
| L'orchestrateur est-il affecté lors du changement de PSP ? | Oui | Non |
| Qui gère la différence carte/portefeuille | Orchestrateur | Passerelle |
| Testabilité | La maquette PSP doit | Le résultat pseudo-sémantique est suffisant |

## Liste de contrôle lors de la conception de l'interface

1. Le nom, le domaine ou le code d'erreur d'une PSP est-il directement mentionné dans `ChargeResult` ?
2. L'Orchestrateur peut-il gérer correctement le cas `Pending` sans savoir si un flux utilise la redirection ou non ?
3. Une seule ligne du code de l'orchestrateur doit-elle être modifiée lors de l'ajout d'une nouvelle PSP ? L'abstraction fuit si nécessaire.
4. Le test de Gateway peut-il générer tous les états sémantiques sans jamais se connecter à la PSP réelle ?
5. Des champs opaques autres que `providerRef` entrent-ils dans la logique de décision de l'orchestrateur ?

Les réponses oui ou non à ces questions réduisent le débat sur l'architecture d'une question abstraite de « code propre » à un test de limites mesurables.

## Ce qu'il faut retenir de cet article

1. Provider Gateway est l'unique propriétaire du SDK et de tous les détails spécifiques au fournisseur.
2. Orchestrator ne connaît que l'intention (ChargeRequest) et le résultat sémantique (ChargeResult).
3. Les flux de cartes et de portefeuilles partagent la même interface ; La différence est le statut `Pending` dans le champ `status`.
4. Aucun champ opaque ou spécifique au fournisseur autre que `providerRef` ne doit franchir la limite.

> Le véritable test d'une abstraction est que le code de l'orchestrateur ne change pas du tout lorsque vous ajoutez un nouveau fournisseur.

Dans la section suivante, nous déplacerons cette limite du côté des événements : les webhooks générés par la passerelle doivent-ils atteindre l'orchestrateur en tant que charge utile brute du fournisseur ou en tant qu'événement sémantique ?