Payment automation and limit control

Full article

💡 18+. Engineering and applied material for platforms and iGaming operators. Not a call to play. By "payments" we mean cashouts to players in all channels: cards/banks/wallets/crypto.

1) Why automate payouts

Speed and predictability: Players expect fast and transparent cashouts.

Risk and compliance: RG/AML/sanctions, velocity and brand/player/channel limits.

Scale: peaks after tournaments and "hot" broadcasts - tens of thousands of applications.

Cost: optimization of commissions and treasury balances on PSP/accounts/networks.

The key goal is a one-time, verifiable and manageable payout for any outages.

2) Payout-core role model

Payout Orchestrator is a status machine and sagas: accepts applications, checks limits and rules, routes, retrait, records the result.

Risk & Compliance - RG/AML/KYT, sledge screening, "four eyes."

Treasury - channel reserves, balance management, hedging.

Wallet/Ledger is a source of balance truth; debit/compensation only through it.

PSP/Bank/Kastodi/Crypto-processor - final performer.

3) State machine

1. request → request from front/CRM/API.

2. precheck → RG/AML: self-exclusion/loss/time limits, sunlists/PEP, KYT (for crypto/wallets), KYC status.

3. limits → checking velocity and limits: per player/brand/region/method (daily/weekly/monthly).

4. deduct → idempotent'wallet. debit` (или `hold`→`commit`) с `X-Idempotency-Key`.

5. route → channel/merchant/network selection (rules + cost + conversion + availability).

6. submit → send to PSP/bank/custom (mTLS + signatures).

7. await_settlement → waiting for confirmation ('settled '/' failed') by webhook or pull check.

8. notify → events to the bus/BI, the player - status/ETA.

9. reconcile → reconciling PSP/bank/chain reports with Ledger.

10. compensate → if 'failed' - return to Ledger (idempotent), reselection of the channel, escalation.

Invariants:

The balance only changes through Ledger.
"Lost/duplicated payouts" = 0 - provided by idempotency and deduplication.
All transitions are atomically logged and traced ('trace _ id', 'payout _ id').

4) Limits and velocity: how to count correctly

4. 1 Limit types

Regulatory/RG: daily/weekly withdrawal limits, self-exclusion, cooling.

Fraud/velocity: amount/number of transactions, frequency of applications, change of details, devices/ASN/geo.

Cash: channel/merchant/account/network limits, treasury balances.

Operating rooms: thresholds for "manual review" and "four eyes" (VIP/large sums).

4. 2 Storage and implementation

Distributed counters (Redis + TTL + Lua/atomic) for 1h/24h/7d windows.

Projections in OLAP for advanced rules (sliding windows, patterns).

Idempotence of counters: increase only when the application is transferred to 'submitted'.

Explainability: for each failure - the cause code and "what limit worked."

5) Channel orchestration (PSP/banks/crypto)

5. 1 Routing

Rules on geo, currency, amount, speed, cost, risk, availability, SLO camps.

Cascades: PSP1→PSP2 in case of failure; for crypto - A→B network.

A/B and bandit approach to optimize conversion and price.

5. 2 Channel-specific features

Cards/banks: status machines' submitted→processing→settled ', returns/rollbacks according to schemes (SEPA/SWIFT).

E-wallets: instant but strict limits and sledge screening.

Crypto: on-chain finality (N confirmations), addressable KYT, Travel Rule between VASP, white address lists, MRS/multisig, gas management.

6) Safety and compliance

mTLS + OAuth2/signatures on all S2S, per brand/region keys, short-lived tokens and bound to a channel.

CCR/CCR/Sank- screening before 'submit'; for crypto - the risk rate of the address/tx.

RBAC/ABAC and "four eyes" on manual actions/threshold sums.

WORM audit: immutable logs of limit/rule/threshold changes and manual interventions.

PII/residency: data and logs - by region, encryption at-rest/in-transit, RLS.

7) Idempotence and sagas (money ways)

Each recording operation carries an'X-Idempotency-Key'; repeat → same result (200 with old body).

Сага `deduct→submit→settled`:

if 'submit' fell - compensation ('wallet. release/credit`).
if 'settled' did not come - retray/re-question, grandfather by 'payout _ id'.
No manual balance adjustments - only compensating events.

8) API contracts (reference fragments)

Create a purchase requisition


POST /v1/payouts
Headers: X-Idempotency-Key: po_001, X-Trace-Id: tr_a1b2
{
"player_id":"p_123",  "amount":{"amount":250. 00,"currency":"EUR"},  "method":"sepa",  "destination":{"iban":"DE89..."},  "metadata":{"brand_id":"A","region":"EU"}
}
→ 202 {"payout_id":"po_001","status":"REQUESTED","eta":"2025-10-23T18:00:00Z"}

Webhook from PSP/bank/custom


POST /webhooks/payouts
X-Signature: sha256=...
{
"event_id":"uuid",  "payout_id":"po_001",  "psp_ref":"psp_77",  "status":"SETTLED",  "occurred_at":"2025-10-23T16:21:05Z"
}

Hold removal/compensation


POST /v1/payouts/po_001/compensate
Headers: X-Idempotency-Key: po_001_comp
→ 200 {"status":"COMPENSATED"}

9) Observability and SLO

SLO (landmarks):

`payout. request→submit 'p95 ≤ 120-300 ms (internal path),' submit→settled 'p95: cards/ewallet ≤ 5-30 min, SEPA banks ≤ T + 0/T + 1, crypto ≤ 10 min (over the network), "lost/duplicate payments" = 0.

Metrics:

latency p50/p95/p99 by stages, error-rate (business/4xx/5xx), retry storms, queue/DLQ lag, success-rate by channels, cost per success, PSP/bank code failure, limit-response (RG/AML/velocity).
Tracing: OpenTelemetry (edge→limits→wallet→router→PSP), 'trace _ id' in webhooks.
Alerts: breach SLO, 'IDEMPOTENCY _ MISMATCH' growth, 'missing _ platform' jump on reconciliation, success-rate drop in a particular geo/channel.

10) Treasury and balances

Reserves by channels/merchants/networks, automatic rebalance.

Threshold policies: minima and maxima in accounts/wallets, "stopping new payments" when underfunded.

Currency hedging/crypto, accounting for commissions and exchange rate differences.

Financial showcases: plan-fact, cost of withdrawal via the channel, aging "hanging" payments.

11) Reconciliation

Daily PSP/bank/custom/chain reports → normalization → comparison with the'payouts' registry and Ledger records.

Категории: `match`, `timing`, `missing_psp`, `missing_platform`, `amount_mismatch`.

Auto-rules for 'timing', tickets for 'mismatch', alerts by thresholds.

For crypto - mapping by 'txid/network/confirmations'.

12) Chaos practices and DR

PSP/bank drop: cascade to alternative, 'pause new payouts' mode for channel.

Delay of webhooks: periodic pull-statuses, dedup by 'event _ id'.

Regional outage: asset-liability/asset-asset (RPO ≤ 5 min, RTO ≤ 30 min).

Spiked gas/reorgs (crypto): dynamic fee, additional confirmations, deferred low-priority payments.

13) Checklists

Platform/Operator

Idempotency on'wallet. debit/credit/compensate`, `X-Idempotency-Key` везде.
Velocity/RG/AML/KYT/Sank Screening before 'submit'.
Routing and channel cascades, keys/certificates per brand/region.
WORM audit of limits/rules/manual actions, four eyes on thresholds.
SLO dashboards and alerts, OpenTelemetry, DLQ for webhooks.
Daily T + 1 reconciliation, mismatch cases, escalations.
Treasury thresholds and auto rebalance; stop mods ('no new payouts').
DR/xaoc exercises: PSP/bank/network drop, delays/duplicates of webhooks.

Provider/PSP/Bank/Custom

Signed Webhooks (HMAC/EdDSA) + timestamp/nonce, 2xx re-delivery guarantee.
Normalized failure cause codes, T + 1 reports, file integrity (hash/PGP).
Available status APIs for pull checks.

14) Anti-patterns (red flags)

Debit/credit balance by webhook without explicit command in Ledger.

Lack of idempotency → double write-offs/compensations.

Shared keys/certificates for multiple brands/regions.

Velocity limits are considered "on request" and not on confirmed shipments.

Manual edits of payment/balance statuses in the database.

There is no DLQ/deduplication for webhooks → "sticky" statuses.

No T + 1 reconciliation; manual Excel part-timers.

Crypto-inferences without TAC/whitelisting/multifactorial confirmations.

15) The bottom line

Payment automation is an orchestration of money and risks: hard limits and velocity, idempotent money commands, reasonable channel routing, default compliance, observability and daily reconciliation. Such a payout pipeline pays quickly and once, is resistant to crashes and peaks, is transparent to the player, regulator and financial reporting - and at the same time controls the cost and risks of the treasury.