Integración con pasarelas de pago: flow, devoluciones, reconciliation

Texto completo del artículo

💡 18+. Material técnico para plataformas de iGaming, operadores y proveedores de pagos. No es una llamada al juego.

1) El papel de la orquestación de pago en iGaming

La caja registradora es la «arteria» de la plataforma: acepta depósitos, inicia cachouts, maneja devoluciones/chargeback 'y se sincroniza con la cartera (Ledger). Un error o retraso aquí se convierte rápidamente en un riesgo financiero y de cumplimiento. Tarea de arquitectura: flujo de caja rápido y verificable en caso de interrupción.

2) Flow básico con PSP (mapa de estado)

2. 1 Depósito (tarjeta de estado)

1. create_intent (INICIATED) → la creación de una intención de pago en el lado de la plataforma.

2. Authorize (AUTHORIZED) → la colina en PSP (opcional - capture inmediatamente).

3. 3-DS/AVS/KYC hooks → comprobaciones de riesgo/regulaciones.

4. capture (CAPTURED) → el cobro de fondos; bolso de crédito.

5. failed/expired/canceled → compensación y cierre de intent.

2. 2 Cashout (withdrawal)

request → validatsii los RG/AML/límites → payout_initiated → payout_settled/failed.

Confirmaciones de «cuatro ojos» para sumas VIP/grandes, límites de velocidad y reglas geo.

2. 3 Void / Refund

void: cancelar hasta capture (quita hold).

refund: retorno parcial/completo después de capture.

Para esquemas de tarjetas, los estados individuales son «submitted/processed».

Invariante: La verdad sobre el equilibrio del jugador es la cartera. Los diseños PSP no cambian el equilibrio directamente; sólo a través del comando 'wallet. credit/debit 'con idempotencia.

3) Idempotencia, llaves y retraídas

Cada operación de escritura lleva 'X-Idempotency-Key' y 'X-Trace-Id'.

La composición de clave está vinculada a los parámetros de negocio (por ejemplo, 'intent _ id + amount + currency').

La repetición con la misma clave → el mismo resultado (200 con el viejo cuerpo).

Retrés con retroceso exponencial + jitter, duro 'timeout/deadline'.

4) 3-DS, AVS, velocity, antifraude

3-DS 2. x: preferiblemente challenge-flow con device-fingerprinting; almacene ECI/CAVV/DSTransID en el registro.

AVS/CVV: incluya los códigos de verificación en la telemetría y las reglas de routing.

Velocity: límites por suma/cantidad/tarjetas/ASN/dispositivos (1h/24h/7d).

Señales de comportamiento: no coincidencia geo/zona horaria, muchas tarjetas/pocos depósitos, cachouts rápidos.

5) Enrutamiento y cascadas PSP

Reglas: geo, bandas BIN, tipo de tarjeta, costo, conversión, riesgo-score.

Cascada: PSP1 → PSP2 cuando se falla, sin perder la canasta (idempotent token).

A/B/multi-armed bandit: optimización de conversiones y costos.

Fail-open/closed: para errores dudosos, aplique safe-default (por ejemplo, repetición a través de otro merchant), pero no para doble-capture.

6) Contratos API (fragmentos de referencia)

6. 1 Creación de intent en depósito


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 Autorización/Captura


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 → plataforma (firmada por 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"
}

El receptor debe: verificar la firma/timestamp/nonce, deduplicar 'event _ id', correlacionar con 'intent _ id'.

7) Sincronización con la cartera (Ledger)

Después de capturar: el comando 'wallet. credit '(idempotente) → el equilibrio del jugador.

Refund: `wallet. debit '(o' wallet. hold_release' para void).

Cashout: 'wallet. debit` → `payout` в PSP; después del webhook 'payout _ settled' - Cierre de la saga.

Saga «deposition»: 'authorize → capture → credit' con compensaciones por fallos.

Saga «refund/payout»: 'request → submitted → settled/failed' con repetición y dedoop.

8) Reconciliation (conciliación) - corazón del control del dinero

8. 1 Conciliación diaria

Obtener informe de configuración PSP (por merchant/fecha/moneda).

Asignar al registro de la plataforma: 'intents/captures/refunds/payouts' ↔' wallet entries '.

Categorizar:

match: todo está bien, timing: retraso mj informes, missing_psp: en la plataforma hay, en el PSP no, missing_platform: en el PSP hay, en la plataforma no, amount_mismatch: divergencia cantidad/moneda/fee.
Reglas automáticas para timing, tickets/escalada para mismatch.

8. 2 Proceso técnico

Los informes son arrastrados por SFTP/API según lo programado (retraídas + control de integridad).

Parcing → normalización → mapping determinista ('psp _ ref', 'intent _ id', 'capture _ id').

La conciliación se realiza en OLAP (ClickHouse/BigQuery) por invariantes.

Vitrinas BI: conversiones, causas de fallos, costo de los canales, hora de cierre.

8. 3 Alertas

`% mismatch` > X p. p., estallido de 'missing _ platform', crecimiento de 'amount _ mismatch', desviación de 'deposits _ success' por canal/geo, aging transacciones no fiables> N días.

9) Chargeback / Dispute

Ciclo de vida: notificación → evidencia → representación → arbitración.

Almacenar paquetes de evidencia (KYC, IP/ASN, device, resultados 3-DS, registros de uso).

Estrecha relación con risk/anti-fraud: cuentas de tarjetas/dispositivos/ASN a nivel de routing.

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

10) Telemetría y SLO

p95 autorizaciones: ≤ 3 s, p99: ≤ 6-8 s (depende de 3-DS/bancos).

Tasa de éxito de depósito por geo/PSP: objetivo ≥ 85% (referencia realista).

Registro de reconciliación: informe cerrado ≤ T + 1 día; aging no fiel

Refund turnaround: ≤ T + 1 para el envío, ≤ T + 5 para la inscripción (según el esquema).

Métricas: error-rate por códigos, fallo por 3-DS/AVS, decline-matrix (banco/código), costo por éxito, webhook-lag, storms retry.

11) Seguridad y cumplimiento

mTLS a PSP + OAuth2/firma de solicitudes; claves/certificados por marca/región.

PCI DSS: tokenización PAN, nunca almacenar CVV, segmentación de zonas.

Auditoría WORM: operaciones de creta (manual refund/void, cambio de merchant).

RG/AML: pies antes de capture/payout; Las sank-hojas/rer; Informe SAR/NAT.

Residencia PII: registros/informes en la región; RLS/enmascaramiento en BI.

12) Observabilidad y registro

Registros estructurados (JSON) con 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', códigos y duraciones.

OpenTelemetry en HTTP/gRPC/DB/colas; 100% sampling para errores/anomalías monetarias.

Dashboards NOC: conversiones por canal, p95, denegación por código, webhook-lag, DLQ.

13) Prácticas de caos y DR

Caída del PSP: auto-cascada/« pause new captures ».

Retardo de webhooks: dedoop + re-conciliación a través de pull-API.

Fuera de orden: idempotencia y máquina de estado en la plataforma.

Salida regional: activo pasivo/activo activo, RPO ≤ 5 min, RTO ≤ 30 min.

14) Hojas de cheques

Plataforma/operador

Todas las pistas de escritura con 'X-Idempotency-Key', 'X-Trace-Id'.
Enrutamiento/cascadas PSP con telemetría y límites.
3-DS/AVS/velocity incluidos; reglas risk y banas.
Webhooks firmados; dedoup por 'event _ id'; DLQ.
Sagas de depósito/refund/payout; compensación sin «revisiones manuales».
Conciliación diaria T + 1, vitrinas de mismatch, alertas.
Zona PCI, tokenización PAN; Auditoría WORM de las operaciones de creación.
RG/AML pie a capture/payout.

Integración PSP/backend de la caja registradora

Los contratos de error se normalizan; mapping decline-códigos.
Las repeticiones son seguras; las claves de idempotencia están documentadas.
Tiempo de espera/retrai/jitter, circuit breaker, rate limits.
Los reportes están disponibles por API/SFTP, la integridad está garantizada.

15) Anti-patrones (banderas rojas)

El balance cambia a través de la web PSP sin un comando explícito en la cartera.

No hay idempotencia → doble cargo/crédito.

Caja registradora integrada dentro del proveedor de juegos iFrame (pérdida de control RG/AML/telemetría).

Llaves merchant compartidas en varias marcas/regiones.

No hay conciliaciones T + 1, correlaciones de Excel manuales.

Informes BI/regulatorios directamente desde la caja OLTP.

Los errores 3-DS/AVS no son lógicos/no se analizan.

Webhooks sin firma/validación de ventana → réplica.

Editar manualmente los estados de pagos/balances en la DB.

16) Resultado

La integración confiable con pasarelas de pago es una orquestación, no un «probador de API». El éxito garantiza:

1. Comandos y sagas monetarias idempotentes (authorize/capture/refund/payout).

2. Enrutamiento y cascadas de PSP con telemetría 3-DS/AVS/velocity y real.

3. Conciliación diaria (reconciliation) y contabilización rigurosa de discrepancias.

4. Seguridad y cumplimiento (mTLS, firmas, PCI, RG/AML, WORM).

Al construir estas bases, la plataforma aumenta la conversión de depósitos, reduce los riesgos de tomas y chargebacks y se audita con confianza, incluso en el pico del tráfico y cuando los proveedores externos fallan.