mod.payouts — Cobros de plataforma¶
Community · Categoría core (siempre registrado) · inerte salvo que el operador active el modo plataforma
Qué hace¶
Permite que el operador de la instalación cobre en su propia cuenta de Stripe y reparta el dinero a cada creador: al creador le llega venta − comisión real de Stripe − comisión del operador. Es el modo con el que funciona Didacta Cloud; el creador no pega claves de Stripe, conecta una cuenta de cobros y el resto lo hace la plataforma.
Aquí vive el dominio del dinero: cuenta conectada del creador, reparto de cada venta, libro mayor, deudas, reembolsos, disputas, conciliación con Stripe, datos fiscales del creador y la factura mensual de la comisión.
Una instalación Community normal no lo usa
Sin PAYMENTS_PLATFORM_STRIPE_SECRET_KEY el módulo no consulta ni escribe una sola fila: cada aula sigue cobrando con sus propias claves de Stripe (véase mod.billing y mod.subscriptions) y sin comisión. Esta página es para quien opera una plataforma con varias aulas y quiere cobrar en nombre de sus creadores. Los creadores de Didacta Cloud tienen la guía propia en Cloud → Cobros y pagos.
Cómo funciona¶
- Interruptor único: la variable
PAYMENTS_PLATFORM_STRIPE_SECRET_KEY. Vacía o sin definir, el modo está apagado y el resto de variablesPAYMENTS_PLATFORM_*ni se leen (aunque traigan basura). Definida, el modo está encendido y todo se valida al arrancar: lo que falte o esté mal aborta el arranque con un mensaje que nombra la variable. Una plataforma que cobra dinero ajeno no arranca a medias; en particular, clave sinPAYMENTS_PLATFORM_STRIPE_WEBHOOK_SECRETSes un error. - Sin dependencias entre módulos: no importa
mod.billingnimod.subscriptions, ni ellos a él. El host les pasa un adaptador de Stripe con las opciones de Connect y compone los tres. - Cuenta conectada con alta alojada: el creador elige país y tipo (particular/autónomo o empresa) en Administración → Cobros (
/admin/payments) y completa el alta en Stripe. La pantalla le dice en cada momento si falta un dato, si Stripe está revisando o si ya puede vender. Mientras la cuenta no está lista, la compra del aula no se abre (y/joinno ofrece planes). - Importes siempre de la API de Stripe: al liquidar, el servicio relee el cargo con su
balance_transactiony calcula el reparto con la comisión real de ese cobro, en la divisa de liquidación. El reparto se sella antes de llamar a Stripe y un reintento nunca lo recalcula. - Una transferencia por venta: se crea con
source_transactiony una clave de idempotencia por venta; antes de crearla se busca en Stripe una transferencia previa de esa venta y, si existe, se adopta. Una venta pasa porAWAITING_FEE→READY→ liquidada, o se queda retenida con motivo y reintento diario (cuenta restringida, transferencia rechazada, cargo reembolsado o disputado, datos fiscales sin completar). - Libro mayor de solo inserción: cada euro (venta, comisión de Stripe, comisión del operador, deuda recuperada, reembolso, disputa) deja un asiento que no se modifica nunca. Los reembolsos de pagos posteriores se apuntan como asientos nuevos.
- Reembolsos y disputas: el creador reembolsa desde Ventas (total o parcial) con una vista previa de lo que se le descuenta. Por defecto el operador devuelve su comisión en proporción, la comisión de la tarjeta (que el banco no devuelve) la asume el creador, igual que la tasa de una disputa perdida. Si el dinero ya se le había enviado y no hay saldo suficiente, se anota una deuda que se descuenta de sus próximas ventas.
- Conciliación: un barrido horario y otro nocturno profundo comparan el libro con Stripe, y el operador puede lanzarlo a mano (
POST /modules/payouts/admin/reconcile/run-now). Las discrepancias avisan por correo al operador (PAYMENTS_PLATFORM_OPERATOR_ALERT_EMAIL). - Datos fiscales y factura: las transferencias se retienen hasta que el creador complete sus datos fiscales (
PAYMENTS_PLATFORM_TAX_PROFILE_REQUIRED, activo por defecto) porque son necesarios para la factura de la comisión y para el reporte DAC7. El NIF/VAT se valida (con consulta a VIES para el IVA intracomunitario). A principios de cada mes se emite la factura de la comisión del mes anterior (una por aula y moneda; serieDC-AAAA-NNNNNN, rectificativasDCR-…) en PDF, con la comisión con el IVA incluido y desglosado según dónde esté el creador, y se envía por correo; el creador las ve en Cobros → Facturas. Sin los datos del emisor (PAYMENTS_PLATFORM_INVOICE_ISSUER_*) no se factura y se avisa al arrancar. - Aula a aula: la comisión por defecto es el 5 % (
PAYMENTS_PLATFORM_DEFAULT_FEE_BPS, máximo 30 %) y el operador puede fijar una distinta por aula desde la administración de instancia.
Configuración (operador de la instancia)¶
Todas son variables de entorno de instancia; no hay ajustes por aula para el creador más allá del alta y los datos fiscales. Referencia completa en Variables de entorno → Cobros de plataforma.
| Variable | Qué controla (por defecto) |
|---|---|
PAYMENTS_PLATFORM_STRIPE_SECRET_KEY |
Interruptor. Clave sk_…/rk_… de la cuenta del operador. |
PAYMENTS_PLATFORM_STRIPE_WEBHOOK_SECRETS |
Secretos whsec_… del webhook de plataforma (1 a 3, separados por comas). Obligatoria si hay clave. |
PAYMENTS_PLATFORM_STRIPE_PUBLISHABLE_KEY |
Clave pk_… para pintar el pago dentro de la ficha de venta (opcional). |
PAYMENTS_PLATFORM_DEFAULT_FEE_BPS |
Comisión del operador en puntos básicos (500 = 5 %). |
PAYMENTS_PLATFORM_SUPPORTED_COUNTRIES |
Países a cuyos creadores se paga (UE/EEE donde opera Stripe, GB, CH, US, CA). |
PAYMENTS_PLATFORM_PAYOUT_INTERVAL / _WEEKLY_DAY / _DELAY_DAYS |
Calendario de pago de Stripe a la cuenta bancaria del creador (weekly, monday, 7 días). |
PAYMENTS_PLATFORM_MIN_BALANCE |
Colchón que se deja en la cuenta del creador, por divisa (eur:5000,usd:5000,gbp:5000). |
PAYMENTS_PLATFORM_REFUND_PLATFORM_FEE, _REFUND_CARD_FEE_BEARER, _DISPUTE_LOSS_BEARER, _DISPUTE_WON_FEE_BEARER |
Quién asume qué cuando el dinero vuelve. |
PAYMENTS_PLATFORM_TAX_PROFILE_REQUIRED |
Retener transferencias sin datos fiscales (true). |
PAYMENTS_PLATFORM_INVOICE_* |
Datos del emisor, serie y nombre del servicio de la factura de la comisión. |
PAYMENTS_PLATFORM_OPERATOR_ALERT_EMAIL |
Correo del operador para las alertas de dinero. |
Workers (todos con cron ajustable): PAYOUTS_SETTLE_CRON (barrido de liquidación, cada minuto), PAYOUTS_ACCOUNTS_PENDING_CRON (*/15 * * * *) y PAYOUTS_ACCOUNTS_READY_CRON (20 3 * * *) para sincronizar cuentas, PAYOUTS_RECONCILE_CRON (7 * * * *) y PAYOUTS_RECONCILE_DEEP_CRON (40 3 * * *) para la conciliación, y PAYOUTS_INVOICES_CRON (20 6 * * *, hora de Madrid) para la factura mensual.
El webhook de plataforma es POST /api/v1/modules/payouts/webhook y verifica la firma contra cualquiera de los secretos configurados (varios para poder rotar sin cortes).
Uso paso a paso¶
- El operador crea las claves y el webhook en su cuenta de Stripe, define las variables
PAYMENTS_PLATFORM_*y reinicia. Si algo está mal, el arranque aborta con el nombre de la variable. - El creador entra en Administración → Cobros (
/admin/payments), pulsa «Conectar cobros», completa el alta en Stripe y, cuando la tarjeta dice «Todo listo», rellena sus datos fiscales. - Cada venta aparece en «Tus ventas» con lo pagado, la comisión de la tarjeta, la del operador, lo que recibe, cuándo llega y su estado (cobrada, en camino, enviada, retenida, reembolsada, reclamada…).
- Para devolver un pago, «Reembolsar» enseña antes cuánto se le descuenta; con un reembolso total el alumno pierde el acceso, con uno parcial lo conserva.
- Cada mes aparece su factura de la comisión en Cobros → Facturas (PDF).
Captura con el modo plataforma encendido
/admin/payments solo existe cuando el modo plataforma está encendido. La captura es de una aula de ejemplo, en modo sencillo (pestaña Ventas), con el modo plataforma activado con claves de Stripe inventadas (no hay ninguna cuenta real conectada): enseña la tarjeta «Cobros» antes de conectar. Las pantallas posteriores al alta (cuenta, ventas, facturas) necesitan una cuenta de Stripe de verdad y no llevan captura.

Dependencias¶
Ninguna declarada (modules: [], optionalModules: []). La composición con billing y subscriptions la hace el host.
Modelo de datos¶
mod_payouts_account (cuenta conectada) · mod_payouts_sale · mod_payouts_ledger_entry (solo inserción) · mod_payouts_debt · mod_payouts_refund · mod_payouts_dispute · mod_payouts_object_ref (objeto de Stripe → aula) · mod_payouts_webhook_event (idempotencia) · mod_payouts_settings · mod_payouts_tax_profile · mod_payouts_invoice, _invoice_item y _invoice_counter.
Permisos¶
payouts.account.read, payouts.account.manage, payouts.sale.read, payouts.sale.refund.
API¶
Prefijo /modules/payouts: status, connect, connect/link, dashboard-link, disconnect, sales, summary, sales/:id/refund-preview, sales/:id/refund, tax-profile (GET/PUT), invoices, invoices/:id/pdf, webhook (Stripe) y, solo operador, admin/reconcile/run-now y admin/invoices/run.
Eventos¶
El manifest no declara eventos propios (eventsEmitted: [], eventsConsumed: []): los hechos de Stripe llegan por el webhook de plataforma, no por el bus.