VibeFox Transbank for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

Moneda de la tienda: peso chileno (CLP). Webpay Plus cobra solo pesos enteros, así que pon Number of decimals en 0 en WooCommerce > Settings > General. En tiendas con otra moneda no se muestra el método de pago.

Cuenta de Transbank: para pagos reales necesitas un comercio estándar de Webpay Plus (captura inmediata) con su Commerce Code de producción y su API Key Secret. Transbank te entrega el Commerce Code cuando se aprueba tu afiliación, y la API Key Secret después del proceso de validación de integración (consulta la documentación para desarrolladores de Transbank). Para las pruebas no hacen falta credenciales. Los códigos de comercio de Webpay Plus Mall, Oneclick y de captura diferida no son compatibles.

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_transbank_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Pon la moneda de la tienda en peso chileno y Number of decimals en 0 en WooCommerce > Settings > General.

4. Abre los ajustes: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.

5. 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.

6. Activa Enable / Disable y prueba un pago con Integration (test) mode activado, usando las tarjetas de prueba de la documentación para desarrolladores de Transbank.

7. Para pasar a real, introduce tu Production Commerce Code y tu Production API Key Secret, desmarca Integration (test) mode y guarda.

No hace falta configurar en Transbank ninguna URL de retorno ni webhook. El plugin envía su URL de retorno con cada transacción.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Transbank Webpay Plus. Encima de los campos, la página te avisa cuando está seleccionada la producción pero falta el código de comercio de producción o la API Key, o no es válida (en ese caso Webpay se oculta en la finalización de compra); cuando la moneda de la tienda no es CLP (el método de pago se oculta); y cuando los precios en CLP tienen decimales (los totales se redondean a pesos enteros). Mientras el modo de integración esté activado, la página muestra Integration (test) environment: no se cobra dinero real. Después de guardar, los avisos ya siguen los nuevos ajustes. En la lista de métodos de pago, la pasarela aparece marcada como pendiente de configuración cuando está seleccionada la producción sin credenciales válidas.

General

Enable / Disable: Enable Transbank Webpay Plus payments activa o desactiva el método de pago. Por defecto: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. Por defecto: Webpay Plus.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with credit, debit or prepaid card via Webpay.

Entorno y credenciales

El texto de la sección enlaza con la documentación para desarrolladores de Transbank y explica cuándo Transbank te entrega las credenciales de producción.

Integration (test) mode: Use the Transbank integration environment. Los pagos van al entorno de integración de Transbank con su código de comercio de prueba público (597055555532), que se rellena automáticamente. Las credenciales de producción de abajo no se usan y no se cobra dinero real. Por defecto: activado. Desmárcalo para pasar a real.

Production Commerce Code: tu código de comercio de producción (Tbk-Api-Key-Id): 12 dígitos, que empiezan por 5970. Si el tuyo tiene 8 dígitos, introdúcelo tal cual; el plugin añade el prefijo 5970 al guardar. Se eliminan los espacios y otros caracteres. Los códigos de comercio de prueba públicos de Transbank no se aceptan en producción.

Production API Key Secret: el Tbk-Api-Key-Secret de tu comercio de producción. Mantenlo en secreto. Se eliminan los espacios al guardar.

Avanzado

Debug log: Log API requests and returns (errors are always logged). Los detalles se escriben en WooCommerce > Status > Logs, origen wcp_transbank_gateway; el campo tiene un enlace view logs. Los errores y avisos se registran aunque esta opción esté desactivada. No se registran datos de tarjeta, claves API ni tokens completos. Por defecto: desactivado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept). Por defecto: desactivado.

Pruebas y producción

Integration (test) mode decide adónde van los nuevos pagos. Cada pago recuerda su entorno: la confirmación y los reembolsos de un pago siempre van al entorno (integración o producción) y con las credenciales con las que se creó, aunque cambies el modo más tarde.

Finalización de compra

El cliente elige el método de pago (por defecto Webpay Plus) y realiza el pedido. En modo de integración, la finalización de compra muestra TEST MODE: entorno de integración. Sin cargos reales. El plugin crea una transacción de Transbank por el total del pedido en pesos enteros (un total con decimales se redondea al peso más cercano) y envía al cliente a una página breve Redirecting to Webpay. Please wait..., que lo reenvía al formulario de Webpay. Sin JavaScript, el cliente hace clic en Proceed to Webpay. En Webpay, el cliente paga con tarjeta de crédito, débito o prepago.

Cuando el cliente vuelve, el plugin confirma (commit) la transacción con Transbank de servidor a servidor. El pedido se marca como pagado solo después de que Transbank la confirme: la respuesta debe ser aprobada, y el importe, la orden de compra y la sesión deben coincidir con lo que la tienda envió para este intento. Después, el cliente ve la página de pedido recibido. Si la llamada de confirmación falla, por ejemplo por un tiempo de espera, el plugin pide a Transbank el estado de la transacción. Si aun así no se puede conocer el estado, el pedido no cambia y el cliente ve We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.

Si el cliente cancela en Webpay, el formulario de Webpay caduca o da un error, no se cobra nada. El pedido sigue pendiente de pago y el cliente vuelve a la página Pay for order con un mensaje, por ejemplo You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Una tarjeta rechazada muestra Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. El cliente puede volver a pagar desde la misma página. Cada nuevo intento es una nueva transacción de Webpay.

Cada intento de Webpay se confirma como máximo una vez. Recargar la página de retorno, usar el botón Atrás del navegador o un segundo retorno al mismo tiempo nunca confirman dos veces ni cambian el pedido. Si un pedido ya no necesita pago (ya pagado con otro intento, cancelado o reembolsado), un retorno tardío no se confirma, así que Transbank no lo cobra. El cliente ve This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

Si Webpay no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo Could not connect to Webpay. Please try again in a moment. o Webpay payments are not available at the moment. Please choose another payment method. El motivo técnico se guarda 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 WooCommerce High-Performance Order Storage (HPOS).

Transbank no tiene webhook de pago: el resultado se procesa cuando el cliente vuelve de Webpay. Si el cliente cierra el navegador en Webpay y nunca vuelve, la transacción no se confirma y el pedido sigue pendiente; según Transbank, las transacciones no confirmadas no se liquidan. El plugin no incluye Webpay Plus Mall, tarjetas guardadas de Oneclick, suscripciones, captura diferida ni conversión de moneda.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente fue enviado a Webpay y aún no ha pagado, canceló, dejó caducar el formulario, o el pago todavía no se pudo confirmar. Una nota registra cada intento cerrado con su orden de compra.

Processing or Completed: Transbank aprobó el pago. El estado lo asigna WooCommerce: Procesando, o Completado para pedidos con solo productos virtuales descargables. La nota del pedido muestra el código de autorización, las últimas cuatro cifras de la tarjeta, la orden de compra, el importe, el tipo de pago y el número de cuotas. El ID de la transacción es el token de Webpay.

On hold: Transbank autorizó un pago que no coincide con el pedido (importe, orden de compra o ID de sesión), por ejemplo porque el pedido se editó después de iniciar el pago. La nota enumera las diferencias. Revisa el portal de Transbank y reembolsa o completa el pedido.

Failed: el pago fue rechazado. No se cobró nada. La nota muestra el código de respuesta y el estado.

Si Webpay devuelve un pago de un pedido que ya está pagado, cancelado o reembolsado, el pago no se confirma y una nota te pide revisar el portal de Transbank si el cliente informa de un cargo. Los pedidos existentes no se ven afectados por intentos posteriores.

Reembolsos

El botón de reembolso solo se ofrece en pedidos pagados con Webpay. Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Webpay Plus (el botón usa el título del método de pago). Se admiten reembolsos totales y parciales en pesos enteros. Un importe parcial con decimales se rechaza con Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. El último resto de un total con decimales se redondea igual que el cobro. El reembolso va al entorno donde se hizo el pago, así que en producción deben estar configuradas las credenciales de producción.

Transbank responde con una reversa (REVERSED) o una anulación (NULLIFIED). Un reembolso correcto se añade a las notas del pedido con el importe, el tipo, el código de autorización y el saldo que queda en Transbank. Si Transbank no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Los reembolsos hechos en el portal de Transbank no se importan a WooCommerce.

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 > Transbank Webpay Plus. 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 volver a comprobar el estado, 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, Webpay Plus no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda que han iniciado sesión 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. Un recordatorio aparece 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 funcionan.

Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

Webpay Plus no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado, que la moneda de la tienda sea CLP (en la página Pay for order, la moneda del pedido) y, con el modo de integración desactivado, que estén guardados un Production Commerce Code válido (12 dígitos, que empiezan por 5970) y una Production API Key Secret. La página de ajustes muestra un aviso por cada condición que falte.

El pago se realizó, pero el pedido sigue en Pending payment: Transbank no tiene webhook, así que el pedido solo se confirma cuando el cliente vuelve de Webpay. Si el cliente cerró el navegador en Webpay, la transacción no se confirmó y, según Transbank, no se liquida. Revisa las notas del pedido, el registro y la transacción en el portal de Transbank.

El cliente ve We could not confirm your Webpay payment with Transbank: la llamada de confirmación falló y no se pudo comprobar el estado. El pedido no cambió y se añadió una nota. El cliente puede volver a intentarlo en un momento. Si el portal de Transbank muestra la transacción como autorizada, confirma allí la transacción antes de enviar el pedido.

El cliente ve un error al realizar el pedido: activa Debug log y mira WooCommerce > Status > Logs, origen wcp_transbank_gateway. Webpay payments are not available at the moment suele indicar credenciales de producción incorrectas. Could not connect to Webpay significa que no se pudo contactar con Transbank. Un pedido en una moneda distinta de CLP no se puede pagar con Webpay.

Los totales y los reembolsos difieren en unos pesos: los precios en CLP tienen decimales. Webpay cobra pesos enteros, así que los totales se redondean. Pon Number of decimals en 0.

El reembolso falla con The production Commerce Code / API Key are missing: el pago se hizo en producción y las credenciales de producción no están guardadas. Introdúcelas y vuelve a intentarlo.

El reembolso falla con Transbank refused the refund o Transbank did not approve the refund: Transbank no lo aceptó; el mensaje muestra el motivo o el tipo y el código de respuesta que devolvió. No se reembolsó nada. Revisa la transacción en el portal de Transbank.

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 en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.

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 licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, las demás opciones y los datos temporales del plugin, así como sus registros (archivos de log, incluidos los rotados, y las entradas de registro de la base de datos), solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los datos de Transbank almacenados en los pedidos siempre se conservan, porque se necesitan para la contabilidad y los reembolsos. Los pedidos existentes conservan sus notas de pago y los IDs de transacción.

Transbank y Webpay son marcas comerciales de sus respectivos titulares. Este plugin no está afiliado a Transbank ni cuenta con su respaldo.