Charitable Pro 1.8.13+ puede registrar la comisión de procesamiento real cobrada por su pasarela de pago contra cada donación. Cuando está habilitado, la comisión aparece en la página de administración de donaciones individuales y se incluye en las exportaciones de donaciones en formato CSV.
Pasarelas compatibles: Stripe, PayPal (Standard / IPN)
Tabla de Contenidos
Requisitos
- Charitable Pro: Versión 1.8.13 o superior
- Pasarela: Stripe o PayPal (Standard). Otras pasarelas no son compatibles.
Cómo funciona
El seguimiento de comisiones es pasivo: captura la comisión notificada por la pasarela en el momento en que se confirma el pago, sin llamadas API adicionales.
Stripe: La comisión de procesamiento se lee del campo balance_transaction.fee del objeto de cargo de Stripe cuando el webhook de Stripe procesa la confirmación del pago. La comisión se convierte de la unidad monetaria más pequeña de la pasarela (centavos) a una cantidad decimal antes de almacenarse.
PayPal: La comisión de procesamiento se lee del campo mc_fee en la carga útil de la notificación IPN de PayPal. Se almacena tal cual, ya que PayPal ya la envía como una cantidad decimal.
En ambos casos, la comisión se almacena una vez y nunca se sobrescribe. Si PayPal reintenta una IPN o Stripe dispara un evento de webhook duplicado, se conserva el valor original (idempotencia).
Habilitar el seguimiento de comisiones
El seguimiento de comisiones está deshabilitado por defecto. Para habilitarlo, agregue el siguiente fragmento a functions.php del tema o a un plugin específico del sitio:
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );No se necesita ninguna otra configuración. Una vez habilitado, la comisión se registrará para todas las donaciones nuevas de Stripe y PayPal en adelante. Las donaciones existentes no se actualizan retroactivamente.
Deshabilitar el seguimiento de comisiones
Elimine el fragmento anterior o devuelva explícitamente false:
add_filter( 'charitable_show_gateway_processing_fee', '__return_false' );Deshabilitar el seguimiento detiene el registro de nuevas comisiones. No elimina los datos de comisiones ya almacenados en donaciones existentes.
Dónde aparece la comisión
Cuando el seguimiento de comisiones está habilitado, aparece una fila de Comisión de procesamiento de la pasarela en la sección de metadatos de la donación de la página de administración de donaciones individuales (Donaciones – haga clic en cualquier donación para verla). El valor tiene el formato de una cantidad de moneda utilizando la moneda de la donación.
La fila se oculta automáticamente para cualquier pasarela que no sea Stripe o PayPal, incluso si el filtro está habilitado.
Exportación CSV
Cuando el seguimiento de comisiones está habilitado, se incluye una columna de Comisión de procesamiento de la pasarela en las exportaciones de donaciones en formato CSV. El valor tiene el formato de una cantidad de moneda. Esta columna no aparece en las exportaciones cuando el filtro está deshabilitado.
Importe neto
Hay una función de ayuda disponible para calcular el importe neto recibido después de las comisiones:
Net = Donation Total - Gateway Processing Fee - Stripe Connect Application Fee (if applicable)La comisión de aplicación de Stripe Connect (almacenada por separado como _stripe_application_fee_amount) solo está presente en sitios que utilizan Stripe Connect. Para donaciones estándar de Stripe y PayPal, es cero.
Para recuperar el importe neto en código:
$net = charitable_gateway_fees_get_net_amount( $donation );
// Returns a formatted currency string, or false if no fee data is stored.Notas y limitaciones
- Los datos de comisiones solo se registran a partir del momento en que se habilita el filtro. No existe una herramienta para rellenar comisiones de donaciones anteriores.
- La captura de comisiones de PayPal requiere que IPN funcione correctamente. Si IPN no está configurado o falla, no se registrará ninguna comisión.
- La captura de comisiones de Stripe requiere que el webhook de Stripe esté activo y entregue eventos
charge.succeededopayment_intent.succeededconbalance_transactionexpandido. - El campo de comisión solo se muestra en los metadatos de administración de donaciones y en la exportación CSV para donaciones de Stripe y PayPal, incluso si los datos de comisión existen de alguna manera en una donación de otra pasarela.
- Para cuentas de Stripe Connect, la comisión de la aplicación de la plataforma (
_stripe_application_fee_amount) se almacena por separado y se resta además de la comisión de procesamiento al calcular los importes netos.
Referencia del desarrollador
Filtro
charitable_show_gateway_processing_fee – Controla si el seguimiento de comisiones de pasarela está activo. Devuelve true para habilitar, false para deshabilitar (predeterminado).
// Enable fee tracking site-wide.
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );Claves meta
| Clave de metadatos | Descripción |
|---|---|
_tarifa_procesamiento_pasarela | El importe de la comisión de procesamiento de la pasarela como un número decimal flotante (por ejemplo, 0.59). Almacenado en la publicación de donación. |
_importe_tarifa_aplicacion_stripe | Comisión de la aplicación de la plataforma de Stripe Connect. Solo presente en donaciones de Stripe Connect. |
Ganchos
charitable_paypal_web_accept – Acción que se dispara cuando se recibe una notificación IPN web_accept de PayPal. El módulo de comisiones de pasarela se engancha a esto en la prioridad 10 para capturar mc_fee.
do_action( 'charitable_paypal_web_accept', $data, $donation_id );charitable_default_donation_fields – Filtro utilizado para registrar el campo gateway_processing_fee en el sistema de campos de Charitable. Solo se registra cuando charitable_show_gateway_processing_fee devuelve true.
charitable_donation_admin_meta – Filtro utilizado para ocultar la fila de comisiones de los metadatos de administración de donaciones para pasarelas no compatibles.
charitable_export_donations_format_money_fields – Filtro utilizado para incluir gateway_processing_fee como una columna con formato de dinero en las exportaciones CSV cuando el seguimiento está habilitado.
