Máquina clasificadora de monedas de latón y acero con una válvula que envía algunas monedas a una bandeja y detiene otras en una compuerta cerrada, como metáfora de un motor de reintentos de pago

Lógica de reintentos de pago: cómo construir un motor seguro

•12 min de lectura

Casi toda lógica de reintentos de pago empieza como un cron que vuelve a cobrar cada noche todas las tarjetas que fallaron. Funciona hasta que cobra dos veces a un cliente, agota el límite de reintentos de una red de tarjetas o insiste con una tarjeta cuyo emisor ya dijo "nunca". Esta guía trata del lado de ingeniería: cómo diseñar la lógica de reintentos de pago como un sistema pequeño y consciente de los códigos de rechazo, con un modelo de datos claro, una capa de políticas, un planificador, ejecución idempotente y las salvaguardas que esperan las redes de tarjetas. Si primero necesitas la visión de negocio (por qué fallan las tarjetas y qué corregir en el checkout), lee nuestra guía sobre cómo reducir los pagos rechazados en una tienda en línea. Este artículo da esa parte por resuelta y se enfoca en qué construir.

Lo que un motor de reintentos realmente tiene que decidir

Cada cobro fallido lleva a tres preguntas, y tu sistema debería responderlas de forma explícita en lugar de esconderlas en un bucle:

  1. ¿Reintentamos o no? Algunos rechazos son definitivos. Reintentarlos desperdicia dinero y puede generar cargos de la red.
  2. ¿Cuándo? Un error técnico puede resolverse en minutos; la falta de fondos, después del día de pago.
  3. ¿Cómo, de forma segura? El reintento no debe crear un segundo cargo si el primero en realidad se aprobó, y dos workers nunca deben reintentar el mismo pago al mismo tiempo.

Las redes de tarjetas te dan señales para las dos primeras. Visa agrupa los rechazos en categorías y, para los que pueden reintentarse, permite no más de 15 reintentos en cualquier periodo de 30 días. Mastercard envía Merchant Advice Codes (MAC) junto con el código de respuesta; su lista de valores incluye 01 (hay nueva información de la cuenta), 02 (intenta más tarde), 03 (no vuelvas a intentar), 21 (cancelación del pago) y 24–29, que significan "reintenta después de" 1 hora, 24 horas, 2, 4, 6 u 8 días. Mastercard además cobra una tarifa por cada reenvío tras un rechazo con MAC 03 dentro de un periodo de 30 días. El trabajo de tu motor es convertir esas señales en decisiones deterministas.

Modelo de datos: separa intenciones, intentos y calendario

El error de diseño más común es una sola fila payments con un status y un retry_count. Pierdes el historial, no puedes auditar por qué ocurrió un reintento y los errores de concurrencia se vuelven invisibles. Modela tres cosas por separado:

CREATE TABLE payment_intents (
  id              UUID PRIMARY KEY,
  customer_id     UUID NOT NULL,
  payment_method  TEXT NOT NULL,        -- gateway token, never a card number
  amount_minor    BIGINT NOT NULL,      -- cents, no floats
  currency        CHAR(3) NOT NULL,
  status          TEXT NOT NULL,        -- pending | retry_scheduled | succeeded | failed_final | needs_customer
  next_attempt_at TIMESTAMPTZ,
  locked_until    TIMESTAMPTZ,
  version         INT NOT NULL DEFAULT 0,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE payment_attempts (
  id               UUID PRIMARY KEY,
  intent_id        UUID NOT NULL REFERENCES payment_intents(id),
  attempt_no       INT NOT NULL,
  idempotency_key  TEXT NOT NULL UNIQUE,
  outcome          TEXT NOT NULL,       -- approved | declined | error | unknown
  gateway_code     TEXT,
  network_code     TEXT,
  advice_code      TEXT,                -- e.g. Mastercard MAC
  decision         TEXT,                -- retry | stop | ask_customer
  raw_response     JSONB,               -- scrubbed
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (intent_id, attempt_no)
);

CREATE INDEX ON payment_intents (next_attempt_at)
  WHERE status = 'retry_scheduled';

La intención es la obligación ("cobrar a este cliente este monto"). Los intentos son hechos inmutables. El calendario vive en la intención como next_attempt_at, lo que mantiene barata la consulta del planificador gracias al índice parcial. La restricción UNIQUE (intent_id, attempt_no) es una protección económica contra dos workers que registran el mismo intento.

Para respetar los límites de la red por tarjeta y no por factura, cuenta los intentos por método de pago en una ventana móvil. Una consulta sobre payment_attempts unida a las intenciones funciona con volumen moderado; con más volumen, mantén una tabla de contadores por método de pago y día.

Normaliza las señales de rechazo antes de decidir

Cada pasarela devuelve sus propios códigos de rechazo, y algunas también transmiten el código de respuesta de la red y el código de recomendación. No dejes que cadenas específicas de una pasarela se filtren a tu política. Primero mapea todo a un vocabulario interno pequeño:

from dataclasses import dataclass
from enum import Enum

class Action(Enum):
    STOP = "stop"                  # never retry automatically
    ASK_CUSTOMER = "ask_customer"  # needs new card or customer action
    RETRY_SOON = "retry_soon"      # technical / transient
    RETRY_LATER = "retry_later"    # funds, limits
    RETRY_AT = "retry_at"          # network told us when

@dataclass
class Decision:
    action: Action
    delay_hours: float | None = None
    reason: str = ""

MAC_DELAYS = {"24": 1, "25": 24, "26": 48, "27": 96, "28": 144, "29": 192}

def classify(attempt) -> Decision:
    mac = attempt.advice_code
    if mac in ("03", "21"):
        return Decision(Action.STOP, reason=f"mac_{mac}")
    if mac == "01":
        return Decision(Action.ASK_CUSTOMER, reason="new_account_info")
    if mac in MAC_DELAYS:
        return Decision(Action.RETRY_AT, MAC_DELAYS[mac], f"mac_{mac}")
    category = GATEWAY_MAP.get((attempt.gateway, attempt.gateway_code))
    if category is None:
        return Decision(Action.STOP, reason="unmapped_code")  # fail closed
    return category

Hay dos detalles importantes. Primero, la recomendación de la red manda sobre tus heurísticas: si el emisor dio una instrucción explícita, síguela. Segundo, los códigos desconocidos fallan cerrado. Un código sin mapear debe detener los reintentos automáticos y generar una alerta, no caer en un cajón por defecto de "reintentar en 24 horas". Guarda GATEWAY_MAP como datos (una tabla o un archivo de configuración) para que operaciones pueda actualizarlo sin desplegar, y versiónalo para que cada intento registre qué mapeo produjo su decisión.

Planificación: esperas, presupuestos y jitter

Una vez que tienes una decisión, calcular el siguiente intento es una función pura. Mantenerla pura hace trivial probarla con tests unitarios:

def next_attempt(decision, attempt_no, card_attempts_30d, now):
    if decision.action in (Action.STOP, Action.ASK_CUSTOMER):
        return None
    if card_attempts_30d >= CARD_BUDGET_30D:   # keep well under network caps
        return None
    if attempt_no >= MAX_ATTEMPTS_PER_INTENT:
        return None
    if decision.action == Action.RETRY_AT:
        base = decision.delay_hours
    elif decision.action == Action.RETRY_SOON:
        base = 0.5 * (2 ** (attempt_no - 1))   # 30 min, 1 h, 2 h...
    else:  # RETRY_LATER
        base = 24 * attempt_no                 # 1 day, 2 days, 3 days...
    jitter = random.uniform(0, base * 0.1)
    return now + timedelta(hours=base + jitter)

CARD_BUDGET_30D y MAX_ATTEMPTS_PER_INTENT son decisiones de tu negocio; fíjalas con holgura por debajo de los límites de la red y no justo en ellos, porque otros sistemas (un cliente que reintenta en el checkout, otra suscripción con la misma tarjeta) también consumen el presupuesto. El jitter evita enviar miles de reintentos a la pasarela en el mismo segundo después de una falla masiva. Para los rechazos de "reintentar más tarde", muchos equipos también alinean los intentos con la hora local del cliente o con sus fechas típicas de pago; si lo haces, guarda la zona horaria en el cliente, no en el servidor.

Ejecutar un reintento sin cobros dobles

Aquí es donde se pierde dinero real. El patrón tiene cuatro partes.

1. Reclama la intención de forma atómica. Usa un lease para que solo un worker procese una intención a la vez:

UPDATE payment_intents
SET locked_until = now() + interval '5 minutes', version = version + 1
WHERE id = (
  SELECT id FROM payment_intents
  WHERE status = 'retry_scheduled'
    AND next_attempt_at <= now()
    AND (locked_until IS NULL OR locked_until < now())
  ORDER BY next_attempt_at
  LIMIT 1
  FOR UPDATE SKIP LOCKED
)
RETURNING *;

FOR UPDATE SKIP LOCKED (PostgreSQL) permite que muchos workers lean de la misma tabla sin bloquearse entre sí.

2. Crea la fila del intento antes de llamar a la pasarela, con una clave de idempotencia determinista como intent_id:attempt_no. Si el worker se cae después de la llamada, el siguiente worker reutiliza la misma clave en lugar de generar una nueva, y una pasarela que soporte claves de idempotencia devolverá el resultado original en vez de cobrar dos veces. Revisa la documentación de tu proveedor para saber cuánto tiempo guarda las claves y qué considera una solicitud en conflicto.

3. Trata los timeouts como "desconocido", no como "rechazado". Un timeout significa que no sabes si el cargo ocurrió. Antes de programar otro intento, consulta el estado del pago en la pasarela o espera el webhook. Reintentar un resultado desconocido con una clave nueva es el clásico error de cobro doble.

4. Concilia con webhooks. Los webhooks pueden llegar antes de que regrese tu llamada a la API, tarde o más de una vez. Procésalos de forma idempotente (guarda el ID del evento, ignora duplicados) y deja que muevan la intención solo mediante transiciones de estado válidas. Una intención en succeeded nunca debe volver a retry_scheduled.

pending ──approved──▶ succeeded
   │
   ├─declined (retryable)──▶ retry_scheduled ──claim──▶ pending
   ├─declined (final)──────▶ failed_final
   ├─needs new card────────▶ needs_customer ──card updated──▶ pending
   └─timeout───────────────▶ unknown ──status check──▶ (any of the above)

Construir, comprar o híbrido: las ventajas y desventajas

Reintentos gestionados por la pasarela. Muchos procesadores y herramientas de facturación ofrecen reintentos automáticos para suscripciones. Se activan rápido y el proveedor puede usar señales que tú no ves. El costo: poco control, poca visibilidad de por qué ocurrió un reintento y dependencia del proveedor si usas más de un procesador.

Tu propio motor. Control total de la política, presupuestos por tarjeta entre procesadores y datos que puedes analizar. El costo es todo lo que describe este artículo: máquina de estados, planificación, idempotencia, monitoreo y mantenimiento de los mapeos de códigos.

Híbrido. Deja que la pasarela se encargue de la recuperación dentro de la sesión (tokens de red, funciones de actualización de tarjetas donde existan) y controla tú los reintentos programados y la comunicación con el cliente. Para la mayoría de las tiendas medianas y negocios de suscripción, es el punto medio pragmático. Nunca ejecutes ambos planificadores automáticos sobre la misma factura: excederás los límites sin darte cuenta.

Sobre el planificador en sí: un cron más la consulta indexada de arriba basta para una sola base de datos y volumen moderado. Una cola con mensajes diferidos escala mejor, pero hace más difícil responder "¿qué está programado para mañana?"; un término medio común es mantener la base de datos como fuente de verdad y usar la cola solo para despachar. Los motores de workflows durables encajan cuando los reintentos son parte de un proceso más largo con correos, periodos de gracia y suspensión de cuentas.

Notas de seguridad y cumplimiento

  • Guarda solo tokens de la pasarela. Tener números de tarjeta en tu base de datos te mete de lleno en el alcance de PCI DSS.
  • Limpia las respuestas crudas de la pasarela antes de guardarlas o registrarlas en logs; conserva los códigos y descarta cualquier cosa parecida a datos de tarjeta o datos personales.
  • Restringe quién puede lanzar reintentos manuales y registra cada acción manual con el usuario que la hizo.
  • Limita la tasa de solicitudes del endpoint "actualiza tu tarjeta y paga" para clientes; es un objetivo atractivo para pruebas de tarjetas robadas.

Errores comunes

  • Reintentar todos los rechazos con la misma espera fija.
  • Contar intentos por factura y no por tarjeta, de modo que un cliente con tres suscripciones recibe el triple de intentos.
  • Generar una clave de idempotencia nueva en cada repetición del mismo intento.
  • Tratar un timeout como un rechazo.
  • Enviar por defecto los códigos de rechazo desconocidos a "reintentar".
  • Ejecutar los reintentos automáticos de la pasarela y los tuyos sobre el mismo cargo.
  • No tener métricas: no puedes saber si el ingreso recuperado viene de los reintentos o de clientes que actualizaron su tarjeta.

Checklist de lógica de reintentos de pago

  • Tablas separadas para intenciones e intentos inmutables.
  • Una capa de normalización de códigos de la pasarela a acciones internas, guardada como datos versionados.
  • Códigos de recomendación de la red (como MAC 03 y 21 de Mastercard) respetados antes de cualquier heurística.
  • Presupuesto de intentos por tarjeta en una ventana móvil de 30 días, por debajo de los límites de la red.
  • Función de planificación pura y con tests, con backoff y jitter.
  • Reclamo atómico con leases o SKIP LOCKED.
  • Claves de idempotencia deterministas creadas antes de llamar a la pasarela.
  • Un estado explícito de "desconocido" para timeouts, resuelto con consulta de estado o webhook.
  • Procesamiento idempotente de webhooks con transiciones de estado obligatorias.
  • Tableros de tasa de recuperación por categoría de rechazo, intentos por tarjeta y reintentos detenidos.

Si vendes suscripciones o pedidos recurrentes, como el autoship de un negocio de venta directa, este motor está en el centro de tus ingresos; es uno de los componentes que construimos en Ariani, nuestra plataforma para empresas de venta directa. Para otros negocios, es una pieza típica de software a la medida construido alrededor de tus flujos de cobro y pagos.

Preguntas frecuentes

¿Cuántas veces debo reintentar un pago con tarjeta fallido?

No hay un número universal. Respeta los límites de la red (Visa permite como máximo 15 reintentos en 30 días para rechazos reintentables, y los MAC 03 o 21 de Mastercard significan que no se reintenta), y después fija tu propio presupuesto menor por tarjeta según tus datos.

¿Los reintentos deben usar la misma clave de idempotencia?

Usa la misma clave cuando repites el mismo intento después de una caída o un timeout, para que la pasarela devuelva el resultado original. Usa una clave nueva para un intento realmente nuevo que programaste después de un rechazo confirmado.

¿Un cron job es suficiente para los reintentos de pago?

Para una sola base de datos y volumen moderado, sí, si reclama filas de forma atómica y el calendario vive en la base de datos. Pasa a una cola o a un motor de workflows cuando crezca el volumen o los reintentos formen parte de un proceso de cobranza más largo.

Comentarios

Todavía no hay comentarios. Sé el primero en compartir lo que piensas.

Deja un comentario

Nunca se publica.