VibeFox Datatrans for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

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 separadas, con ID de comerciante y claves distintos.

Tienda accesible: Datatrans envía los webhooks desde sus propios servidores, así que tu tienda debe ser accesible desde internet.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca más tarde VibeFox Datatrans Gateway en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).

4. Introduce las credenciales de sandbox del Web Admin de sandbox de Datatrans (véase Configuración).

5. Activa Enable/Disable y haz clic en Save. Haz un pago de prueba en modo sandbox. Cuando todo funcione, introduce las credenciales de producción y desactiva Sandbox mode.

Al instalarse, el módulo crea el estado de pedido Datatrans payment on hold. PrestaShop habilita por defecto el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences; Datatrans se muestra solo para las monedas permitidas allí.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cuando el método de pago está activado pero el entorno actual no tiene ID de comerciante o contraseña de API, la página muestra Datatrans is hidden at checkout until these settings are filled in: con los campos que faltan. Mientras el modo sandbox está activado, la página muestra Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Datatrans

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 ve el cliente al finalizar la compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Datatrans. Obligatorio.

Description: el texto que se muestra debajo del método de pago al finalizar la compra. Por defecto: Pay securely via Datatrans.

Sandbox mode: usa el sandbox de Datatrans: pagos de prueba, sin dinero real. Cambia tanto los servidores de Datatrans como las credenciales usadas para los nuevos pagos. Por defecto: activado. Desactívalo para aceptar pagos reales. Mientras esté activado, el cliente ve Sandbox mode: no real payment is taken. debajo del método de pago. Los reembolsos y las capturas siempre usan el entorno en el que se hizo el pago, sea cual sea la posición de este interruptor.

Credenciales de sandbox

Cópialas desde el Web Admin de sandbox de Datatrans (admin.sandbox.datatrans.com). La clave de firma está allí, en la configuración 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 la cuenta de sandbox.

Sandbox HMAC sign key: la clave hexadecimal usada 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 desde el 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 la cuenta de producción.

Production HMAC sign key: la clave hexadecimal usada 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.

Las contraseñas y claves de firma guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. 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, y los demás ajustes sí se guardan.

Clear saved secrets: marca una contraseña o clave de firma y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.

URL del webhook

La sección muestra la URL del webhook de tu tienda. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_datatrans_gateway/webhook, posiblemente con un código de idioma, como /en/. El módulo envía esta URL a Datatrans en cada transacción, así que no tienes que introducirla en ningún sitio. También puedes introducirla en la configuración de webhooks del Web Admin de Datatrans para recibir actualizaciones de las capturas y cancelaciones hechas allí; cópiala exactamente como la muestra la configuración. Los reembolsos hechos en el Web Admin de Datatrans no se reflejan en el pedido.

El webhook informa del estado de la transacción. El módulo actúa según estos estados:

Con una clave de firma HMAC, cada webhook se verifica mediante su cabecera Datatrans-Signature con la clave de firma del entorno en el que se hizo el pago. Los webhooks sin firma válida se rechazan. Sin clave de firma, el módulo no confía en el contenido del webhook y comprueba cada webhook con la API de estado de Datatrans. Sin el webhook, un pedido solo se crea cuando el cliente vuelve a la tienda después de pagar.

Procesamiento del pago

Auto settle: captura (liquida) los pagos inmediatamente. Si está desactivado, los pagos solo se autorizan: el pedido pasa a Datatrans payment on hold y lo capturas más tarde con Capture Datatrans payment en el bloque de Datatrans del pedido, o lo liberas con Cancel Datatrans authorization. Por defecto: activado.

Order status after payment: el estado del pedido una vez liquidado el pago.

Los pagos solo autorizados y las diferencias de importe o moneda siempre van a Datatrans payment on hold.

Avanzado

Logging: registra los eventos de pago y las llamadas a la API en logs/datatrans_p_debug.log.php de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso con este interruptor desactivado. No se escriben claves, datos de tarjetas ni datos de clientes. Por defecto: desactivado.

Log: muestra el tamaño y las últimas entradas del registro, con un botón para borrarlo.

Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan sus ajustes y el registro. Los registros de pagos de Datatrans de los pedidos (transacciones, reembolsos) y el estado del pedido siempre se conservan. Por defecto: desactivado.

Finalizar compra

En el paso de pago el cliente elige el método de pago (por defecto Datatrans) y ve la nota You will be redirected to the Datatrans payment page to complete the payment securely. Al confirmar, el módulo crea una transacción de Datatrans por el total del carrito en la moneda del carrito y envía al cliente a la página de pago de Datatrans. La página se abre en alemán, inglés, francés o italiano si el idioma de la tienda es uno de ellos. Allí el cliente paga con cualquier método activado en tu cuenta de Datatrans. Todavía no existe ningún pedido en este punto.

Después de pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando Datatrans lo confirma: mediante el webhook o mediante una petición del servidor a la API de estado de Datatrans cuando el cliente vuelve. La dirección de retorno incluye la clave segura del carrito, y el retorno en sí nunca crea un pedido. Después se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with Datatrans has been received. En un pago solo autorizado, la página muestra Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Si Datatrans aún no ha confirmado el pago, una página de Payment confirmation muestra Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. con un botón Check again; el webhook crea el pedido en cuanto llega.

Si el cliente cancela en la página de Datatrans, vuelve a la finalización de compra con The payment was canceled. You can try again or choose another payment method. Si el pago falló, el mensaje es The payment was not completed. Please try again or choose another payment method. El carrito se conserva. Un nuevo intento crea una nueva transacción de Datatrans; un pago tardío de un intento anterior sigue siendo reconocido.

Si Datatrans no puede iniciar el pago, el cliente se queda en la finalización de compra con The payment could not be started. Please try again or choose another payment method. El motivo técnico se escribe en el registro.

El webhook funciona mientras la tienda está en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.

El módulo acepta pagos únicos en la página de pago de Datatrans. No tiene tarjetas guardadas ni alias, suscripciones, Lightbox ni Secure Fields en tu sitio, elección de métodos de pago en la configuración ni captura parcial de una autorización.

Pedidos y reembolsos

Estados del pedido

Aún sin pedido: el cliente fue enviado a Datatrans y no ha pagado, el pago falló o fue cancelado, o Datatrans aún no lo ha confirmado. Solo existe el carrito.

Payment accepted, Delivered or Datatrans payment on hold: el pago fue liquidado. El estado sigue a Order status after payment. El pago se registra con el ID de transacción de Datatrans, y una nota muestra el importe, el método de pago, el entorno y cómo se confirmó (webhook o retorno).

Datatrans payment on hold tras una autorización: Auto settle está desactivado y el pago solo está autorizado. Captúralo o cancélalo en el bloque del pedido.

Datatrans payment on hold tras el pago: Datatrans informó un importe o una moneda distintos del total del carrito (por ejemplo, el carrito se cambió después de iniciar el pago), o el pago llegó después de que el pedido se hubiera cancelado. La nota lo explica. Revisa la transacción en el Web Admin de Datatrans y completa el pedido o reembolsa el pago.

Canceled: la autorización fue liberada, en el bloque del pedido o en el Web Admin de Datatrans.

Refunded: el pago fue reembolsado en su totalidad a través del módulo.

Si llega un segundo pago para un carrito que ya está pagado o autorizado, el pedido no cambia. Una nota pide que lo compruebes y reembolses el duplicado en Datatrans. Una transacción fallida o cancelada nunca degrada un pedido pagado.

Bloque Datatrans payment

La página del pedido muestra un bloque Datatrans payment con el ID de transacción, el estado de Datatrans, el método de pago, el importe, los importes pagados y reembolsados, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las Datatrans notes del pedido. Las acciones del bloque requieren el permiso para editar pedidos; no hace falta acceso a las páginas de módulos.

Captura y cancelación

En un pago solo autorizado, el bloque muestra Capture Datatrans payment y Cancel Datatrans authorization. La captura liquida el pago por el total actual del pedido, que no debe ser mayor que el importe autorizado; después el pedido pasa al estado de Order status after payment. La cancelación libera la autorización y pone el pedido en Canceled. Ambas acciones van al entorno del pago. Si Datatrans lo rechaza, el bloque muestra el error y se añade una nota.

Reembolsos

En el bloque Datatrans payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Datatrans. Confirma la pregunta Refund this amount through Datatrans? This cannot be undone. Se admiten reembolsos totales y parciales, hasta el importe que Datatrans realmente cobró menos los reembolsos anteriores. El reembolso se envía al entorno del pago, por lo que deben estar configurados el ID de comerciante y la contraseña de API de ese entorno. Un reembolso reintentado no se abona dos veces. Si Datatrans no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso exitoso se añade al historial y a las notas con el ID de transacción de reembolso de Datatrans. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado.

En un pago solo autorizado todavía no se ha cobrado nada: solo se puede "reembolsar" el importe total, lo que cancela la autorización. Los reembolsos están disponibles cuando Datatrans ha liquidado el pago; una autorización con un importe no coincidente no se puede reembolsar hasta que se liquide.

El módulo no crea abonos (credit slips). Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de Datatrans. Los reembolsos hechos en el Web Admin de Datatrans no se registran en PrestaShop.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Datatrans Gateway es el primer bloque de Modules > Module Manager > VibeFox Datatrans Gateway > Configure, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-datatrans y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de que cambie la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda 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 en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. La tienda pública no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No se necesita ninguna tarea cron. Al desinstalar o restablecer el módulo, la clave de licencia y el estado de la licencia siempre se eliminan.

Solución de problemas

Datatrans does not appear at checkout: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el entorno actual tenga su ID de comerciante y su contraseña de API: los campos de sandbox en modo sandbox, los campos de producción en caso contrario. La página de configuración muestra los campos que faltan. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.

The payment went through, but no order was created: Datatrans no pudo llegar a la URL del webhook y el cliente no volvió a la tienda. Comprueba que la tienda sea accesible desde internet y que ningún cortafuegos bloquee las peticiones a la URL del webhook. Comprueba que la clave de firma de la configuración pertenezca al entorno del pago. Revisa el campo Log en la página del módulo.

Webhook answers Invalid signature: la clave de firma HMAC de la configuración no coincide con la del Web Admin de Datatrans, o pertenece al otro entorno. Copia la clave de nuevo.

Webhook answers Not configured or Verification failed: el webhook tenía que comprobarse con la API de estado de Datatrans, pero faltan las credenciales de ese entorno, o Datatrans no respondió. Datatrans reintenta el webhook.

Webhook answers Busy, retry: otra petición estaba confirmando el pedido en ese mismo momento, o el pedido no se pudo crear (por ejemplo, el módulo está desactivado). Datatrans reintenta el webhook. El registro muestra el motivo.

The webhook URL shows Method not allowed in the browser: es normal. La URL solo acepta peticiones de Datatrans.

The HMAC sign key is not saved: la clave debe ser una cadena hexadecimal. Cópiala de nuevo desde el Web Admin de Datatrans.

The customer sees Datatrans payments are not configured yet: falta el ID de comerciante o la contraseña de API del entorno actual.

The customer sees The payment could not be started: revisa el campo Log. Un ID de comerciante o una contraseña de API incorrectos, o credenciales del entorno equivocado, son las causas habituales.

Order is Datatrans payment on hold after payment: lee las Datatrans notes en el bloque del pedido (véase Estados del pedido) y luego completa el pedido o reembolsa el pago.

Capture is refused: el total del pedido es mayor que el importe autorizado. Datatrans no puede liquidar más de lo autorizado.

Refund or capture fails with a message about missing credentials: el pago se hizo en el otro entorno, y su ID de comerciante o contraseña de API no están configurados. Introdúcelos y vuelve a intentarlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Datatrans Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y reembolsos de Datatrans y el estado de pedido Datatrans payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar o capturar tras una reinstalación. Los pedidos existentes conservan sus notas de pago e ID de transacción.

Datatrans es una marca comercial de su respectivo titular. Este módulo no está afiliado a Datatrans ni es respaldado por Datatrans.