VibeFox Xendit 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.

Moneda de la tienda: IDR, PHP, VND, THB, MYR, USD o SGD. Para otras monedas del carrito 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, 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 se necesita 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 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 VibeFox Xendit Payment Gateway más tarde en la lista de módulos y haz clic en Configure.

3. Introduce 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. 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).

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

Al instalarse, el módulo crea el estado de pedido Xendit payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, un cuadro 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 cuadro avisa si 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 si el token de verificación del webhook del modo activo está vacío (las notificaciones de Xendit se rechazan, así que los pedidos solo se crean cuando el cliente vuelve a tu tienda).

Xendit

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. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Xendit. Obligatorio.

Description: el texto que se muestra 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: crea las facturas con la clave secreta de prueba, así que no se cobra dinero real. Predeterminado: activado. Desactívalo para aceptar pagos reales con la clave secreta real. Mientras esté activado, los clientes ven Test mode: no real money is charged. debajo del método de pago.

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

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.

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 Webhook URL de esta sección para Invoices > Invoice paid, en modo de prueba y en modo real. Opcionalmente, configúrala también para Invoice expired. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_xendit_payment_gateway/webhook, posiblemente con un código de idioma como /en/. Cópiala exactamente como la muestran 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 procede 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, el pedido solo se crea cuando el cliente vuelve a la tienda tras 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 real de Xendit.

Clear saved secrets: marca una clave o un token y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Pago

Invoice Description: la descripción que aparece en la factura de Xendit. Puedes usar los marcadores {order_id}, {order_number} y {site_name}. Como el pedido se crea después del pago, {order_id} y {order_number} son el número del carrito. 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.

Avanzado

Debug Log: escribe las peticiones a la API y los webhooks en logs/xendit_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, incluso con esta opción desactivada. Las claves de API, los tokens y los datos de los clientes no se registran. Predeterminado: desactivado.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes del módulo y el registro. Los datos de los pedidos (los ID de factura de los pedidos) y el estado de pedido Xendit payment on hold siempre se conservan. Predeterminado: desactivado.

Finalización de compra

El método de pago se muestra cuando la moneda del carrito es IDR, PHP, VND, THB, MYR, USD o SGD. El cliente lo elige en el paso de pago (por defecto Xendit) y confirma. El módulo crea una factura de Xendit por el total del carrito en la moneda del carrito 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 admite decimales para estas monedas. 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 establecimiento minorista o una tarjeta. En este momento todavía no existe ningún pedido.

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 petición del servidor a la API de Xendit cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. Si Xendit aún no ha confirmado el pago, aparece una página de Payment confirmation con el mensaje Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. y los botones Check again y Back to checkout. El webhook crea el pedido en cuanto llega.

Si la factura falla o caduca, Xendit devuelve al cliente. El módulo comprueba primero la factura (puede que se haya pagado en otra pestaña) y después la hace caducar, para 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.

Un cliente puede volver a pagar el mismo carrito. Si el total del carrito, la moneda y el modo no han cambiado y la factura abierta sigue siendo válida durante al menos cinco minutos más, el cliente va a la misma factura. Si no, la factura anterior se hace caducar primero y se crea una nueva, de modo que nunca hay dos facturas abiertas para un mismo carrito. Si la factura anterior ya estaba pagada, se crea el pedido en lugar de un nuevo pago.

Si Xendit no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, 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 carrito con total cero no se puede pagar con Xendit.

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

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

Pedidos

Estados del pedido

Aún no hay pedido: el cliente fue enviado a Xendit y no ha pagado, o Xendit todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted or Delivered: el pago se confirmó. El estado sigue a Order Status After Payment. El pago se registra con el ID de factura de Xendit como ID de transacción, y una nota muestra el ID de factura, el importe pagado, el canal de pago y el modo.

Xendit payment on hold: la factura pagada no coincidía con el total o la moneda del carrito, o se pagó menos del total (por ejemplo, el carrito se modificó después de crear la factura). La nota lo explica. Comprueba el pago en el Panel de control de Xendit y después completa el pedido o reembolsa el pago. Si más adelante se paga otra factura del mismo carrito con el importe correcto, el pago se registra y el pedido pasa al estado de pagado.

Si se paga una factura de un pedido que ya está cancelado o reembolsado, el estado del pedido no cambia. Una nota te pide que reembolses el pago en el Panel de control de Xendit o que restaures el pedido manualmente. Si se paga una segunda factura de un pedido que ya está pagado, el pedido no cambia y una nota te pide que reembolses el pago duplicado en el Panel de control de Xendit.

Bloque Xendit payment

La página del pedido muestra un bloque Xendit payment con el ID de factura, el modo (con una insignia Test mode para los pagos de prueba), el estado del pago, una lista de todas las facturas del pedido (fecha, factura, ID externo, importe e importe pagado, estado, canal de pago) y las Payment notes del pedido.

Reembolsos

Los reembolsos no se envían a Xendit desde la tienda. Reembolsa el pago en el Panel de control de Xendit (busca el ID de factura que aparece en el bloque Xendit payment) y registra el reembolso en el pedido manualmente. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Xendit.

Clave de licencia

El módulo 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 Modules > Module Manager > VibeFox Xendit Payment 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-xendit 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 inglés y 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. Tras cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un solo 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, 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. La tienda de PrestaShop 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. Un recordatorio aparece en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan 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 hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre 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 real) y que la moneda del carrito es IDR, PHP, VND, THB, MYR, USD o SGD. La página de ajustes muestra una advertencia cuando falta la clave o es incorrecta. 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.

El pago se realizó, pero no se creó ningún pedido: 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 Webhook URL 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 crea cuando el cliente vuelve a la tienda tras 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 carrito.

Webhook answers Ignored: not an invoice of this store: la factura no la creó esta tienda, por ejemplo otra integración en 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. Ignored: unknown order e Ignored: unknown invoice significan que esta tienda no conoce el carrito o la factura.

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, otra petición estaba actualizando el carrito en ese mismo momento o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Xendit reintenta el webhook. Comprueba que ambas claves secretas están configuradas si se iniciaron pagos en ambos modos, y activa Debug Log para ver el motivo.

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

A key is not saved: el valor no empieza por el prefijo de su campo. Las claves de prueba empiezan por xnd_development_, y las reales por xnd_production_.

The customer sees 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). Revisa el campo Log de la página del módulo. 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.

The customer sees A payment for this order was already received by Xendit and is being reviewed: se pagó una factura anterior de este carrito, pero el pedido todavía no se pudo confirmar. Comprueba el pago en el Panel de control de Xendit y en el registro.

The customer sees We could not match this payment to an order: el enlace de retorno de Xendit no pertenece a un carrito de esta tienda, o no se pudo relacionar ninguna factura del carrito. Comprueba el pago en el Panel de control de Xendit y en el registro.

Order is Xendit payment on hold after payment: lee las notas del bloque Xendit payment. El importe o la moneda pagados eran distintos a los del carrito. Completa el pedido o reembolsa el pago en el Panel de control de Xendit.

Para los desarrolladores, el módulo ofrece los hooks actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies y actionWcpXenditCurrencyDecimals para modificar la petición de factura, la lista de monedas y el número de decimales por moneda.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Xendit Payment 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, se conservan todos los ajustes para una futura reinstalación. Los datos de las facturas de Xendit de los pedidos y el estado de pedido Xendit payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Xendit es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Xendit ni cuenta con su respaldo.