Intégration avec les passerelles de paiement : flow, retours, reconciliation

Texte intégral de l'article

💡 18+. Matériel technique pour les plates-formes iGaming, les opérateurs et les fournisseurs de paiement. Pas un appel au jeu.

1) Rôle de l'orchestre payant dans iGaming

La caisse est une « artère » de la plate-forme : elle accepte les dépôts, initie les cashouts, traite les retours/chargeback et est synchronisée avec le portefeuille (Ledger). L'erreur ou le retard se transforme rapidement en risque financier et de conformité. La tâche de l'architecture est un flux de trésorerie rapide et prouvé en cas de défaillance.

2) Flow de base avec PSP (carte d'état)

2. 1 Dépôt (carte de fortune)

1. create_intent (INITIATED) → créer une intention de paiement du côté de la plate-forme.

2. autorize (AUTORISÉ) → hold dans PSP (en option - capture à la fois).

3. 3-DS/AVS/KYC hooks → contrôles de risque/réglementation.

4. capture (CAPTURED) → passation par profits et pertes ; portefeuille de crédit.

5. failed/expired/canceled → l'indemnisation et la fermeture de l'intendant.

2. 2 Cache (withdrawal)

request → validation RG/AML/limites → payout_initiated → payout_settled/failed.

Confirmations « quatre yeux » pour VIP/grandes sommes, limites de velocity et géo-règles.

2. 3 Void / Refund

void : annulation avant capture (supprime hold).

refund : retour partiel/complet après capture.

Pour les schémas de cartes, des statuts distincts « submitted/processed ».

Invariant : La vérité sur l'équilibre du joueur est un portefeuille. Les formats PSP ne changent pas directement la balance ; seulement par l'équipe 'wallet. credit/debit 'avec idempotence.

3) Idempotence, clés et retraits

Chaque opération write porte "X-Idempotency-Key" et "X-Trace-Id'.

La composition de la clé est liée aux paramètres métiers (par exemple, 'intent _ id + amount + currency').

Une répétition avec la même clé → le même résultat (200 avec l'ancien body).

Retrai avec exponentielle backoff + jitter, dur 'timeout/deadline'.

4) 3-DS, AVS, velocity, antifrode

3-DS 2. x : de préférence challenge-flow avec device-fingerprinting ; stocker ECI/CAVV/DSTransID dans le journal.

AVS/CVV : incluez les codes de vérification dans la télémétrie et les règles de routage.

Velocity : limites par montant/nombre/cartes/ASN/appareils (1h/24h/7d).

Signaux comportementaux : décalage géo/fuseau horaire, beaucoup de cartes/peu de dépôts, cache rapide.

5) Routage et cascades PSP

Règles : géo, bandes BIN, type de carte, coût, conversion, risque.

Cascade : PSP1 → PSP2 en cas de panne, sans perte de panier (idempotent token).

A/B/multi-armed bandit : optimisation de la conversion et du coût.

Fail-open/closed : pour les erreurs douteuses, appliquez safe-default (par exemple, répétez via un autre merchant), mais pas pour duble-capture.

6) Contrats API (fragments de référence)

6. 1 Création d'un intendant de dépôt


POST /v1/cashier/intents
Headers: X-Idempotency-Key, X-Trace-Id
{
"player_id":"p_123",  "amount":{"amount":50. 00,"currency":"EUR"},  "method":"card",  "metadata":{"brand_id":"A","region":"EU"}
}
→ 201 { "intent_id":"pi_001","status":"INITIATED" }

6. 2 Autorisation/Capture


POST /v1/cashier/intents/pi_001/authorize
→ 200 { "status":"AUTHORIZED","psp_ref":"psp_aa1","eci":"05","cavv":"…" }

POST /v1/cashier/intents/pi_001/capture
→ 200 { "status":"CAPTURED","capture_id":"cap_001" }

6. 3 Void / Refund


POST /v1/cashier/captures/cap_001/refunds
{ "refund_id":"rf_001", "amount":{"amount":10. 00,"currency":"EUR"} }
→ 202 { "status":"REFUND_SUBMITTED" }

6. 4 Webhooks PSP → plateforme (signé par HMAC/EdDSA)


POST /webhooks/psp
X-Signature: sha256=…
{
"event":"payment. captured",  "psp_ref":"psp_aa1",  "intent_id":"pi_001",  "amount":{"minor_units":5000,"currency":"EUR"},  "occurred_at":"2025-10-23T12:05:01Z",  "idempotency_key":"cap_001"
}

Le récepteur doit : vérifier la signature/timstamp/nonce, dédupliquer 'event _ id', corréler avec 'intent _ id'.

7) Synchronisation avec le portefeuille (Ledger)

Après capture : commande 'wallet. credit '(idempotent) → le solde du joueur.

Refund: `wallet. debit '(ou'wallet. hold_release' pour void).

Cache : 'wallet. debit` → `payout` в PSP; après le webhook 'payout _ settled' - fermeture de la saga.

Saga « deposit » : « autorité → capture → credit » avec indemnisation en cas de refus.

Saga « refund/payout » : 'request → submitted → settled/failed' avec répétition et déduplication.

8) Reconnaissance (rapprochement) - le cœur du contrôle de l'argent

8. 1 Rapprochement quotidien

Obtenez le rapport PSP settlement (par merchant/date/devise).

Comparer avec le registre de la plate-forme : 'intents/captures/refunds/payouts' ↔ 'wallet entries'.

Catégoriser :

match : tout ok, timing : retard par les rapports, missing_psp : il y a dans la plate-forme, dans la PSP non, missing_platform : dans la PSP il y a, non dans la plate-forme, amount_mismatch : divergence somme/monnaie/fee.
Règles auto pour timing, tickets/escalade pour mismatch.

8. 2 Processus technique

Les rapports sont programmés par SFTP/API (rétroactions + contrôle de l'intégrité).

Parsing → normalisation → mapping déterministe ('psp _ ref', 'intent _ id', 'capture _ id').

Le rapprochement est effectué dans OLAP (ClickHouse/BigQuery) par invariants.

Vitrines BI : conversions, causes de défaillances, coût des canaux, heure de fermeture.

8. 3 Alert

`% mismatch` > X p. p., sursaut de 'missing _ platform', croissance de 'amount _ mismatch', déviation de 'deposit _ success' sur le canal/geo, aging des transactions non vérifiées> N jours.

9) Chargeback / Dispute

Cycle de vie : notification → evidence → representment → arbitration.

Stockez les paquets evidence (KYC, IP/ASN, device, résultats 3-DS, utilisation-logs).

Lien étroit avec risk/anti-fraud : cartes/bans d'appareils/ASN au niveau du routage.

KPI: win-rate, cost-to-serve, time-to-close.

10) Télémétrie et SLO

p95 autorisations : ≤ 3 s, p99 : ≤ 6-8 s (dépendant des 3-DS/banques).

Deposit success rate par geo/PSP : ciblage ≥ 85 % (référence réaliste).

Reconnaissance lag : rapport fermé ≤ T + 1 jour ; aging des non fidèles

Refund turnaround : ≤ T + 1 par envoi, ≤ T + 5 par inscription (selon le schéma).

Métriques : error-rate par code, échec par 3-DS/AVS, decline-matrix (banque/code), cost per success, webhook-lag, retry storms.

11) Sécurité et conformité

mTLS à PSP + OAuth2/signature de requête ; clés/certificats par marque/région.

PCI DSS : Tokenization PAN, ne jamais stocker CVV, segmentation de zone.

Audit WORM : opération crète (manuel refund/void, changement de merchant).

RG/AML : pieds avant capture/payout ; Sanklists/RER ; Rapport SAR/STR.

Résidence PII : logis/rapports dans la région ; RLS/masquage en BI.

12) Observabilité et journalisation

Logs structurés (JSON) avec 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', codes et durées.

OpenTelemetry sur HTTP/gRPC/DB/files d'attente ; 100 % sampling pour les erreurs/anomalies monétaires.

Dashboards NOC : conversions par canaux, p95, défaillance par codes, webhook-lag, DLQ.

13) Pratiques de chaos et de DR

Chute de PSP : Auto-caskad/« pause nouvelles captures ».

Retarder les webhooks : Dédup + recoupement via l'API pull.

Out-of-order : idempotence et machine de statut sur la plate-forme.

Sortie régionale : Actif-passif/actif-actif, RPO ≤ 5 min, RTO ≤ 30 min.

14) Chèques-feuilles

Plate-forme/opérateur

Tous les chemins d'écriture avec 'X-Idempotency-Key', 'X-Trace-Id'.
Routage/cascades PSP avec télémétrie et limites.
3-DS/AVS/velocity inclus ; les règles de risque et les bans.
Les webhooks sont signés ; dedup par 'event _ id' ; DLQ.
Saga deposit/refund/payout ; compensation sans « modifications manuelles ».
Rapprochement quotidien T + 1, vitrines mismatch, alertes.
Zone PCI, Tokenization PAN ; Audit WORM des opérations Crète.
RG/AML pied à capture/payout.

Intégration PSP/backend de la caisse

Les contrats d'erreur sont normalisés ; mapping des codes decline.
Les répétitions sont sans danger ; les clés d'idempotence sont documentées.
Time out/retrai/gitter, circuit breaker, rate limits.
Les reportages sont disponibles par API/SFTP, l'intégrité est garantie.

15) Anti-modèles (drapeaux rouges)

L'équilibre change selon le Web PSP sans commande explicite dans le portefeuille.

Aucune idempotence → doubles prélèvements/crédits.

Caisse intégrée au sein du fournisseur de jeux iFrame (perte de contrôle RG/AML/télémétrie).

Clés de merchant communes à plusieurs marques/régions.

Pas de rapprochement T + 1, mappage Excel manuel.

BI/rapports réglementaires directement à partir de la caisse OLTP.

Les erreurs ne sont pas 3-DS/AVS/analysées.

Webhooks sans signature/validation de fenêtre → de relais.

Modifications manuelles des statuts de paiement/bilan dans la base de données.

16) Résultat

L'intégration fiable avec les passerelles payantes est une orchestration, pas une « API ». Le succès est assuré par :

1. Commandes d'argent idempotent et sagas (autorité/capture/refund/payout).

2. Routage et cascades PSP avec télémétrie 3-DS/AVS/velocity et réelle.

3. Le rapprochement quotidien (reconciliation) et la comptabilité rigoureuse des divergences.

4. Sécurité et conformité (mTLS, signatures, PCI, RG/AML, WORM).

En construisant ces bases, la plate-forme augmente la conversion des dépôts, réduit les risques de prises et de chargbacks et est auditée avec confiance - même dans le pic du trafic et en cas de défaillance des fournisseurs externes.