System Design: cómo diseñar un sistema de pagos en una entrevista

-- Tabla de cuentas
CREATE TABLE accounts (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  owner_id    UUID NOT NULL REFERENCES users(id),
  currency    CHAR(3) NOT NULL,  -- ISO 4217: ARS, USD, BRL
  type        TEXT NOT NULL,     -- 'user', 'merchant', 'system'
  created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Tabla de transacciones (inmutable)
CREATE TABLE transactions (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  idempotency_key TEXT UNIQUE NOT NULL,
  status          TEXT NOT NULL DEFAULT 'pending',
  -- 'pending' | 'processing' | 'completed' | 'failed' | 'reversed'
  amount          BIGINT NOT NULL,  -- en centavos/unidad mínima
  currency        CHAR(3) NOT NULL,
  from_account_id UUID REFERENCES accounts(id),
  to_account_id   UUID REFERENCES accounts(id),
  type            TEXT NOT NULL,  -- 'charge' | 'refund' | 'payout' | 'fee'
  metadata        JSONB,
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW()
);

-- Ledger (doble entrada — jamás se modifica, solo inserta)
CREATE TABLE ledger_entries (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  transaction_id  UUID NOT NULL REFERENCES transactions(id),
  account_id      UUID NOT NULL REFERENCES accounts(id),
  amount          BIGINT NOT NULL,  -- positivo = crédito, negativo = débito
  balance_after   BIGINT NOT NULL,  -- snapshot del balance en ese momento
  created_at      TIMESTAMPTZ DEFAULT NOW()
);

# Mal — nunca hagas esto
amount = 10.99  # float

# Bien
amount_cents = 1099  # int, siempre

# Conversión al mostrar
def format_amount(cents: int, currency: str) -> str:
    if currency in ("JPY", "KRW"):
        return f"{cents}"
    return f"{cents / 100:.2f}"

-- Un pago de $100 del usuario A al comercio B
-- genera dos asientos:
INSERT INTO ledger_entries (transaction_id, account_id, amount, balance_after)
VALUES
  (txn_id, account_user_a,    -10000, 50000),  -- débito: le salen $100
  (txn_id, account_merchant_b, 10000, 20000);  -- crédito: le entran $100

-- Invariante: SUM(amount) OVER (txn_id) = 0
SELECT SUM(amount) FROM ledger_entries WHERE transaction_id = txn_id;
-- debe retornar 0

# Cliente: genera la key ANTES de enviar
import uuid

idempotency_key = str(uuid.uuid4())  # se genera una sola vez para este intento

response = requests.post(
    "https://api.payments.com/v1/charges",
    headers={"Idempotency-Key": idempotency_key},
    json={"amount": 5000, "currency": "ARS", "source": "tok_123"}
)

# Servidor: lógica de idempotencia
from db import get_idempotency_record, save_idempotency_record
from fastapi import Header, HTTPException

async def create_charge(
    payload: ChargeRequest,
    idempotency_key: str = Header(...)
):
    # 1. Buscar si ya existe
    existing = await get_idempotency_record(idempotency_key)
    if existing:
        return existing.response  # devolvés la misma respuesta, sin reejecutar

    # 2. Ejecutar el cobro (dentro de una transacción DB)
    async with db.transaction():
        charge = await process_charge(payload)
        # 3. Guardar key + respuesta (atómicamente con el cobro)
        await save_idempotency_record(
            key=idempotency_key,
            response=charge.to_dict(),
            expires_at=datetime.now() + timedelta(days=7)
        )

    return charge

-- Tabla de idempotencia
CREATE TABLE idempotency_records (
  key         TEXT PRIMARY KEY,
  response    JSONB NOT NULL,
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  expires_at  TIMESTAMPTZ NOT NULL
);

-- El UNIQUE en key garantiza que dos requests concurrentes
-- con la misma key no creen dos registros

-- INSERT atómico: si ya existe, no hace nada
INSERT INTO idempotency_records (key, response, expires_at)
VALUES ($1, $2, $3)
ON CONFLICT (key) DO NOTHING
RETURNING *;

-- Si RETURNING no devuelve filas, es que ya existía → fetch y devolvé

Cliente → API Gateway → Payment Service
                              │
                    ┌─────────▼──────────┐
                    │  Validar & crear   │
                    │  transacción       │
                    │  (status=pending)  │
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │  Publicar evento   │
                    │  en Kafka          │
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │  Payment Worker    │
                    │  consume el evento │
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │  Llamar al PSP     │
                    │  (Stripe / dLocal) │
                    └──┬──────────────┬──┘
                       │              │
                  Éxito │         Fallo│
                       │              │
              status=  │    status=   │
              completed │    failed   │
                       │              │
                    ┌──▼──────────────▼──┐
                    │  Actualizar ledger  │
                    │  Notificar webhook  │
                    └────────────────────┘

# Paso 1: autorizar (reservar fondos)
auth = stripe.PaymentIntent.create(
    amount=5000,
    currency="ars",
    capture_method="manual",  # no captura automáticamente
    payment_method="pm_card_visa",
    confirm=True
)
# auth.status == "requires_capture"

# Paso 2: capturar (cuando despachás el pedido)
stripe.PaymentIntent.capture(auth.id)

payments.transactions.created     → payment-workers (procesan con PSP)
payments.transactions.completed   → ledger-workers (asientan en ledger)
payments.transactions.failed      → retry-workers / alerting
payments.webhooks.outbound        → webhook-dispatcher (notifica al comercio)
payments.reconciliation.daily     → reconciliation-worker

# Productor: cuando se crea la transacción
from kafka import KafkaProducer
import json

producer = KafkaProducer(
    bootstrap_servers="kafka:9092",
    value_serializer=lambda v: json.dumps(v).encode("utf-8")
)

producer.send(
    "payments.transactions.created",
    key=transaction_id.encode(),  # key = partition determinista por txn
    value={
        "transaction_id": str(transaction_id),
        "amount": 5000,
        "currency": "ARS",
        "idempotency_key": idempotency_key,
        "payment_method_id": payment_method_id,
        "created_at": created_at.isoformat()
    }
)

# Consumidor: worker que llama al PSP
from kafka import KafkaConsumer

consumer = KafkaConsumer(
    "payments.transactions.created",
    group_id="payment-workers",
    bootstrap_servers="kafka:9092",
    enable_auto_commit=False  # commit manual después de procesar
)

for message in consumer:
    txn = json.loads(message.value)
    try:
        result = call_psp(txn)
        update_transaction_status(txn["transaction_id"], "completed", result)
        consumer.commit()  # solo comiteás si todo salió bien
    except PSPError as e:
        if e.retryable:
            # No commitear → Kafka va a redeliverar
            pass
        else:
            update_transaction_status(txn["transaction_id"], "failed", str(e))
            consumer.commit()

def process_transaction(txn: dict):
    # Verificar si ya fue procesada (idempotencia a nivel worker)
    existing = db.query(
        "SELECT status FROM transactions WHERE id = %s",
        txn["transaction_id"]
    )
    if existing.status in ("completed", "failed"):
        return  # ya procesada, ignorar

    # Procesar solo si está en pending
    result = psp_client.charge(
        amount=txn["amount"],
        idempotency_key=txn["idempotency_key"]  # pasamos la key al PSP también
    )
    update_transaction_status(txn["transaction_id"], "completed", result)

-- Ejemplo de débito con consistencia fuerte
-- Usa FOR UPDATE para lockear la fila durante la transacción
BEGIN;

SELECT balance
FROM accounts
WHERE id = $1
FOR UPDATE;  -- lock exclusivo

-- Verificar saldo suficiente
-- Si balance < amount → ROLLBACK y retornar error

UPDATE accounts
SET balance = balance - $amount
WHERE id = $1;

INSERT INTO ledger_entries (transaction_id, account_id, amount, balance_after)
VALUES ($txn_id, $1, -$amount, balance - $amount);

COMMIT;

-- Sin protección (MAL):
-- Thread A lee balance = 100
-- Thread B lee balance = 100
-- Thread A escribe balance = 0 (cobró 100)
-- Thread B escribe balance = 0 (cobró 100 también — ¡pero ya no había!)

-- Con SELECT FOR UPDATE (BIEN):
BEGIN;
SELECT balance FROM accounts WHERE id = $user_id FOR UPDATE;
-- Thread B queda bloqueado hasta que Thread A haga COMMIT o ROLLBACK
UPDATE accounts SET balance = balance - $amount
WHERE id = $user_id AND balance >= $amount;
-- Verificar affected rows = 1, si no → ROLLBACK
COMMIT;

from abc import ABC, abstractmethod
from dataclasses import dataclass

@dataclass
class ChargeResult:
    psp_transaction_id: str
    status: str  # 'succeeded' | 'failed' | 'pending'
    error_code: str | None = None

class PaymentGateway(ABC):
    @abstractmethod
    async def charge(
        self,
        amount: int,
        currency: str,
        payment_method_token: str,
        idempotency_key: str
    ) -> ChargeResult:
        ...

    @abstractmethod
    async def refund(self, psp_transaction_id: str, amount: int) -> ChargeResult:
        ...

class StripeGateway(PaymentGateway):
    async def charge(self, amount, currency, payment_method_token, idempotency_key):
        import stripe
        intent = stripe.PaymentIntent.create(
            amount=amount,
            currency=currency.lower(),
            payment_method=payment_method_token,
            confirm=True,
            idempotency_key=idempotency_key
        )
        return ChargeResult(
            psp_transaction_id=intent.id,
            status="succeeded" if intent.status == "succeeded" else "failed"
        )

class DLocalGateway(PaymentGateway):
    """Para LATAM: Brasil, México, Argentina, Colombia, etc."""
    async def charge(self, amount, currency, payment_method_token, idempotency_key):
        # dLocal maneja métodos locales: OXXO, Boleto, PSE, Rapipago
        response = await self.client.post(
            "/secure_payments",
            json={
                "amount": amount / 100,  # dLocal usa decimales
                "currency": currency,
                "payment_method_id": payment_method_token,
                "order_id": idempotency_key
            }
        )
        return ChargeResult(
            psp_transaction_id=response["id"],
            status=response["status"]
        )

class MercadoPagoGateway(PaymentGateway):
    """Para Argentina y Brasil principalmente"""
    async def charge(self, amount, currency, payment_method_token, idempotency_key):
        response = await self.client.post(
            "/v1/payments",
            headers={"X-Idempotency-Key": idempotency_key},
            json={
                "transaction_amount": amount / 100,
                "token": payment_method_token,
                "installments": 1
            }
        )
        return ChargeResult(
            psp_transaction_id=str(response["id"]),
            status="succeeded" if response["status"] == "approved" else "failed"
        )

# Selector de PSP
class PSPRouter:
    def select(self, currency: str, country: str, method: str) -> PaymentGateway:
        if country in ("AR", "BR", "MX", "CO") and method in ("oxxo", "boleto", "pse"):
            return DLocalGateway()
        if country == "AR" and method == "mercadopago":
            return MercadoPagoGateway()
        return StripeGateway()  # fallback para tarjetas internacionales

# Endpoint de webhook
from fastapi import Request, HTTPException
import hmac, hashlib

async def stripe_webhook(request: Request):
    payload = await request.body()
    sig_header = request.headers.get("Stripe-Signature")

    # 1. Verificar firma (evitar webhooks falsos)
    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, STRIPE_WEBHOOK_SECRET
        )
    except stripe.error.SignatureVerificationError:
        raise HTTPException(400, "Invalid signature")

    # 2. Idempotencia: ignorar eventos ya procesados
    if await event_already_processed(event["id"]):
        return {"status": "already_processed"}

    # 3. Publicar en Kafka para procesamiento asíncrono
    # (no procesamos directamente en el endpoint — queremos responder rápido al PSP)
    await kafka_producer.send(
        "payments.psp.events",
        key=event["id"].encode(),
        value={
            "event_id": event["id"],
            "type": event["type"],
            "data": event["data"],
            "received_at": datetime.now().isoformat()
        }
    )

    # 4. Responder 200 rápido (Stripe reintenta si no recibe 200 en <30s)
    return {"status": "queued"}

class PSPError(Exception):
    def __init__(self, code: str, message: str, retryable: bool):
        self.code = code
        self.retryable = retryable
        super().__init__(message)

# Errores NO retryable (reintentar no va a ayudar)
NON_RETRYABLE_CODES = {
    "card_declined",           # el banco rechazó la tarjeta
    "insufficient_funds",      # no tiene saldo
    "card_expired",            # tarjeta vencida
    "invalid_card_number",     # número inválido
    "do_not_honor",            # el banco dice que no
}

# Errores retryable (pueden resolverse solos)
RETRYABLE_CODES = {
    "rate_limited",            # PSP con rate limit
    "timeout",                 # timeout de red
    "service_unavailable",     # PSP caído transitoriamente
    "processing_error",        # error interno del PSP
}

async def charge_with_retry(
    gateway: PaymentGateway,
    payload: dict,
    max_attempts: int = 3
) -> ChargeResult:
    base_delay = 1.0  # segundos

    for attempt in range(max_attempts):
        try:
            return await gateway.charge(**payload)
        except PSPError as e:
            if not e.retryable:
                raise  # no reintentar

            if attempt == max_attempts - 1:
                raise  # agotamos reintentos

            # Exponential backoff con jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            await asyncio.sleep(delay)

-- Tabla de outbox (misma base de datos que las transacciones)
CREATE TABLE outbox_messages (
  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  topic        TEXT NOT NULL,
  key          TEXT,
  payload      JSONB NOT NULL,
  created_at   TIMESTAMPTZ DEFAULT NOW(),
  published_at TIMESTAMPTZ  -- null = pendiente de publicar
);

# En la misma transacción de DB, insertás en outbox
async def create_charge(payload: dict):
    async with db.transaction():
        # 1. Crear la transacción
        txn = await db.execute(
            "INSERT INTO transactions (...) VALUES (...) RETURNING *",
            payload
        )
        # 2. Insertar en outbox (mismo TX — o ambos persisten o ninguno)
        await db.execute(
            "INSERT INTO outbox_messages (topic, key, payload) VALUES ($1, $2, $3)",
            "payments.transactions.created",
            str(txn.id),
            txn.to_dict()
        )
    # Después del commit, un poller lee el outbox y publica en Kafka

# Poller que lee outbox y publica (corre en background)
async def outbox_poller():
    while True:
        messages = await db.fetchall(
            "SELECT * FROM outbox_messages WHERE published_at IS NULL LIMIT 100"
        )
        for msg in messages:
            await kafka_producer.send(msg.topic, key=msg.key, value=msg.payload)
            await db.execute(
                "UPDATE outbox_messages SET published_at = NOW() WHERE id = $1",
                msg.id
            )
        await asyncio.sleep(0.1)

# Reconciliation worker (corre una vez al día)
async def daily_reconciliation(date: date):
    # 1. Obtener todos los pagos del día desde el PSP
    psp_transactions = await stripe_client.list_charges(
        created_from=datetime.combine(date, time.min),
        created_to=datetime.combine(date, time.max)
    )

    # 2. Obtener los registros internos del mismo período
    internal_transactions = await db.fetchall(
        """SELECT id, psp_transaction_id, amount, status
           FROM transactions
           WHERE created_at::date = $1""",
        date
    )

    internal_map = {t.psp_transaction_id: t for t in internal_transactions}

    discrepancies = []

    for psp_txn in psp_transactions:
        internal = internal_map.get(psp_txn.id)

        if not internal:
            discrepancies.append({
                "type": "missing_internal",
                "psp_transaction_id": psp_txn.id,
                "amount": psp_txn.amount
            })
            continue

        if internal.amount != psp_txn.amount:
            discrepancies.append({
                "type": "amount_mismatch",
                "internal_id": str(internal.id),
                "psp_transaction_id": psp_txn.id,
                "internal_amount": internal.amount,
                "psp_amount": psp_txn.amount
            })

        if internal.status == "pending" and psp_txn.status == "succeeded":
            discrepancies.append({
                "type": "status_mismatch",
                "internal_id": str(internal.id),
                "action": "mark_completed"
            })

    # 3. Persistir discrepancias para revisión manual o auto-resolución
    if discrepancies:
        await save_reconciliation_report(date, discrepancies)
        await alert_ops_team(f"{len(discrepancies)} discrepancias en {date}")

[Cliente]
    │  (tarjeta ingresada en iframe del PSP)
    │
[PSP (Stripe/dLocal)]
    │  (devuelve un token, ej: "tok_1AbcDEF...")
    │
[Tu sistema]
    │  (solo almacena el token, nunca el PAN)
    ▼
[Base de datos — solo tokens]

# NUNCA hagas esto
payment_method = {
    "card_number": "4242424242424242",  # ¡NUNCA almacenes esto!
    "cvv": "123",                        # ¡NUNCA!
    "expiry": "12/26"                    # ¡NUNCA!
}

# Siempre trabaja con tokens del PSP
payment_method = {
    "token": "pm_1AbcDEF23GhIJKL",  # token opaco del PSP — esto sí
    "last4": "4242",                  # solo los últimos 4 para display
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2026
}

# Rate limiting básico para prevenir ataques de carding
from redis import Redis

redis = Redis()

async def check_rate_limit(user_id: str, ip: str) -> bool:
    # Máximo 5 intentos de pago por IP por hora
    ip_key = f"payment_attempts:ip:{ip}"
    ip_count = redis.incr(ip_key)
    if ip_count == 1:
        redis.expire(ip_key, 3600)
    if ip_count > 5:
        return False  # bloquear

    # Máximo 3 tarjetas distintas por usuario por día
    card_key = f"payment_attempts:user:{user_id}:date:{date.today()}"
    user_count = redis.incr(card_key)
    if user_count == 1:
        redis.expire(card_key, 86400)
    if user_count > 10:
        return False

    return True

┌──────────────────────────────────────────────────────────┐
│                      CLIENTE / SDK                        │
│   (iframe PSP para captura de tarjeta — fuera del scope) │
└────────────────────────┬─────────────────────────────────┘
                         │ HTTPS + Idempotency-Key
                         ▼
┌──────────────────────────────────────────────────────────┐
│                    API GATEWAY / BFF                      │
│   Rate Limiting · Auth (JWT) · TLS termination           │
└────────────────────────┬─────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌──────────────┐
│  Payments   │  │  Accounts   │  │  Webhooks    │
│  Service    │  │  Service    │  │  Service     │
└──────┬──────┘  └──────┬──────┘  └──────┬───────┘
       │                │                │
       └────────────────┼────────────────┘
                        │
                        ▼
       ┌────────────────────────────────┐
       │         Kafka Cluster          │
       │  payments.transactions.created  │
       │  payments.transactions.completed│
       │  payments.psp.events           │
       │  payments.webhooks.outbound    │
       └────────────────┬───────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
┌──────────────┐ ┌────────────┐ ┌──────────────┐
│  Payment     │ │  Ledger    │ │  Webhook     │
│  Workers     │ │  Workers   │ │  Dispatcher  │
│  (x10)       │ │  (x5)      │ │  (x3)        │
└──────┬───────┘ └──────┬─────┘ └──────────────┘
       │                │
       ▼                ▼
┌──────────────────────────────────────┐
│           PSP Router                 │
│  ┌─────────┐ ┌────────┐ ┌─────────┐ │
│  │ Stripe  │ │ dLocal │ │MercPago │ │
│  └─────────┘ └────────┘ └─────────┘ │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│          Databases / Storage         │
│  ┌────────────────┐ ┌─────────────┐  │
│  │ PostgreSQL (RW)│ │ Redis Cache │  │
│  │ Primary + 2    │ │ (idempotency│  │
│  │ Read Replicas  │ │  / sessions)│  │
│  └────────────────┘ └─────────────┘  │
│  ┌─────────────────────────────────┐  │
│  │ ClickHouse / BigQuery (analytics│  │
│  │ + reconciliation reports)       │  │
│  └─────────────────────────────────┘  │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│          Monitoring & Alerting        │
│  Prometheus · Grafana · PagerDuty    │
│  Distributed Tracing (Jaeger/OTEL)   │
└──────────────────────────────────────┘

# Instrumentación con Prometheus
from prometheus_client import Counter, Histogram, Gauge

payment_attempts = Counter(
    "payment_attempts_total",
    "Total de intentos de pago",
    ["psp", "currency", "status"]
)

payment_latency = Histogram(
    "payment_processing_seconds",
    "Latencia de procesamiento de pagos",
    ["psp"],
    buckets=[0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0]
)

kafka_consumer_lag = Gauge(
    "kafka_consumer_lag",
    "Mensajes pendientes en Kafka",
    ["topic", "consumer_group"]
)

# Uso en el código
async def process_payment(txn: dict):
    psp_name = get_psp_for_transaction(txn)

    with payment_latency.labels(psp=psp_name).time():
        try:
            result = await charge(txn)
            payment_attempts.labels(
                psp=psp_name,
                currency=txn["currency"],
                status="success"
            ).inc()
        except PSPError as e:
            payment_attempts.labels(
                psp=psp_name,
                currency=txn["currency"],
                status=e.code
            ).inc()
            raise

# Selección de shard por account_id
def get_shard_for_account(account_id: str) -> str:
    # Consistent hashing o módulo simple
    shard_index = int(account_id.replace("-", ""), 16) % NUM_SHARDS
    return f"db-shard-{shard_index}"

# Job de payout nocturno
async def process_daily_settlements(settlement_date: date):
    # 1. Calcular el monto neto por comercio
    # (ventas - refunds - fees del día anterior)
    settlements = await db.fetchall("""
        SELECT
            merchant_id,
            SUM(CASE WHEN type = 'charge' THEN amount ELSE 0 END) as gross_volume,
            SUM(CASE WHEN type = 'refund' THEN amount ELSE 0 END) as refunds,
            SUM(CASE WHEN type = 'fee' THEN amount ELSE 0 END) as fees
        FROM transactions
        WHERE created_at::date = $1 AND status = 'completed'
        GROUP BY merchant_id
    """, settlement_date - timedelta(days=1))

    for s in settlements:
        net_amount = s.gross_volume - s.refunds - s.fees
        if net_amount > 0:
            await create_payout(
                merchant_id=s.merchant_id,
                amount=net_amount,
                settlement_date=settlement_date
            )

@dataclass
class ExchangeRate:
    from_currency: str
    to_currency: str
    rate: Decimal
    fetched_at: datetime
    source: str  # 'fixer.io' | 'xe.com' | 'central_bank'

# Siempre almacenar el tipo de cambio en el momento del pago
async def create_cross_currency_charge(
    amount: int,           # en moneda del usuario
    user_currency: str,    # ej: "ARS"
    settlement_currency: str  # ej: "USD" — en qué moneda se asienta
) -> dict:
    rate = await get_exchange_rate(user_currency, settlement_currency)

    # Convertir
    settled_amount = int(amount / rate.rate)  # en settlement_currency

    # Guardar ambos montos y el rate — crucial para auditoría
    return {
        "charged_amount": amount,
        "charged_currency": user_currency,
        "settled_amount": settled_amount,
        "settled_currency": settlement_currency,
        "exchange_rate": float(rate.rate),
        "exchange_rate_at": rate.fetched_at.isoformat()
    }

async def handle_unknown_psp_status(transaction_id: str):
    """Consulta el estado real de la transacción al PSP"""
    txn = await get_transaction(transaction_id)

    # Consultar al PSP directamente
    psp_status = await psp_client.retrieve_charge(txn.psp_transaction_id)

    if psp_status == "succeeded":
        await finalize_transaction(transaction_id, "completed")
    elif psp_status == "failed":
        await finalize_transaction(transaction_id, "failed")
    else:
        # Todavía pendiente — reencolar para revisar más tarde
        delay_seconds = 30 * (2 ** txn.status_check_count)  # backoff
        await schedule_status_check(transaction_id, delay=delay_seconds)

# Manejo de flujo 3DS2
intent = stripe.PaymentIntent.create(
    amount=5000,
    currency="eur",
    payment_method="pm_card_threeDSecure2Required",
    confirm=True,
    return_url="https://tuapp.com/payment/return"
)

if intent.status == "requires_action":
    # Redirigir al usuario para completar el 3DS challenge
    redirect_url = intent.next_action.redirect_to_url.url
    return {"action_required": True, "redirect_url": redirect_url}
elif intent.status == "succeeded":
    return {"success": True}