VibeFox Xendit 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: IDR, PHP, VND, THB, MYR, USD o SGD. Para otras monedas no se muestra el método de pago. Qué canales de pago y monedas están realmente disponibles depende de tu cuenta de Xendit.
Cuenta de Xendit: necesitas una clave secreta de API con permiso de escritura para Money-in (facturas) para el modo de prueba y otra para el modo real, y el token de verificación de webhook de cada modo (véase Configuración). Solo se usan las claves secretas y los tokens de verificación. No hace falta ninguna clave pública, porque el cliente paga en la página de factura alojada de Xendit.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_xendit_payment_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Xendit > Manage, o haz clic en Settings debajo del 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. Pega tus claves secretas de Xendit, configura la URL del webhook en el Panel de control de Xendit y pega los tokens de verificación (véase Configuración).
6. Activa Enable/Disable. Haz un pedido de prueba en modo de prueba y, después, desmarca Test Mode para aceptar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Xendit. Encima de los campos, un aviso muestra el modo activo: TEST MODE (las facturas se crean con la clave secreta de prueba y no se cobra dinero real) o LIVE MODE (las facturas se crean con la clave secreta real y se cobra a los clientes). El aviso advierte cuando falta la clave secreta del modo activo o tiene el prefijo incorrecto (en ese caso el método de pago se oculta en la finalización de compra), y cuando el token de verificación de webhook del modo activo está vacío (las notificaciones de Xendit se rechazan, así que los pedidos solo se actualizan cuando el cliente vuelve a tu tienda). En la lista de métodos de pago, Xendit aparece como pendiente de configuración hasta que el modo activo tenga una clave secreta válida.
General
Enable/Disable: Enable Xendit activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Predeterminado: Xendit.
Description: el texto que aparece debajo del método de pago en la finalización de compra. Predeterminado: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.
Claves de API
Crea una clave secreta de API con permiso de escritura para Money-in (facturas) en Xendit Dashboard > Settings > Developers > API keys, una vez en modo de prueba y otra en modo real. La clave decide dónde se crea la factura. Al guardar, una clave que no empieza por el prefijo de su campo no se guarda, y la página muestra, por ejemplo, Test secret key was not saved: it must start with xnd_development_. Los demás ajustes sí se guardan.
Test Mode: Enable test mode crea las facturas con la clave secreta de prueba, así que no se cobra dinero real. Predeterminado: activado. Desmárcalo para aceptar pagos reales con la clave secreta real.
Test Secret Key: la clave secreta del modo de prueba de Xendit. Empieza por xnd_development_.
Live Secret Key: la clave secreta del modo real de Xendit. Empieza por xnd_production_.
Webhooks
El webhook avisa a tu tienda de que una factura se ha pagado. En Xendit Dashboard > Settings > Developers > Webhooks, configura la URL que aparece en esta sección de los ajustes para Invoices > Invoice paid, en modo de prueba y en modo real. Opcionalmente, configúrala también para Invoice expired. La URL tiene este aspecto: https://your-site/wc-api/xendit_p_callback/. Cópiala exactamente como aparece en los ajustes.
Después, copia el Webhook verification token de cada modo desde el Panel de control de Xendit en el campo correspondiente. Xendit lo envía en la cabecera x-callback-token. Las notificaciones sin el token del modo en el que se creó la factura se rechazan. El token solo demuestra que la notificación viene de Xendit: el estado, el importe y la moneda de la factura siempre se vuelven a leer de la API de Xendit con la clave secreta de ese modo. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda después de pagar.
Test Webhook Verification Token: el token de verificación de webhook del modo de prueba de Xendit.
Live Webhook Verification Token: el token de verificación de webhook del modo real de Xendit.
Pago
Invoice Description: la descripción que aparece en la factura de Xendit. Puedes usar los marcadores {order_id}, {order_number} y {site_name}. El HTML se elimina y el texto se corta a 255 caracteres. Predeterminado: Order #{order_id}.
Order Status After Payment: el estado del pedido que se asigna cuando Xendit confirma el pago. El estado se asigna de inmediato, en un único cambio de estado.
Avanzado
Debug Log: Log API requests and webhooks escribe las peticiones, los webhooks y los cambios de estado en WooCommerce > Status > Logs, origen wcp_xendit_payment_gateway. Los errores y las advertencias se registran siempre, incluso cuando esto está desactivado. Las claves de API, los tokens y los datos de los clientes no se registran. Predeterminado: desactivado.
Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. Desactivar el plugin nunca borra nada. Los datos de los pedidos (IDs de factura en los pedidos) se conservan siempre. Predeterminado: desactivado.
Finalización de compra
El método de pago se muestra cuando la moneda de la tienda es IDR, PHP, VND, THB, MYR, USD o SGD. En la página Pay for order cuenta la moneda del pedido. El cliente elige el método de pago (por defecto Xendit) y realiza el pedido. El plugin crea una factura de Xendit por el total del pedido en la moneda del pedido y envía al cliente a la página de factura de Xendit. Los importes en IDR y VND se redondean a números enteros, porque Xendit no acepta decimales en ellos. El correo electrónico de facturación del cliente se envía a Xendit. En la página de la factura, el cliente paga con uno de los canales de pago activados en tu cuenta de Xendit para esta moneda, por ejemplo una cuenta virtual, un monedero electrónico, un código QR, un establecimiento minorista o una tarjeta.
Después de pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido se marca como pagado solo cuando Xendit lo confirma: mediante el webhook, o mediante una petición del servidor a la API de Xendit cuando el cliente llega a esa página. Hasta entonces, el pedido sigue en Pendiente de pago.
Si la factura falla o caduca, Xendit devuelve al cliente a la tienda. Un pedido realizado en la finalización de compra se cancela entonces de la forma estándar de WooCommerce, y su factura caduca. Un pedido pagado desde la página Pay for order (por ejemplo, un pedido que creaste para el cliente) vuelve a su página de pago con el mensaje The Xendit payment was not completed. You can try again or choose another payment method. y sigue pudiéndose pagar.
El cliente puede volver a pagar un pedido no pagado. Si el total del pedido, la moneda y el modo no han cambiado y la factura abierta sigue vigente, el cliente va a la misma factura. Si no, la factura anterior caduca primero y se crea una nueva, así que nunca hay dos facturas abiertas para un mismo pedido. Si la factura anterior ya estaba pagada, el pedido pasa a Completado en lugar de realizar un nuevo pago.
Si Xendit no puede iniciar el pago, el cliente ve un mensaje breve y puede elegir otro método de pago, por ejemplo Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., un mensaje de que la moneda no está aceptada para tu cuenta o de que el total del pedido está fuera de los límites de importe de Xendit. El motivo técnico se escribe en el registro. Un pedido con total cero no puede pagarse con Xendit.
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. En modo de prueba, el bloque de Finalizar compra muestra Test mode: no real money is charged. debajo del método de pago. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El pago siempre se realiza en la página de Xendit. El plugin no incluye reembolsos desde WooCommerce, tarjetas guardadas, suscripciones ni pagos recurrentes, campos de tarjeta o monedero electrónico en la página de finalización de compra, autorización y captura por separado, subcuentas de xenPlatform, caducidad de factura personalizada ni comisiones de pago.
Pedidos
Estados del pedido
Pending payment: la factura se creó y el cliente todavía no ha pagado, o Xendit todavía no ha confirmado el pago. La nota del pedido muestra el ID de la factura, el importe, la moneda y el modo.
Processing or Completed: el pago fue confirmado. El estado sigue el valor de Order Status After Payment. La nota del pedido muestra el ID de la factura, el importe pagado, el canal de pago y el modo. El ID de transacción es el ID de la factura de Xendit.
On hold: la factura pagada no coincidió con el total o la moneda del pedido, o se pagó menos que el total (por ejemplo, el pedido se editó después de crear la factura). La nota del pedido lo explica, también cuando el pedido ya estaba en espera. Revisa el pago en el Panel de control de Xendit y después tramita el pedido o reembolsa el pago.
Failed: la factura actual caducó sin pago. El cliente puede volver a pagar el pedido.
Cancelled: el cliente volvió desde una factura fallida o caducada, o el pedido lo canceló el propio administrador o el tiempo de espera de WooCommerce para pedidos sin pagar. La factura abierta caduca, así que ya no se puede pagar. Si Xendit no acepta esto, una nota te pide que hagas caducar la factura en el Panel de control de Xendit.
Si se paga una factura de un pedido que ya está pagado, cancelado o reembolsado, el pedido no cambia. Una nota te pide que reembolses el pago en el Panel de control de Xendit o que restaures el pedido manualmente.
Reembolsos
Los reembolsos no se envían a Xendit desde WooCommerce. Reembolsa el pago en el Panel de control de Xendit (la nota del pedido y el ID de transacción contienen el ID de la factura) y registra el reembolso en WooCommerce manualmente.
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 > Xendit. 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 solo dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Xendit no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, 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 recordatorio 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.
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
Xendit no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo activo tiene una clave secreta con el prefijo correcto (Test Secret Key con xnd_development_ en modo de prueba, Live Secret Key con xnd_production_ en modo real) y que la moneda de la tienda es IDR, PHP, VND, THB, MYR, USD o SGD. El aviso de los ajustes muestra una advertencia cuando falta la clave o es incorrecta.
El pago se realizó, pero el pedido sigue en Pendiente de pago: el webhook no funciona. En el Panel de control de Xendit del modo que usas (prueba o real), comprueba que la URL que aparece en los ajustes está configurada para Invoice paid y que el token de verificación de ese modo está guardado en el campo correspondiente. El Panel de control de Xendit muestra la respuesta de tu tienda para cada webhook. El pedido también se confirma cuando el cliente vuelve a la página de pedido recibido.
Respuesta del webhook «Webhook verification token is not configured»: ninguno de los dos tokens de verificación está configurado. Pega el token en los ajustes.
Respuesta del webhook «Unauthorized»: el token enviado por Xendit no coincide con ningún token de los ajustes. Vuelve a copiar el token del modo correcto.
Respuesta del webhook «Token does not match the mode of this invoice»: la factura se creó en el otro modo. Una notificación de prueba nunca confirma un pedido real, ni al revés. Configura el webhook y el token en el modo en el que se pagó el pedido.
Respuesta del webhook «Ignored: not an invoice of this store»: la factura no la creó esta tienda, por ejemplo otra integración de la misma cuenta de Xendit. El botón Test del Panel de control de Xendit también recibe esta respuesta, lo que confirma que la URL y el token funcionan.
Respuesta del webhook «Temporary error»: no se pudo contactar con la API de Xendit para comprobar la factura, falta la clave secreta del modo de la factura o otra petición estaba actualizando el pedido en ese mismo momento. Xendit reintenta el webhook. Comprueba que ambas claves secretas están configuradas si tienes pedidos de los dos modos.
Una clave no se guarda: el valor no empieza por el prefijo de su campo. Las claves de prueba empiezan por xnd_development_, las reales por xnd_production_.
El cliente ve «This payment method is temporarily unavailable»: Xendit rechazó la petición, por ejemplo porque la clave secreta es incorrecta o no tiene permiso de escritura para Money-in (facturas). Activa Debug Log si hace falta y revisa WooCommerce > Status > Logs, origen wcp_xendit_payment_gateway. Un mensaje sobre los datos de facturación significa que Xendit no aceptó los datos de la petición, por ejemplo el correo electrónico.
El cliente ve «A payment for this order was already received by Xendit and is being reviewed»: una factura anterior de este pedido se pagó, pero no coincidía con el pedido, así que el pedido está en espera. Revisa el pago en el Panel de control de Xendit.
El pedido queda en espera tras el pago: lee la nota del pedido. El importe o la moneda pagados eran distintos de los del pedido. Tramita el pedido o reembolsa el pago en el Panel de control de Xendit.
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 del plugin, los datos temporales y sus registros (archivos de registro, incluidos los rotados, entradas de registro en la base de datos y la carpeta de registros de la versión 1.0) se eliminan solo si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, IDs de factura e IDs de transacción.
Xendit es una marca comercial de su respectivo titular. Este plugin no está afiliado a Xendit ni cuenta con su respaldo.