Integracja z bramami płatności: przepływ, zwroty, pojednanie

Pełny artykuł

💡 18+. Materiały techniczne dla platform iGaming, operatorów i dostawców płatności. Ani telefonu do zabawy.

1) Rola orkiestry płatności w iGaming

Kasa jest „arterią” platformy: akceptuje depozyty, inicjuje gotówki, przetwarza zwroty/obciążenie zwrotne i synchronizuje z portfelem (Ledger). Błąd lub opóźnienie szybko przekształca się w ryzyko finansowe i związane z przestrzeganiem przepisów. Zadaniem architektury jest szybki i sprawdzony przepływ środków pieniężnych w przypadku awarii.

2) Przepływ podstawowy z PSP (mapa stanu)

2. 1 Depozyt (karta statusu)

1. create_intent (INITIATED) → Utwórz intencję płatniczą po stronie platformy.

2. authorize (AUTHORIZED) → hold in PSP (opcjonalnie - capture at once).

3. 3-DS/AVS/KYC haczyki → dodatkowe kontrole ryzyka/regulacji.

4. capture (CAPTURED) → debiting; kredyt portfelowy.

5. nie powiodło/wygasło/anulowane → odszkodowanie i zamknięcie zamiaru.

2. 2 Cashout (wycofanie)

wniosek → walidacje RG/AML/лимита → payout_initiated → payout_settled/failed.

Potwierdzenia czworoboczne dla VIP/dużych ilości, limitów prędkości i zasad geoprzestrzennych.

2. 3 Nieważność/zwrot

pusta: cofnij do przechwytywania (zatrzymuje).

zwrot: częściowy/pełny zwrot po przechwyceniu.

W przypadku programów kart - odrębne statusy „złożone/przetworzone”.

Niezmienny: Prawdą równowagi gracza jest portfel. Projekty PSP nie zmieniają bezpośrednio równowagi; Tylko przez „komendę portfela”. kredyt/debet 'z idempotencją.

3) Idempotencja, klucze i rekolekcje

Każda operacja zapisu zawiera 'X-Idempotence-Key' i 'X-Trace-Id'.

Skład klucza jest związany z parametrami biznesowymi (np. „intent _ id + kwota + waluta”).

Powtarzanie z tym samym kluczem → ten sam wynik (200 ze starym ciałem).

Wycofuje się z wykładniczym backoff + jitter, twardy „timeout/deadline”.

4) 3-DS, AVS, prędkość, antifraud

3-DS 2. x: najlepiej wyzwanie-przepływ z urządzeniem-odciski palców; Dziennik ECI/CAVV/DSTransID.

AVS/CVV: Włączenie kodów walidacyjnych do zasad telemetrii i routingu.

Prędkość: limity według ilości/ilości/kart/urządzeń ASN/( 1h/24h/7d).

Wskazówki behawioralne: niedopasowanie geo/strefy czasowej, wiele kart/kilka depozytów, szybkie gotówki.

5) Routing PSP i kaskady

Zasady: geo, zakresy BIN, typ karty, koszt, konwersja, kurs ryzyka.

Kaskada: PSP1 → PSP2 na awarii, bez utraty koszyka (idempotent token).

A/B/bandyta zbrojny: optymalizacja konwersji i kosztów.

Fail-open/closed: W przypadku błędów wątpliwych należy użyć domyślnie bezpiecznego (na przykład powtórzyć przez innego handlowca), ale nie do podwójnego przechwytywania.

6) Umowy API (fragmenty referencyjne)

6. 1 Stworzenie zamiaru wpłaty


POST/v1/cashier/intents
Nagłówki: X-Idempotency-Key, X-Trace-Id
{
„player_id":"p_123,” „kwota „: {„kwota”: 50. 00, "waluta": "EUR"}, "metoda": "karta", "metadane": {"marka _ id':" A "," region ":" UE "}
}
→ 201 {„intent_id":"pi_001,""status":"INITIATED”}

6. 2 Autoryzacja/przechwytywanie


POST/ v1/cashier/intents/pi_001/authorize
→ 200 {„status „: „AUTORYZOWANY „, „psp _ ref „:” psp _ aa1”,” eci”:” 05”,” cavv”:”...”}

POST/ v1/cashier/intents/pi_001/capture
→ 200 {"status": "CAPTURED", "capture _ id':" cap _ 001 "}

6. 3 Nieważność/zwrot


POST/ v1/cashier/captures/cap_001/refunds
{„refund_id":"rf_001,” „kwota „: {„kwota”: 10. 00, „waluta”:” EUR”}}
→ 202 {„status „: „REFUND _ SUBMITTED”}

6. 4 PSP Webhooks → Platforma (podpisana przez HMAC/EdDSA)


POST/webhooks/psp
Podpis X: sha256 =...
{
"wydarzenie ":" płatność. ", "psp_ref":"psp_aa1," "intent_id":"pi_001," "kwota ": {"minor _ units ": 5000," currency":" EUR"}, "occurred_at":"2025-10-23T12:05:01Z," "idempotency_key":"cap_001"
}

Odbiornik musi: sprawdzić podpis/timestamp/nonce, zdublować 'event _ id', skorelować z' intent _ id'.

7) Synchronizacja z portfelem (Ledger)

Po przechwyceniu: komenda 'portfel'. kredyt '(idempotently) → saldo gracza.

Zwrot: "portfel. debit '(lub' portfel. hold_release' za nieważność).

Cashout: 'portfel. debit "→" payout "- PSP; po haku webhook 'payout _ settled' - zamykanie sagi.

Saga "depozyt': 'authorize → capture → credit' z rekompensatą za niepowodzenia.

„Zwrot/wypłata” saga: 'request → submitted → settled/failed' with redo and deduplication.

8) Pojednanie - serce kontroli pieniądza

8. 1 Dzienne pojednanie

Pobierz raport rozliczeniowy PSP (według handlowca/daty/waluty).

Mapa do rejestru platformy: „intencje/przechwytywanie/refundacje/wypłaty”

Kategoria:

mecz: ok, timing: delays mмzh reports, missing_psp: in the platform is, in the PSP is not, missing_platform: in the PSP is, in the platform is not, amount_mismatch: disrepancy between the amount/currency/fee.
Automatyczne zasady dotyczące czasu, biletów/eskalacji w przypadku niedopasowania.

8. 2 Proces techniczny

Raporty są ciągnięte przez SFTP/API w harmonogramie (retray + kontrola integralności).

Parsing → normalizacja → mapowanie deterministyczne ('psp _ ref', 'intent _ id',' capture _ id').

Pojednanie odbywa się w systemie OLAP (ClickHouse/اQuery) przez stałych.

Prezentacje BI: konwersje, przyczyny awarii, koszt kanału, czas zamknięcia.

8. 3 Wpisy

'% mismatch'> X p. p., 'missing _ platform' spike, 'amount _ mismatch' growth, 'deposit _ success' channel/geo variance, aging of outstanding transactions> N days.

9) Obciążenie zwrotne/spór

Cykl życia: powiadomienie → dowody → reprezentacja → arbitraż.

Przechowywać pakiety dowodowe (KYC, IP/ASN, urządzenie, wyniki 3-DS, dzienniki użytkowania).

Bliski związek z ryzykiem/zwalczaniem oszustw: karta/urządzenie/zakazy ASN na poziomie routingu.

KPI: stawka wygranej, koszt obsługi, czas do zamknięcia.

10) Telemetria i SLO

p95 zezwolenia: ≤ 3 s, p99: ≤ 6-8 s (zależy od 3-DS/banków).

Wskaźnik powodzenia depozytów według geo/PSP: cel ≥ 85% (realistyczne wytyczne).

Opóźnienie pojednania: raport zamknięty ≤ T + 1 dzień; starzenie się bez nawrotu

Obrót refundacji: ≤ T + 1 do wysyłki, ≤ T + 5 do rejestracji (zgodnie z programem).

Metryki: wskaźnik błędów według kodów, awaria przez 3-DS/AVS, matryca spadkowa (bank/kod), koszt za sukces, hak-lag, powtórne burze.

11) Bezpieczeństwo i zgodność

mTLS do PSP + OAuth2/request klucze podpisów/certyfikaty dla marki/regionu.

PCI DSS: tokenizacja PAN, nigdy nie przechowywać CVV, segmentacja strefy.

Audyt WORM: operacje kretowe (ręczny zwrot/nieważność, zmiana handlowca).

RG/AML: stopy przed przechwyceniem/wypłatą; sankliści/POP; sprawozdawczość SAR/STR.

rezydencja PII: dzienniki/raporty w regionie; RLS/maskowanie w BI.

12) Obserwowalność i pozyskiwanie drewna

Rejestry strukturalne (JSON) z 'trace _ id',' psp _ ref ',' intent _ id/capture _ id/refund _ id', kody i okresy.

OpenTelemetry na HTTP/gRPC/DB/kolejki; 100% pobieranie próbek w przypadku błędów/nieprawidłowości monetarnych.

Deski rozdzielcze NOC: konwersje kanałów, p95, awaria kodu, webhook-lag, DLQ.

13) Praktyki chaosu i DR

Upadek PSP: autokasada/” zatrzymać nowe przechwytywania„

Opóźnienie webhooks: deadup + rekalibracja poprzez pull-API.

Poza zamówieniem: maszyna do idempotencji i stanu na platformie.

Przerwa regionalna: aktywa-zobowiązania/aktywa-aktywa, RPO ≤ 5 min, RTO ≤ 30 min.

14) Listy kontrolne

Platforma/Operator

Wszystkie ścieżki zapisu z 'X-Idempotency-Key', 'X-Trace-Id'.
PSP routing/kaskady z telemetrii i limitów.
3-DS/AVS/velocity włączone; zasad ryzyka i zakazów.
Haki internetowe podpisane; dziadek przez 'event _ id'; DLQ.
Depozyt Sagas/zwrot/wypłata; kompensacja bez „ręcznych edycji”.
Dzienne pojednanie T + 1, przypadki niedopasowania, wpisy.
strefa PWZ, tokenizacja PAN; Audyt WORM operacji kretowych.
Stopy RG/AML do przechwytywania/wypłaty.

Integracja PSP/backend cash desk

Umowy o błąd są znormalizowane; mapowanie kodów upadku.
Powtórki są bezpieczne; klucze idempotencji są udokumentowane.
Timeouts/retreats/jitter, wyłącznik, limity prędkości.
Raporty są dostępne za pośrednictwem API/SFTP, integralność jest gwarantowana.

15) Anty-wzory (czerwone flagi)

Saldo zmienia się przez hak PSP bez wyraźnego polecenia do portfela.

Brak idempotencji → podwójne odpisy/kredyty.

Wbudowana kasa wewnątrz iFrame dostawcy gry (utrata kontroli RG/AML/telemetrii).

Wspólne klucze handlowe dla kilku marek/regionów.

Brak pojednania T + 1, ręczne mapowanie programu Excel.

BI/raporty regulacyjne bezpośrednio z biurka OLTP.

3-DS/AVS błędy nie są rejestrowane/analizowane.

Niezapisane haki internetowe/walidacja okien → powtórki.

Ręczne edycje statusów płatności/salda w bazie danych.

16) Sedno sprawy

Niezawodna integracja z bramy płatności to orkiestra, a nie "spedycja API. "Sukces zapewnia:

1. Idempotentne polecenia pieniężne i sagi (autoryzacja/przechwytywanie/zwrot/wypłata).

2. PSP routing i kaskady z 3-DS/AVS/velocity i prawdziwej telemetrii.

3. Codzienne pojednanie i ścisłe rozliczanie rozbieżności.

4. Bezpieczeństwo i zgodność (mTLS, podpisy, PCI, RG/AML, WORM).

Po zbudowaniu tych fundamentów, platforma zwiększa konwersję depozytów, zmniejsza ryzyko przejęć i obciążeń zwrotnych oraz pewnie przechodzi audyt - nawet w szczytowym momencie ruchu i gdy dostawcy zewnętrzni zawiodą.