El sistema de suspensión por facturación

Una plataforma de pagos que no puede cobrar sus propias comisiones tiene un problema fundamental de credibilidad. El sistema de suspensión por facturación es la capa de aplicación del modelo de comisión del 0,99 % de 0fee.dev -- asegura que los comerciantes que usan la plataforma paguen por el servicio, siendo justo y predecible sobre las consecuencias.

El principio de diseño: advertir temprano, suspender tarde, reactivar instantáneamente.

La línea temporal de facturación

Cada mes sigue el mismo patrón, sin excepciones:

Día 1   --> Cron: Generar facturas del mes anterior
Día 1   --> Email: Factura enviada al comerciante
Día 5   --> Fecha de vencimiento
Día 6   --> Email: Advertencia "Tu factura está vencida"
Día 8   --> Email: Advertencia final "Suspensión en 2 días"
Día 10  --> Cron: Verificar facturas impagadas, suspender cuentas
Día 10+ --> 402 Payment Required en todas las llamadas API

Este ciclo de diez días da a los comerciantes tiempo suficiente para pagar. El periodo de gracia (días 6-10) existe porque entendemos que los negocios africanos a menudo lidian con transferencias bancarias retrasadas, problemas de liquidez de dinero móvil y ciclos de pago variables.

Generación de facturas: el cron del 1.o del mes

El primer trabajo cron se ejecuta a las 00:01 UTC del 1.o de cada mes. Escanea todas las aplicaciones activas, agrega sus transacciones completadas del mes anterior y genera facturas.

pythonasync def cron_generate_invoices(db: AsyncSession):
    """Monthly invoice generation -- runs on the 1st."""
    now = datetime.utcnow()
    period_start = (now.replace(day=1) - timedelta(days=1)).replace(day=1)
    period_end = now.replace(day=1) - timedelta(days=1)

    apps = await db.execute(
        select(App).where(App.status == "active")
    )

    for app in apps.scalars().all():
        transactions = await db.execute(
            select(Transaction).where(
                Transaction.app_id == app.id,
                Transaction.status == "completed",
                Transaction.completed_at >= period_start,
                Transaction.completed_at <= period_end
            )
        )
        tx_list = transactions.scalars().all()

        if not tx_list:
            continue

        total_fees = sum(tx.platform_fee_usd for tx in tx_list)
        # ... crear factura y enviar notificación

La respuesta 402 Payment Required

Cuando una aplicación suspendida intenta hacer cualquier llamada API, el middleware la intercepta y devuelve HTTP 402:

pythonasync def suspension_middleware(request: Request, call_next):
    app = request.state.app
    if app and app.status == "suspended":
        return JSONResponse(
            status_code=402,
            content={
                "error": "payment_required",
                "message": "Your account is suspended due to an unpaid invoice. "
                           "Please pay your outstanding balance to restore access.",
                "invoice_url": f"https://app.0fee.dev/billing/invoices",
                "support_email": "[email protected]"
            }
        )
    return await call_next(request)

HTTP 402 es el código de estado semánticamente correcto -- "Payment Required". La mayoría de desarrolladores nunca lo han encontrado en la práctica, lo que lo hace autodocumentado.

Verificación de suspensión basada en JWT

Para rendimiento, incrustamos el estado de suspensión en el token JWT. Esto evita una consulta a la base de datos en cada solicitud. Hay una verificación de dos capas: JWT (rápida) para la mayoría de casos, y middleware (autoritativo) para casos límite donde el estado del JWT está desactualizado.

El componente SuspensionBanner

En el frontend, los comerciantes suspendidos ven un banner prominente en cada página del panel con el monto exacto adeudado y un botón "Pagar ahora". El banner es intencionalmente intrusivo -- una notificación sutil sería ignorada.

Reactivación automática

Cuando un comerciante suspendido paga su factura, la reactivación es instantánea y automática. El detalle clave: la reactivación solo ocurre si todas las facturas pendientes están pagadas. Un comerciante no puede pagar la factura más reciente e ignorar las anteriores.

Notificaciones del periodo de gracia

Entre la fecha de vencimiento (5) y la fecha de suspensión (10), enviamos notificaciones escaladas: una informativa el día 6 y una urgente el día 8. Nos limitamos deliberadamente a dos correos durante el periodo de gracia. Más sería spam. Menos sería negligente.

Casos límite que manejamos

• Pago el día 10 (condición de carrera): El cron verifica el estado de la factura antes de suspender.
• Pago parcial: No soportamos pagos parciales. La factura debe pagarse en su totalidad.
• Facturas disputadas: Las facturas disputadas se excluyen del cron de suspensión.
• Múltiples apps, un usuario: La suspensión es por aplicación, no por usuario.

Por qué este diseño funciona

El sistema de suspensión por facturación encarna nuestro enfoque para construir 0fee.dev:

1. Automatizado de extremo a extremo. Sin intervención humana necesaria para todo el ciclo de facturación.
2. Justo y predecible. Los comerciantes saben exactamente qué pasa y cuándo. Sin sorpresas.
3. Recuperable. La suspensión es una pausa, no una terminación. Paga la factura y el servicio se reanuda inmediatamente.
4. Seguro. Los endpoints cron están protegidos por secreto. La incrustación JWT reduce la carga de la base de datos.

Con cero ingenieros humanos, no podemos permitirnos perseguir facturas manualmente. El sistema debe manejarse solo, y lo hace.

Este artículo es parte de la serie "Cómo construimos 0fee.dev". 0fee.dev es un orquestador de pagos que cubre más de 53 proveedores en más de 200 países, construido por Juste A. GNIMAVO y Claude desde Abiyán sin ingenieros humanos. Sigue la serie para conocer la historia completa de la construcción.