VibeFox Xendit for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posterior (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Moneda de la tienda: IDR, PHP, VND, THB, MYR, USD o SGD. Para otras monedas de finalización de compra 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 de API secreta con permiso de escritura para Money-in (facturas) para el modo de prueba, y otra para el modo de producción, además del 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 por Xendit.

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

Instalación

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_xendit_payment_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_xendit_payment_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_xendit_payment_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Xendit Payment Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página, y haz clic en Activate (véase Clave de licencia).

4. Pega tus claves secretas de Xendit, configura la URL del webhook en el Xendit Dashboard y pega los tokens de verificación (véase Configuración).

5. Activa Enable/Disable y haz clic en Save. Haz un pedido de prueba en el modo de prueba y luego desactiva Test Mode para aceptar pagos reales.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_xendit_payment_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas de la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Xendit Payment Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia, las claves de Xendit y el webhook como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo la URL del webhook es diferente (véase Webhooks).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Encima de los ajustes, un recuadro muestra el modo activo: TEST MODE (las facturas se crean con la clave secreta de prueba; no se cobra dinero real) o LIVE MODE (las facturas se crean con la clave secreta de producción y se cobra a los clientes). La página avisa 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 del webhook del modo activo está vacío (las notificaciones de Xendit se rechazan y los pedidos solo se actualizan cuando el cliente vuelve a tu tienda).

Al guardar, Title no debe estar vacío (como máximo 128 caracteres), Sort Order debe ser un número entero (se permiten números negativos), Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido deben existir. Si no, no se guarda nada y la página indica el campo.

Xendit

Enable/Disable: Enable Xendit activa o desactiva el método de pago. Por defecto: off.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Xendit. Obligatorio, hasta 128 caracteres.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmación. Por defecto: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Sort Order: la posición de Xendit entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece Xendit solo para direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar para que se ofrezca Xendit. Déjalo vacío para ofrecer Xendit con cualquier total.

Claves de API

Crea una clave de API secreta con permiso de escritura para Money-in (facturas) en Xendit Dashboard > Settings > Developers > API keys (la sección tiene un enlace allí), una vez en modo de prueba y otra en modo de producción. 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: crea facturas con la clave secreta de prueba, así que no se cobra dinero real. Por defecto: on. Desactívalo para aceptar pagos reales con la clave secreta de producción. Mientras esté activado, los clientes ven Test mode: no real money is charged. en el paso Confirm Order.

Test Secret Key: la clave secreta del modo de prueba de Xendit. Empieza por xnd_development_.

Live Secret Key: la clave secreta del modo de producción de Xendit. Empieza por xnd_production_.

Las claves y los tokens guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Para borrar un valor guardado, marca Clear the saved value debajo del campo y haz clic en Save.

Webhooks

El webhook avisa a tu tienda de que una factura ha sido pagada. En Xendit Dashboard > Settings > Developers > Webhooks (la sección tiene un enlace allí), configura la URL que aparece en Webhook URL para Invoices > Invoice paid, tanto en modo de prueba como en modo de producción. Opcionalmente, configúrala también para Invoice expired. En OpenCart 3 la URL tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_xendit_payment_gateway/webhook, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_xendit_payment_gateway/payment/wcp_xendit_payment_gateway.webhook. Se construye a partir de la dirección pública de tu instalación de OpenCart. Cópiala exactamente como la muestran los ajustes. Debe ser accesible desde internet.

Después, copia el Webhook verification token de cada modo desde el Xendit Dashboard 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 desde 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 del webhook del modo de prueba de Xendit.

Live Webhook Verification Token: el token de verificación del webhook del modo de producción de Xendit.

Pago

Invoice Description: la descripción que aparece en la factura de Xendit. Puedes usar los marcadores {order_id} y {order_number} (ambos son el número de pedido de OpenCart) y {site_name} (el nombre de la tienda). El HTML se elimina y el texto se corta a 255 caracteres. Por defecto: Order #{order_id}.

Order Status After Payment: qué estado asigna un pago confirmado, en un solo cambio de estado.

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido ausente). El pedido recibe un estado solo después de que Xendit haya confirmado el pago a través de la API. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Paid Order Status: el estado después de un pago confirmado con Processing. Por defecto: Processing.

Complete Order Status: el estado después de un pago confirmado con Completed. Por defecto: Complete.

On Hold (Review) Status: una factura se pagó con otro importe o moneda distinto del pedido (el carrito se cambió después de crear la factura, o un pago parcial). Una nota explica el motivo. Por defecto: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Avanzado

Debug Log: escribe las solicitudes a la API y los webhooks en xendit_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web, y al llegar a 5 MB se mueve a xendit_p_debug.old.log.php. Los errores y las advertencias siempre se registran, incluso cuando esta opción está desactivada. Las claves, los tokens y los datos de los clientes no se registran. Por defecto: off.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los datos de los pedidos (los ID de factura de los pedidos) siempre se conservan. Por defecto: off.

Importar / Exportar

Export: Download JSON guarda los ajustes como un archivo JSON. Las claves secretas y los tokens no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves secretas y los tokens guardados se conservan.

Finalización de compra

El método de pago se muestra cuando la moneda de la finalización de compra es IDR, PHP, VND, THB, MYR, USD o SGD. El cliente lo elige en el paso Payment Method (por defecto, Xendit). En el paso Confirm Order, el cliente ve tu descripción. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión 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 de IDR y VND se redondean a números enteros, porque Xendit no acepta decimales para ellos. El correo electrónico 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 punto de venta minorista o una tarjeta. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque de método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Xendit lo confirma: mediante el webhook o mediante una solicitud del servidor a la API de Xendit cuando el cliente regresa. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart. Si Xendit todavía no ha confirmado el pago, una página de Payment confirmation muestra Your payment has not been confirmed by Xendit yet. Your order will be confirmed as soon as Xendit confirms it — please do not pay again. con los botones Check again y Back to checkout. El webhook asigna el estado del pedido en cuanto llega.

Si la factura falla o caduca, Xendit devuelve al cliente. La extensión primero comprueba la factura (puede que se haya pagado en otra pestaña) y, después, la hace caducar, de modo que ya no se pueda pagar. El cliente vuelve a la finalización de compra con The Xendit payment was not completed. You can try again or choose another payment method. El carrito se conserva.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order. OpenCart 4 mantiene un pedido para la finalización de compra y lo actualiza, así que tras una factura fallida o caducada el siguiente Confirm Order crea una nueva factura para el mismo pedido. Si otro pedido del mismo carrito ya está pagado, el cliente va directamente a la página de éxito y no se le cobra dos veces. Si el total del pedido, la moneda y el modo no han cambiado y la factura abierta de este pedido sigue siendo válida durante al menos otros cinco minutos, el cliente es enviado a la misma factura. Si no, la factura anterior se hace caducar primero y se crea una nueva, de modo que nunca haya dos facturas abiertas para un mismo carrito. Si la factura anterior ya estaba pagada, se confirma ese pago en lugar de crear uno nuevo.

En OpenCart 4, si el pedido de la finalización de compra fue cerrado por la tienda entretanto (por ejemplo, cancelado o reembolsado), o ya está pagado pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el cliente vuelve a la finalización de compra con Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order., y el siguiente Confirm Order paga un pedido nuevo. En OpenCart 4 este mensaje, el mensaje sobre el pago no completado y We could not match this payment to an order. If you were charged, please contact us. se muestran encima de la página de finalización de compra.

Si Xendit no puede iniciar el pago, el cliente permanece en el paso Confirm Order con un breve mensaje encima del botón, 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 se puede pagar con Xendit.

El webhook y el regreso del cliente también funcionan mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio para ellas.

El pago siempre se realiza en la página de Xendit. La extensión no tiene reembolsos desde el panel de administración, ni tarjetas guardadas, suscripciones ni pagos recurrentes, ni campos de tarjeta o monedero electrónico en la página de finalización de compra, ni autorización y captura por separado, ni subcuentas de xenPlatform.

Pedidos

Estados del pedido

No status (missing order): el cliente fue enviado a Xendit y no ha pagado, o Xendit todavía no ha confirmado el pago. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Paid Order Status o Complete Order Status (por defecto Processing o Complete): el pago fue confirmado. El estado sigue a Order Status After Payment. Una nota muestra el ID de la factura, el importe pagado, el canal de pago y el modo.

On Hold (Review) Status (por defecto Pending): la factura pagada no coincidía con el total o la moneda del pedido, o se pagó menos del total (por ejemplo, el carrito se cambió después de crear la factura). La nota lo explica. Comprueba el pago en el Xendit Dashboard y luego prepara el pedido o reembolsa el pago. Si después se paga otra factura del mismo pedido con el importe correcto, el pedido pasa al estado de pagado.

Si se paga una factura de un pedido que tiene otro estado, por ejemplo cancelado o reembolsado, el estado del pedido no cambia. Una nota pide reembolsar el pago en el Xendit Dashboard o restaurar el pedido manualmente. Si se paga una segunda factura de un pedido que ya está pagado, o de otro pedido de un carrito que ya está pagado, el pedido no cambia y una nota en el pedido pagado pide reembolsar el pago duplicado en el Xendit Dashboard.

Las notas son entradas del History del pedido que el cliente no ve. Empiezan con la palabra Xendit.

VibeFox Xendit Payment Gateway tab

En Sales > Orders abre un pedido pagado con Xendit. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Xendit Payment Gateway muestra la Xendit invoice, el Mode (con la etiqueta Test para los pagos de prueba), el Status del pago, la tabla Invoices of this order and its cart (fecha, pedido, ID de factura, ID externo, modo, importe, importe pagado, estado y canal de pago) y las Payment notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos no se envían a Xendit desde la tienda. Reembolsa el pago en el Xendit Dashboard (busca el ID de la factura que aparece en la pestaña) y cambia después el estado del pedido en OpenCart. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Xendit.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Xendit Payment Gateway es el primer bloque de la página Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit, encima de los ajustes. Introduce 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 quitar la clave de esta tienda. Debajo están la línea Product: opencart-payment-xendit y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen inglés y ruso).

Si la clave no es aceptada, 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, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: la dirección de la tienda de la configuración de OpenCart. 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, Xendit 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. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método de pago se oculta para todos. Tras abrir una vez la página Edit, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del panel de administración o la página Edit: 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 la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

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 de producción) y que la moneda de la finalización de compra es IDR, PHP, VND, THB, MYR, USD o SGD. La página de ajustes muestra un aviso cuando falta la clave o es incorrecta. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total configurado.

El pago se realizó, pero el pedido sigue sin estado: el webhook no funciona. En el Xendit Dashboard del modo que uses (prueba o producción), comprueba que la URL que aparece en Webhook URL está configurada para Invoice paid y que el token de verificación de ese modo está guardado en el campo correspondiente. El Xendit Dashboard muestra la respuesta de tu tienda para cada webhook. El pedido también recibe su estado cuando el cliente vuelve a la tienda después de pagar.

Webhook answers Webhook verification token is not configured: no hay ningún token de verificación configurado. Pega el token en los ajustes.

Webhook answers Unauthorized: el token que envía Xendit no coincide con ningún token de los ajustes. Vuelve a copiar el token del modo correcto.

Webhook answers 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 pago real, y viceversa. Configura el webhook y el token en el modo en el que se pagó el pedido.

Webhook answers 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 Xendit Dashboard también recibe esta respuesta, lo que confirma que la URL y el token funcionan. Ignored: unknown order e Ignored: unknown invoice significan que el pedido o la factura no los conoce esta tienda.

Webhook answers 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 el carrito se estaba actualizando en otra solicitud al mismo tiempo. Xendit reintenta el webhook. Comprueba que ambas claves secretas están configuradas si se iniciaron pagos en los dos modos, y activa Debug Log para ver el motivo.

La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta solicitudes de Xendit.

Una clave no se guarda: el valor no empieza por el prefijo de su campo. Las claves de prueba empiezan por xnd_development_, las de producción por xnd_production_.

El cliente ve This payment method is temporarily unavailable: Xendit rechazó la solicitud, por ejemplo porque la clave secreta es incorrecta o no tiene permiso de escritura para Money-in (facturas). Revisa el campo Log en la página de la extensión. Un mensaje sobre los datos de facturación significa que Xendit no aceptó los datos de la solicitud, 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 carrito se pagó, pero el pedido todavía no se pudo confirmar. Comprueba el pago en el Xendit Dashboard y en el registro.

El cliente ve We could not match this payment to an order: el enlace de retorno de Xendit no pertenece a un pedido de esta tienda, o la factura no se pudo relacionar con él. Comprueba el pago en el Xendit Dashboard y en el registro.

El pedido está en el estado de revisión después del pago: lee las notas de la pestaña VibeFox Xendit Payment Gateway. El importe o la moneda pagados eran distintos a los del pedido. Prepara el pedido o reembolsa el pago en el Xendit Dashboard.

Para desarrolladores: la extensión dispara los eventos de OpenCart xendit_p_invoice_request, xendit_p_supported_currencies y xendit_p_currency_decimals para modificar la solicitud de factura, la lista de monedas y el número de decimales por moneda.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Xendit Payment Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Payment, que vuelven a sus valores por defecto al reinstalar. En OpenCart 4 también se eliminan el evento de la extensión y su acción de inicio, que deja pasar en modo de mantenimiento el webhook y el regreso del cliente. Si Delete Data on Uninstall está activado, se eliminan el resto de ajustes de la pasarela (título, descripción, modo de prueba, claves, tokens, descripción de la factura, estado del pedido tras el pago, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los datos de las facturas de Xendit de los pedidos siempre se conservan. Los pedidos existentes mantienen sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox Xendit Payment Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

Xendit es una marca comercial de su respectivo propietario. Esta extensión no está afiliada a Xendit ni cuenta con su respaldo.