Cómo cobran los mentores (Stripe)

Tu academia puede ser gratis o de pago. Cuando cobras, el dinero de tus alumnos entra en TU propia cuenta de Stripe, no en la de Onyx. Onyx solo retiene su comisión de plataforma, de forma automática, en la misma transacción. Esta guía tiene dos partes: primero lo esencial para el mentor, y al final el detalle técnico del modelo que tenemos montado.

① Para el mentor: lo esencial

Para poder cobrar solo tienes que conectar tu cuenta de Stripe una vez. Es un proceso de Stripe (no de Onyx) y toma un par de minutos.

Qué te llega y cuándo

De cada venta se descuentan dos cosas: la comisión de Stripe (su tarifa por procesar el pago) y la comisión de Onyx (el porcentaje de plataforma que ves en tu panel). El resto es tuyo y queda en tu saldo de Stripe. Luego Stripe hace el pago a tu banco según su calendario de pagos (payout), que tú controlas desde tu propio panel de Stripe.

• El precio lo pones tú, en dólares (mensual, anual y/o pagos únicos por nivel).
• Puedes abrir o cerrar inscripciones y crear cupones de descuento cuando quieras.
• En cada renovación mensual/anual se repite el mismo reparto automáticamente.
• Onyx nunca guarda el dinero: solo separa su comisión en la misma transacción.

Ver tus cobros

Desde tu panel tienes un enlace directo a tu panel de Stripe (Express), donde ves cada cobro, tus pagos al banco y tus facturas. Tus ingresos y la comisión retenida por Onyx también se resumen en tu panel de la academia.

Renovaciones, cancelaciones y reembolsos

Si un alumno cancela, deja de renovar y pierde el acceso al final del periodo pagado. Si haces un reembolso, la comisión de esa venta se marca como revertida en el libro (no cuenta como ingreso). Todo esto es automático.

② Cómo funciona por dentro (técnico)

Esta parte es para ti y tu equipo. Explica el modelo real que está implementado, por si necesitas auditarlo o dar soporte.

Stripe Connect + destination charge

Cada mentor tiene una cuenta Stripe Connect de tipo Express (capacidades transfers y card_payments). Los cobros se crean como "destination charge" en la plataforma de Onyx y se transfieren al mentor:

• transfer_data.destination = cuenta del mentor → el neto va a su cuenta.
• on_behalf_of = cuenta del mentor → el mentor es el comercio de registro, así absorbe el fee de Stripe y la comisión de Onyx queda limpia y separada.
• Pagos únicos: application_fee_amount = precio × %. Suscripciones (niveles, membresía y copy del mentor): application_fee_percent = %.
• allow_promotion_codes activo → el alumno puede aplicar tus cupones de Stripe.

La comisión de Onyx (jerarquía)

El porcentaje que retiene Onyx se resuelve con feeForMentor(), de lo más específico a lo más general, y siempre se limita a un rango de 0–50%:

• 1) Override manual por mentor (mentors.fee_pct), si el dueño fijó uno.
• 2) Comisión de su plan de Onyx (plans.capabilities.academy_fee_pct): baja al subir de plan.
• 3) Porcentaje global por defecto (ajuste app_settings academy_fee).
• 4) Valor de entorno (ONYX_ACADEMY_FEE_PCT, por defecto 10%).

El libro de comisiones

Un webhook dedicado (firmado con ACADEMY_WEBHOOK_SECRET) escucha los eventos de Stripe y anota cada comisión en la tabla onyx_commissions, de forma idempotente por (mentor_id, stripe_ref) para que los reintentos no dupliquen.

• checkout.session.completed: da el acceso; en pago único anota la comisión atada al payment_intent.
• invoice.paid / payment_succeeded: anota la comisión de cada factura, incluidas las renovaciones.
• charge.refunded: marca la comisión como "reversed" (no la borra; corrige el libro).
• subscription.updated / deleted: actualiza el estado (activa, past_due, cancelada).
• account.updated: refresca charges_enabled del mentor.

Tus ingresos del panel salen de ese libro: bruto y comisión sumados sobre las filas que no están revertidas, y el neto es bruto − comisión.