Crypto Casino
Torrent Gear
Integration with payment gateways: flow, returns, reconciliation
Full article
1) The role of payment orchestration in iGaming
The cash register is the "artery" of the platform: it accepts deposits, initiates cashouts, processes returns/chargeback and synchronizes with the wallet (Ledger). An error or delay here quickly turns into financial and compliance risk. The task of the architecture is fast and provably correct cash flow in case of any failures.
2) Basic flow with PSP (state map)
2. 1 Deposit (status card)
1. create_intent (INITIATED) → Create a payment intent on the platform side.
2. authorize (AUTHORIZED) → hold in PSP (optional - capture at once).
3. 3-DS/AVS/KYC hooks → additional risk/regulatory checks.
4. capture (CAPTURED) → debiting; wallet credit.
5. failed/expired/canceled → compensation and closure of the intent.
2. 2 Cashout (withdrawal)
request → validations of RG/AML/лимиты → payout_initiated → payout_settled/failed.
Four-eye confirmations for VIP/large amounts, velocity limits and geo-rules.
2. 3 Void / Refund
void: undo to capture (holds off).
refund: partial/full return after capture.
For card schemes - separate statuses "submitted/processed."
Invariant: The truth of the player's balance is a wallet. PSP designs do not directly change the balance; only through the 'wallet command. credit/debit 'with idempotency.
3) Idempotence, keys and retreats
Each write operation carries' X-Idempotency-Key'and' X-Trace-Id '.
Key composition is bound to business parameters (e.g. 'intent _ id + amount + currency ').
Repeating with the same key → the same result (200 with the old body).
Retreats with exponential backoff + jitter, hard 'timeout/deadline'.
4) 3-DS, AVS, velocity, antifraud
3-DS 2. x: preferably challenge-flow with device-fingerprinting; Log ECI/CAVV/DSTransID.
AVS/CVV: Include validation codes in telemetry and routing rules.
Velocity: limits by amount/quantity/cards/ASN/devices (1h/24h/7d).
Behavioral cues: geo/time zone mismatch, many cards/few deposits, fast cashouts.
5) PSP routing and cascades
Rules: geo, BIN ranges, card type, cost, conversion, risk rate.
Cascade: PSP1 → PSP2 on failure, without loss of the basket (idempotent token).
A/B/multi-armed bandit: optimization of conversion and cost.
Fail-open/closed: For questionable errors, use safe-default (for example, repeat through another merchant), but not for double-capture.
6) API contracts (reference fragments)
6. 1 Creation of an intent on deposit
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 Authorization/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 PSP Webhooks → Platform (signed by 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"
}The receiver must: check the signature/timestamp/nonce, deduplicate 'event _ id', correlate with 'intent _ id'.
7) Synchronization with wallet (Ledger)
After capture: command 'wallet. credit '(idempotently) → the player's balance.
Refund: `wallet. debit '(or' wallet. hold_release' for void).
Cashout: 'wallet. debit` → `payout` в PSP; after the webhook 'payout _ settled' - closing the saga.
Saga "deposit": 'authorize → capture → credit' with compensation for failures.
The "refund/payout" saga: 'request → submitted → settled/failed' with redo and deduplication.
8) Reconciliation - the heart of money control
8. 1 Daily reconciliation
Get PSP settlement report (by merchant/date/currency).
Map to platform registry: 'intents/captures/refunds/payouts' ↔ 'wallet entries'.
Categorize:- match: ok, timing: delay 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: discrepancy between the amount/currency/fee.
- Auto-rules for timing, tickets/escalation for mismatch.
8. 2 Technical process
Reports are pulled by SFTP/API on a schedule (retray + integrity control).
Parsing → normalization → deterministic mapping ('psp _ ref', 'intent _ id', 'capture _ id').
Reconciliation is performed in OLAP (ClickHouse/BigQuery) by invariants.
BI showcases: conversions, reasons for failures, channel cost, closing time.
8. 3 Alerts
`% mismatch` > X p. p., 'missing _ platform' spike, 'amount _ mismatch' growth, 'deposit _ success' channel/geo variance, aging of outstanding transactions> N days.
9) Chargeback / Dispute
Life cycle: notification → evidence → representation → arbitration.
Store evidence packets (KYC, IP/ASN, device, 3-DS results, usage logs).
Close relationship with risk/anti-fraud: card/device/ASN bans at the routing level.
KPI: win-rate, cost-to-serve, time-to-close.
10) Telemetry and SLO
p95 authorizations: ≤ 3 s, p99: ≤ 6-8 s (depends on 3-DS/banks).
Deposit success rate by geo/PSP: target ≥ 85% (realistic guideline).
Reconciliation lag: report closed ≤ T + 1 day; aging unconverted Refund turnaround: ≤ T + 1 for sending, ≤ T + 5 for enrollment (according to the scheme). Metrics: error-rate by codes, failure by 3-DS/AVS, decline-matrix (bank/code), cost per success, webhook-lag, retry storms. 11) Safety and compliance mTLS to PSP + OAuth2/request signatures keys/certificates per brand/region. PCI DSS: PAN tokenization, never store CVV, zone segmentation. WORM audit: crete operations (manual refund/void, change of merchant). RG/AML: feet before capture/payout; sanklists/POP; SAR/STR reporting. PII residency: logs/reports in the region; RLS/masking in BI. 12) Observability and logging Structured logs (JSON) with 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', codes and durations. OpenTelemetry on HTTP/gRPC/DB/queues; 100% sampling for errors/monetary anomalies. NOC dashboards: channel conversions, p95, code failure, webhook-lag, DLQ. 13) Chaos-and DR-practices PSP fall: autocascade/" pause new captures. " Delay webhooks: deadup + recalibration via pull-API. Out-of-order: idempotency and status machine on the platform. Regional outage: asset-liability/asset-asset, RPO ≤ 5 min, RTO ≤ 30 min. 14) Checklists 15) Anti-patterns (red flags) The balance changes by the PSP webhook without an explicit command to the wallet. No idempotency → double write-offs/credits. Built-in cash register inside the iFrame of the game provider (loss of RG/AML/telemetry control). Common merchant keys for several brands/regions. No T + 1 reconciliation, manual Excel mappings. BI/regulatory reports directly from the OLTP cash desk. 3-DS/AVS errors are not logged/analyzed. Unsigned webhooks/window validation → replays. Manual edits of payment/balance statuses in the database. 16) The bottom line 1. Idempotent money commands and sagas (authorize/capture/refund/payout). 2. PSP routing and cascades with 3-DS/AVS/velocity and real telemetry. 3. Daily reconciliation and strict accounting of discrepancies. 4. Security and compliance (mTLS, signatures, PCI, RG/AML, WORM). Having built these foundations, the platform increases the conversion of deposits, reduces the risks of takes and chargebacks and confidently passes the audit - even at the peak of traffic and when external providers fail.
Platform/Operator
PSP integration/cash desk backend