VibeFox Datatrans for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo.
PHP: 8.0 o posterior.
HTTPS: tu sitio debe ser accesible desde internet mediante HTTPS para que Datatrans pueda entregar los webhooks.
Cuenta de Datatrans: necesitas el ID de comerciante, la contraseña de API de servidor a servidor y, recomendada, la clave de firma HMAC-SHA256 para los webhooks. Las credenciales de sandbox se obtienen en el Web Admin de sandbox de Datatrans (admin.sandbox.datatrans.com) y las de producción en el Web Admin de producción (admin.datatrans.com). Sandbox y producción son cuentas de Datatrans distintas, con ID de comerciante y claves diferentes.
Moneda: la moneda de la tienda (o la moneda del pedido de tu plugin multimoneda) debe estar activada en tu cuenta de comerciante de Datatrans.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_datatrans_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate. WooCommerce debe estar activo.
3. Abre los ajustes: WooCommerce > Settings > Payments > Datatrans > Manage, o haz clic en Settings bajo el nombre del plugin en la página de Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Introduce las credenciales de sandbox y, para pagos reales, las credenciales de producción (consulta Configuración).
6. Activa Enable/Disable. Mantén Sandbox mode activado mientras pruebas y desmárcalo después para aceptar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Datatrans. Cuando la pasarela está activada pero falta el ID de comerciante o la contraseña de API del entorno actual, la página muestra Datatrans is hidden at checkout until these settings are filled in: con la lista de los campos que faltan. Mientras el modo sandbox está activado, muestra Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.
Webhook
La Webhook URL se muestra en la parte superior de los ajustes. Tiene este aspecto: https://your-site/wc-api/datatrans_payment_callback/. El plugin envía esta URL a Datatrans con cada transacción, así que no tienes que introducirla en ningún sitio. También puedes introducirla en los ajustes de webhook del Web Admin de Datatrans para recibir las actualizaciones de las capturas y cancelaciones hechas allí.
El webhook informa del estado de la transacción. El plugin actúa según estos estados:
Con una clave de firma HMAC, cada webhook se comprueba mediante su cabecera Datatrans-Signature. Los webhooks sin una firma válida se rechazan. Sin clave de firma, el plugin no se fía del contenido del webhook y comprueba cada webhook con la API de estado de Datatrans. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda después de pagar.
General
Enable/Disable: Enable Datatrans Payment activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ven los clientes al finalizar la compra. Por defecto: Datatrans.
Description: el texto que se muestra bajo el método de pago al finalizar la compra. Por defecto: Pay securely via Datatrans.
Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Cambia tanto los hosts de la API y de la página de pago como las credenciales indicadas más abajo. Los reembolsos y las capturas siempre usan el entorno en el que se hizo el pago. Por defecto: activado. Desmárcalo para aceptar pagos reales.
Credenciales de sandbox
Cópialas del Web Admin de sandbox de Datatrans (admin.sandbox.datatrans.com). La clave de firma está allí, en los ajustes de seguridad.
Sandbox merchant ID: el ID de comerciante de tu cuenta de sandbox.
Sandbox API password: la contraseña de API de servidor a servidor de tu cuenta de sandbox.
Sandbox HMAC sign key: la clave hexadecimal que se usa para verificar la cabecera Datatrans-Signature de los webhooks. Sin ella, cada webhook se vuelve a comprobar con la API de estado de Datatrans.
Credenciales de producción
Cópialas del Web Admin de producción de Datatrans (admin.datatrans.com).
Production merchant ID: el ID de comerciante de tu cuenta de producción.
Production API password: la contraseña de API de servidor a servidor de tu cuenta de producción.
Production HMAC sign key: la clave hexadecimal que se usa para verificar la cabecera Datatrans-Signature de los webhooks de producción. Sin ella, cada webhook se vuelve a comprobar con la API de estado de Datatrans.
Una clave de firma debe ser una cadena hexadecimal tal como la emite Datatrans. Cualquier otro valor no se guarda: la página muestra un error y conserva el valor anterior. Si actualizas desde la versión 1.0, el único conjunto de credenciales de esa versión se mueve a los campos de sandbox si el modo sandbox estaba activado; en caso contrario, se queda en los campos de producción.
Procesamiento del pago
Auto settle: Capture (settle) payments immediately. Por defecto: activado. Si lo desactivas, los pagos solo se autorizan: el pedido pasa a En espera y lo capturas más tarde con la acción del pedido Capture Datatrans payment, o lo liberas con Cancel Datatrans authorization.
Order status after payment: el estado del pedido que se establece cuando el pago queda liquidado. El estado se establece de inmediato, sin un segundo cambio de estado.
Avanzado
Logging: Log payment events and API calls escribe los detalles en WooCommerce > Status > Logs, origen wcp_datatrans_gateway. Los errores se registran siempre. No se escriben claves, datos de tarjeta ni datos de clientes. Por defecto: desactivado.
Delete data on uninstall: Remove the plugin settings when the plugin is deleted. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Datatrans) y realiza el pedido. El plugin crea una transacción de Datatrans por el total del pedido en la moneda del pedido, con el ID del pedido como referencia, y envía al cliente a la página de pago de Datatrans. Allí el cliente paga con cualquier método activado en tu cuenta de Datatrans, por ejemplo una tarjeta, TWINT o PostFinance. La página de pago se abre en alemán, inglés, francés o italiano cuando tu sitio usa uno de estos idiomas; en caso contrario, Datatrans elige el idioma.
Tras pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido solo se marca como pagado cuando Datatrans lo confirma: mediante el webhook o mediante una solicitud del servidor a la API de estado de Datatrans cuando el cliente vuelve. La dirección de retorno lleva la clave del pedido, y el retorno en sí nunca marca un pedido como pagado.
Si el cliente cancela en la página de pago, va a la página Pay for order con el mensaje The payment was canceled. You can try again or choose another payment method. Tras un pago fallido, el mensaje es The payment was not completed. Please try again or choose another payment method. El pedido sigue pudiendo pagarse y el cliente puede intentarlo de nuevo.
Si Datatrans no puede iniciar el pago, el cliente ve The payment could not be started. Please try again or choose another payment method. El motivo se escribe en el registro.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) de WooCommerce.
El plugin solo admite pagos únicos en la página de pago de Datatrans. No tiene tarjetas guardadas ni alias, suscripciones, integración de Lightbox o Secure Fields, elección de métodos de pago en los ajustes ni captura parcial de una autorización.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a Datatrans y aún no ha pagado, canceló en la página de pago, o Datatrans todavía no ha confirmado el pago. Cada transacción nueva se anota en el pedido con su ID y su entorno.
Processing, Completed or On Hold: el pago quedó liquidado. El estado sigue lo indicado en Order status after payment. La nota del pedido muestra el importe, el método de pago, el ID de transacción de Datatrans y el entorno (sandbox o producción). El ID de transacción se guarda en el pedido.
On hold, authorized: con Auto settle desactivado, el pago se autorizó pero no se capturó. Abre el pedido y elige Capture Datatrans payment o Cancel Datatrans authorization en las acciones del pedido. La captura usa el total actual del pedido, que no debe ser superior al importe autorizado. Si lo es, o si Datatrans rechaza la captura o la cancelación, el motivo se añade a las notas del pedido.
On hold after payment: Datatrans notificó un importe o una moneda distintos del total del pedido (por ejemplo, el pedido se editó después de iniciar el pago), o el pago llegó después de que el pedido se hubiera cancelado. La nota del pedido lo explica. Comprueba la transacción en el Web Admin de Datatrans y tramita el pedido o reembolsa el pago.
Failed: el pago falló o fue rechazado. El cliente puede intentarlo de nuevo.
Cancelled: la autorización se liberó, mediante la acción del pedido o en el Web Admin de Datatrans.
Un aviso tardío de fallo o cancelación nunca cambia un pedido pagado. Si llega un segundo pago correcto para un pedido que ya está pagado, el pedido no cambia. Una nota avisa de un posible cobro doble y te pide que lo reembolses en Datatrans si es necesario.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Datatrans. Se admiten reembolsos totales y parciales. El reembolso se envía en el entorno en el que se hizo el pago, por lo que deben estar configuradas las credenciales de ese entorno. Un reembolso reintentado no se abona dos veces. Si Datatrans no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el importe y el ID de la transacción de reembolso de Datatrans.
En un pago que solo está autorizado, un reembolso del importe total cancela la autorización. No es posible un reembolso parcial hasta que el pago se capture.
Los reembolsos hechos en el Web Admin de Datatrans no se registran en WooCommerce. Si es necesario, crea un reembolso manual en WooCommerce sin Refund via Datatrans.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Datatrans. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Datatrans no se muestra a los clientes al finalizar la compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda con sesión iniciada siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un aviso en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando, y los reembolsos y las capturas funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Datatrans no aparece al finalizar la compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el ID de comerciante y la contraseña de API del entorno actual estén definidos: los campos de sandbox en modo sandbox, los de producción en caso contrario. La página de ajustes enumera los campos que faltan.
El pago se realizó, pero el pedido sigue en Pendiente de pago: Datatrans no pudo acceder a la URL del webhook y el cliente no volvió a la tienda. Comprueba que el sitio sea accesible desde internet mediante HTTPS y que ningún plugin de seguridad ni cortafuegos bloquee las solicitudes a /wc-api/datatrans_payment_callback/. Comprueba que la clave de firma de los ajustes corresponda al entorno del pago. Activa Logging y consulta WooCommerce > Status > Logs, origen wcp_datatrans_gateway.
El webhook responde Invalid signature: la clave de firma HMAC de los ajustes no coincide con la del Web Admin de Datatrans o pertenece al otro entorno. Vuelve a copiar la clave.
El webhook responde Not configured o Verification failed: el webhook debía comprobarse con la API de estado de Datatrans, pero faltan las credenciales de ese entorno o Datatrans no respondió. Datatrans reintenta el webhook.
La clave de firma HMAC no se guarda: la clave debe ser una cadena hexadecimal. Vuelve a copiarla del Web Admin de Datatrans.
El cliente ve The payment could not be started: el ID de comerciante o la contraseña de API son incorrectos, pertenecen al otro entorno, o la moneda no está activada en tu cuenta de Datatrans. Activa Logging para ver el motivo.
El pedido está En espera tras el pago: lee la nota del pedido. El importe o la moneda pagados diferían del pedido, el pago llegó después de cancelar el pedido, o el pago solo está autorizado y espera la captura.
La captura no es posible: el total del pedido es superior al importe autorizado. La captura usa el total actual del pedido, así que redúcelo al importe autorizado o a menos.
El reembolso falla con un mensaje sobre credenciales: el pago se hizo en el otro entorno y sus credenciales no están definidas. Introdúcelas e inténtalo de nuevo. En un pago autorizado, reembolsa el importe total o captúralo primero.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Para desarrolladores, el readme menciona el filtro wcp_datatrans_gateway_init_request, por ejemplo para limitar los métodos de pago mostrados en la página de Datatrans.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin se eliminan siempre. Los ajustes de la pasarela solo se eliminan si Delete data on uninstall estaba activado. En caso contrario, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Datatrans es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Datatrans ni cuenta con su respaldo.