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

HTTPS: los campos de la tarjeta están en la página de finalización de compra, así que esta debe servirse por HTTPS. Aun así, los datos de la tarjeta nunca llegan a tu servidor. Omise envía los webhooks solo a direcciones HTTPS, y la página de 3-D Secure del banco debe ser una dirección HTTPS.

Moneda: una de THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Para un carrito en cualquier otra moneda, el método de pago no se muestra en la finalización de compra.

Cuenta de Omise: necesitas la clave pública y la clave secreta de tu cuenta de Omise, para modo de prueba y para modo de producción, desde Settings > Keys en el panel de Omise, y un endpoint de webhook en Settings > Webhooks (ver Configuración).

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 carga, haz clic en Configure, o busca VibeFox Omise Payment más tarde en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).

4. Introduce tus claves de prueba y de producción de Omise y añade en el panel de Omise la URL del webhook que aparece en la página de ajustes (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Prueba un pago en modo de prueba con una tarjeta de prueba de Omise, como 4242 4242 4242 4242, y después desactiva Test mode.

Al instalar el módulo se crean tres estados de pedido: Omise payment authorized, Omise payment on hold y Awaiting Omise payment. El método de pago se ofrece en los países que están activos en el momento de la instalación. Si activas más países después, permite el módulo para ellos en Payment > Preferences, donde también puedes limitarlo por moneda y grupo de clientes.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Omise Payment > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, la página muestra Test mode is on — orders are charged with the test keys, no real money is moved. mientras el modo de prueba está activado, avisa si falta la clave pública o la secreta del modo actual, y avisa cuando Omise no acepta la moneda predeterminada de tu tienda. En estos casos, el método de pago no se muestra en la finalización de compra.

Omise

Enable/Disable: Enable card payments via Omise activa o desactiva el método de pago. Predeterminado: off.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Credit / Debit Card. Obligatorio.

Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Predeterminado: Pay securely with your credit or debit card via Omise.

Claves de API

Encontrarás tus claves en el panel de Omise, en Settings > Keys. Las claves de prueba empiezan por pkey_test_ y skey_test_, y las de producción por pkey_ y skey_. Al guardar, una clave con el prefijo incorrecto (por ejemplo, una clave de prueba en un campo de producción) no se guarda: se mantiene el valor anterior y se muestra un aviso.

Test mode: usa las claves de prueba, sin cargos reales. Cambia las dos claves a la vez. Las capturas, los reembolsos y las comprobaciones de estado de un pedido siempre usan las claves del modo en el que se pagó el pedido. Predeterminado: on.

Test public key: la clave pública del modo de prueba, pkey_test_...

Test secret key: la clave secreta del modo de prueba, skey_test_...

Live public key: la clave pública del modo de producción, pkey_...

Live secret key: la clave secreta del modo de producción, skey_...

Las claves secretas guardadas 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 cambiarla.

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

Pago y webhook

Webhook URL: la dirección del webhook de tu tienda. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_omise_payment/webhook. Cópiala exactamente como la muestran los ajustes y añádela en el panel de Omise, en Settings > Webhooks (solo HTTPS). El módulo gestiona estos eventos (también aparecen listados en esta sección):

Omise no firma los webhooks, así que el contenido del webhook nunca se da por válido: el cargo debe haber sido creado por esta tienda para ese carrito, y su estado se vuelve a leer de la API de Omise con la clave secreta del modo del pago. Sin el webhook, un pedido cuyo cliente cierra el navegador durante el 3-D Secure no se crea automáticamente, y las capturas hechas en el panel de Omise no se registran hasta que hagas clic en Sync payment status.

Payment action: qué ocurre con el importe de la tarjeta.

Per-charge webhook: envía la URL del webhook con cada cargo. Es útil cuando varias tiendas comparten una misma cuenta de Omise. Solo funciona si la tienda usa HTTPS; si no, se usa el webhook del panel. Predeterminado: off.

Avanzado

Debug log: escribe las peticiones a la API y los eventos de pago en logs/omise_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede leer desde la web. Las claves, los tokens y los datos de la tarjeta nunca se registran. Predeterminado: off. Mientras está desactivado no se escribe nada, tampoco los errores, así que actívalo cuando busques un problema.

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 los ajustes y el registro de depuración. Los cargos y reembolsos de Omise de los pedidos forman parte del historial de pagos y siempre se conservan. Predeterminado: off.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (de forma predeterminada Credit / Debit Card) y rellena el formulario de tarjeta: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) y Security code (CVV). En modo de prueba, el formulario muestra TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. Cuando el cliente realiza el pedido, Omise.js convierte la tarjeta en un token de un solo uso en el navegador, usando la dirección de facturación del carrito. Los campos de la tarjeta nunca se envían a tu tienda. Los campos que faltan o no son válidos se muestran debajo del formulario, por ejemplo Please enter a valid card number.

Tu tienda crea entonces el cargo con la clave secreta por el total del carrito, en la moneda del carrito. La descripción del cargo es el nombre de la tienda y el número de carrito, y el ID del carrito se guarda en los metadatos del cargo. En este punto todavía no existe ningún pedido. Si el banco exige 3-D Secure, el cliente es enviado a la página del banco y vuelve a tu tienda, y el resultado se vuelve a leer de la API de Omise.

El pedido se marca como pagado solo cuando Omise lo confirma: el cargo debe estar capturado y su importe y su moneda deben coincidir con el carrito. El cliente ve la página estándar de confirmación del pedido con Your card payment has been received. Con Authorize only, la página dice Your card payment has been authorized. The amount will be charged when your order is processed. Si Omise sigue informando el pago como pendiente, el pedido se crea en Awaiting Omise payment y la página dice Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Si el pago no se puede confirmar justo después del 3-D Secure, aparece una página de Payment confirmation con We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. y un botón Check again.

Si la tarjeta es rechazada, no se crea ningún pedido. El cliente permanece en la finalización de compra con Payment failed: y un motivo, por ejemplo fondos insuficientes, un código de seguridad no válido o un rechazo del emisor de la tarjeta, y puede volver a intentarlo con el mismo carrito. Si el 3-D Secure falla, el cliente vuelve a la finalización de compra con el motivo; si el cargo caducó o se anuló mientras tanto, el mensaje es The payment was not completed. Please try again.

Un reintento nunca cobra dos veces: si el cargo anterior del carrito ya está pagado o autorizado, el pedido se crea sin un nuevo cargo. Un intento de 3-D Secure sin terminar caduca antes de hacer un nuevo cargo. Si un segundo cargo sigue pagado para un carrito que ya tiene pedido (por ejemplo, en otra pestaña del navegador), el pedido no se modifica y una nota te pide que lo reembolses o anules en el panel de Omise.

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

El módulo solo acepta tarjetas. No incluye otros métodos de pago de Omise (PromptPay, TrueMoney, banca móvil, pagos a plazos), ni tarjetas guardadas o clientes de Omise, ni suscripciones, ni captura parcial.

Pedidos y reembolsos

Estados de pedido

No order yet: el cliente está en el 3-D Secure, o la tarjeta fue rechazada. Solo existe el carrito.

Payment accepted: el pago fue confirmado. El pago se registra con el ID del cargo de Omise (chrg_...) como ID de transacción, y una nota muestra el importe, el cargo y cómo se confirmó (finalización de compra, retorno de 3-D Secure, webhook, reintento de pago, captura manual o sincronización manual). Las notas son mensajes privados del pedido, visibles solo en el back office.

Omise payment authorized: la tarjeta fue autorizada con Authorize only. Usa Capture payment o Void authorization.

Awaiting Omise payment: Omise todavía no ha confirmado el pago. El webhook o Sync payment status actualizan el pedido.

Omise payment on hold: el importe o la moneda del cargo no coinciden con el pedido, por ejemplo porque el carrito se cambió durante el 3-D Secure. La nota muestra ambos valores. Un pago capturado se sigue registrando en el pedido. Revisa el pedido y tramítalo o reembolsa el pago.

Payment error: un pago pendiente falló después. Un pedido pagado nunca se degrada por un evento fallido posterior.

Canceled: el cargo caducó o la autorización fue anulada.

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

Si llega un cargo pagado o autorizado para un pedido que ya está Cancelado o Reembolsado, el pedido no se reabre. Una nota te pide que revises el panel de Omise y reembolses o reabras el pedido manualmente.

Bloque de pago de Omise

La página del pedido muestra un bloque Omise payment con el ID del cargo, la acción de pago, el estado del cargo, la marca y los últimos dígitos de la tarjeta, los importes cobrado, del pedido y reembolsado, una insignia Test mode para los pagos de prueba y el historial de reembolsos. Los botones del bloque requieren el permiso para editar pedidos y la clave secreta del modo en el que se hizo el pago. No hace falta acceso a las páginas de módulos. El resultado de cada acción se muestra en la parte superior del bloque.

Capture payment: captura el importe autorizado completo y pone el pedido en Payment accepted. Se muestra solo en pedidos autorizados.

Void authorization: anula la autorización; no se captura dinero y el pedido pasa a Canceled. Se muestra solo en pedidos autorizados.

Sync payment status: lee el cargo desde Omise y actualiza el pedido. La nota también muestra el total reembolsado en Omise.

Reembolsos

En el bloque Omise payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Omise. Confirma la pregunta Refund this amount through Omise? This cannot be undone. Se admiten reembolsos totales y parciales. Los reembolsos se hacen en el importe y la moneda que cobró Omise, así que después de un desajuste de importe o de moneda puedes reembolsar hasta lo que el cliente pagó realmente, y no el total del pedido. El reembolso se envía en el modo en el que se hizo el pago, así que la clave secreta de ese modo debe estar configurada. El motivo se guarda con el reembolso en Omise. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID del reembolso de Omise. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Para una autorización que aún no se ha capturado solo es posible un reembolso total, y anula la autorización. Si Omise rechaza el reembolso, el bloque muestra Refund failed. con el mensaje de Omise, y no se registra ningún reembolso.

El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Omise. Los reembolsos hechos en el panel de Omise no se registran en PrestaShop; Sync payment status muestra el total reembolsado.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Omise Payment es el primer bloque de Modules > Module Manager > VibeFox Omise Payment > Configure, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-omise y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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 Clave no encontrada, Esta clave pertenece a otro producto, Se ha alcanzado el límite de dominios o La licencia caducó el seguido de una fecha. Después de que cambie la dirección de la tienda, o de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no está disponible, 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, Omise no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve Este método de pago no está disponible. Elige otro. El storefront 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. 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 siguen funcionando.

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 hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Omise does not appear at checkout: comprueba que la licencia esté activa, que Enable/Disable esté activado, que estén introducidas las dos claves del modo actual (claves de prueba en modo de prueba, claves de producción en caso contrario) y que la moneda del carrito sea una de las monedas admitidas. La página de ajustes muestra un aviso cuando faltan claves. 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 or the order stays Awaiting Omise payment: el webhook no funciona. En el panel de Omise comprueba que la URL del webhook sea exactamente la que aparece en Webhook URL y que use HTTPS. En un pedido existente haz clic en Sync payment status. Activa Debug log para ver las respuestas del webhook.

Webhook answers Charge ID does not match order or Order not found: el cargo del evento no fue creado por esta tienda para ese carrito. No se cambia nada.

Webhook answers Order is being processed, retry later or Failed to verify charge: el carrito fue bloqueado por otra petición en el mismo momento, no se pudo contactar con la API de Omise, o falta la clave secreta del modo del pago. Omise reintenta el webhook.

Webhook answers The order could not be created, retry later: no se pudo crear el pedido, por ejemplo porque el módulo está desactivado. 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 Omise.

Warning on save: key must start with ... or must be a live key: se pegó una clave en el campo equivocado y no se guardó. Las claves de prueba empiezan por pkey_test_ / skey_test_, y las de producción por pkey_ / skey_.

The customer sees Card payments are temporarily unavailable: las claves son incorrectas, o el token de la tarjeta pertenece al otro modo (un token de prueba en producción o al revés). Comprueba las claves y Test mode.

The customer sees We could not reach the payment provider: no llegó una respuesta válida de Omise al crear el cargo. Es posible que el cargo sí se haya creado; revisa el panel de Omise antes de que el cliente pague de nuevo.

The customer sees This order is already being paid: la finalización de compra se envió dos veces al mismo tiempo. El cliente espera un momento y revisa el correo electrónico antes de volver a intentarlo.

Order is Omise payment on hold after payment: lee la nota del pedido (ver Estados de pedido) y después tramita el pedido o reembolsa el pago.

Refund fails with a message about the mode: el pago se hizo en modo de prueba o de producción, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo.

Partial refund of an authorized order fails: el pago solo está autorizado. Captúralo primero, o reembolsa el importe total para anularlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Omise Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes y el registro de depuración. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los cargos y reembolsos de Omise y los estados de pedido Omise payment authorized, Omise payment on hold y Awaiting Omise payment siempre se conservan, de modo que los pedidos pagados antes se pueden seguir reembolsando tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.

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