VibeFox Omise for WooCommerce — Ayuda
Requisitos
WordPress: 6.2 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activa sin él; si WooCommerce se desactiva más adelante, la pasarela no se carga y se muestra un aviso de administración.
PHP: 8.0 o posterior.
HTTPS: los campos de la tarjeta están en tu página de finalización de compra, así que esta debe servirse por HTTPS y mantenerse libre de scripts no fiables. Los datos de la tarjeta, de todos modos, nunca llegan a tu servidor. Omise envía los webhooks solo a direcciones HTTPS.
Moneda de la tienda: una de THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Para otras monedas, el método de pago se oculta en la finalización de compra.
Cuenta de Omise: necesitas la clave pública y la clave secreta de tu cuenta de Omise, tanto para el modo de prueba como para el de producción, que encontrarás en Settings > Keys del panel de Omise, y un endpoint de webhook en Settings > Webhooks (consulta Configuración).
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_omise_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > Omise > 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. Introduce tus claves de prueba y de producción de Omise y añade en el panel de Omise la URL del webhook que muestra la página de configuración (consulta Configuración).
6. Activa Enable/Disable. Prueba un pago en modo de prueba con una tarjeta de prueba de Omise, como 4242 4242 4242 4242, y después desmarca Test mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Omise. 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, y te avisa si falta la clave pública o la secreta del modo actual, o si Omise no admite la moneda de la tienda. En ambos casos el método de pago se oculta en la finalización de compra. En la lista de métodos de pago, Omise aparece como pendiente de configuración hasta que se introduzcan las dos claves del modo actual.
General
Enable/Disable: Enable card payments via Omise 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: Credit / Debit Card.
Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Por defecto: Pay securely with your credit or debit card via Omise.
Claves de API
Encuentra 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) se rechaza con un error y se conserva el valor anterior.
Test mode: Use the test keys (no real charges). Cambia ambas claves. Los reembolsos, las capturas y las comprobaciones de estado de un pedido siempre usan las claves del modo en el que se pagó el pedido. Por defecto: activado.
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_...
Pago y webhook
La sección muestra la URL del webhook de tu tienda. Tiene este aspecto: https://your-site/wp-json/omise-payment/v1/webhook. Cópiala exactamente como la muestran los ajustes y añádela en el panel de Omise, en Settings > Webhooks (solo HTTPS). El plugin gestiona estos eventos:
El contenido del webhook nunca se considera fiable: el cargo debe ser el guardado en el pedido, y su estado se vuelve a leer de la API de Omise con las claves del modo en el que se pagó el pedido. Sin el webhook, un pedido cuyo cliente cierra el navegador durante el 3-D Secure permanece En espera hasta que ejecutes Omise: Sync payment status, y las capturas hechas en el panel de Omise no se detectan automáticamente.
Payment action: qué ocurre con el importe de la tarjeta.
Per-charge webhook: Send the webhook URL with every charge. Resulta útil cuando varias tiendas comparten una cuenta de Omise. Solo funciona si el sitio usa HTTPS; en caso contrario se usa el webhook del panel. Por defecto: desactivado.
Avanzado
Debug log: Log API requests and payment events guarda los eventos en WooCommerce > Status > Logs, origen wcp_omise_payment. Las claves, los tokens y los datos de la tarjeta nunca se registran. Por defecto: desactivado.
Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto 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. Al realizar el pedido, Omise.js convierte la tarjeta en un token de un solo uso en el navegador. Los campos de la tarjeta nunca se envían a tu servidor.
Tu tienda crea el cargo con la clave secreta por el total del pedido en la moneda del pedido. La descripción del cargo es el nombre de la tienda y el número de pedido, y el ID del pedido se guarda en los metadatos del cargo. Si el banco exige 3-D Secure, el cliente es redirigido al banco y de vuelta a tu tienda. El resultado siempre se vuelve a leer de la API de Omise.
El pedido se marca como pagado solo después de que Omise lo confirme: el cargo debe estar capturado y su importe y su moneda deben coincidir con el pedido. Con Authorize only, el pedido pasa a En espera tras una autorización correcta. El cliente ve la página de pedido recibido.
Si la tarjeta es rechazada, 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. Tras un 3-D Secure fallido, el cliente es llevado a la página Pay for order. Si el pago no se puede confirmar justo después del 3-D Secure, el cliente ve We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.
Un reintento nunca cobra dos veces: si el cargo anterior del pedido ya está pagado o autorizado, el pedido se completa sin un nuevo cargo. Un intento de 3-D Secure no terminado caduca antes de crear un nuevo cargo.
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).
El plugin solo acepta tarjetas. No admite otros métodos de pago de Omise (PromptPay, TrueMoney, banca móvil, pagos a plazos, Konbini, PayNow), tarjetas guardadas ni clientes de Omise, suscripciones ni captura parcial.
Pedidos y reembolsos
Estados del pedido
Pendiente de pago: el cliente está en el 3-D Secure o todavía no ha pagado.
Procesando: el pago fue confirmado. Los pedidos con solo productos virtuales descargables pasan a Completado, como es habitual en WooCommerce. La nota del pedido muestra el importe, el ID del cargo y cómo se confirmó (finalización de compra, retorno del 3-D Secure, webhook, captura manual o sincronización manual). El ID de transacción es el ID de cargo de Omise (chrg_...).
En espera, pendiente de captura: la tarjeta se autorizó con Authorize only. Usa Omise: Capture payment u Omise: Void authorization.
En espera, pendiente: Omise todavía no ha confirmado el pago, por ejemplo porque el cliente cerró el navegador durante el 3-D Secure. El webhook u Omise: Sync payment status actualizan el pedido.
En espera, discrepancia: el importe o la moneda del cargo no coinciden con el pedido. La nota muestra ambos valores. Revisa el pedido y complétalo o reembolsa el pago.
Fallido: el pago fue rechazado. Un pedido pagado nunca pasa a un estado inferior por un evento posterior de fallo.
Cancelado: el cargo caducó o la autorización fue anulada.
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 que reembolses o reabras el pedido manualmente.
Acciones del pedido
Omise: Capture payment: captura el importe autorizado completo. Solo se muestra en los pedidos autorizados.
Omise: Void authorization: anula la autorización; no se captura dinero y el pedido se cancela. Solo se muestra en los pedidos autorizados.
Omise: Sync payment status: lee el cargo en Omise y actualiza el pedido. La nota también muestra el total reembolsado en Omise.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Omise. Se admiten reembolsos totales y parciales. El reembolso se envía en el modo en el que se realizó el pago, por lo que la clave secreta de ese modo debe estar configurada. Un reembolso correcto se añade a las notas del pedido con el ID de reembolso de Omise. En 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, WooCommerce muestra Refund failed. con el mensaje de Omise y no se registra ningún reembolso.
Los reembolsos hechos en el panel de Omise no se importan como reembolsos de WooCommerce. Omise: Sync payment status muestra el total reembolsado; crea reembolsos manuales equivalentes en WooCommerce si hacen falta.
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 > Omise. 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 desde tu cuenta de vibefox.net.
Sin una clave activa, Omise 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 que hayan 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. 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, y las capturas y los reembolsos funcionan.
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
Omise no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que están introducidas las dos claves del modo actual (las de prueba en modo de prueba, y las de producción en el resto de casos) y que la moneda es compatible. En la página Pay for order cuenta la moneda del pedido. La página de ajustes muestra un aviso cuando las claves o la moneda son incorrectas.
El pago se realizó, pero el pedido sigue en Pendiente de pago o En espera: el webhook no funciona. En el panel de Omise comprueba que la URL del webhook es exactamente la que muestran los ajustes y que usa HTTPS. Después ejecuta Omise: Sync payment status en el pedido. Activa el Debug log para ver las respuestas del webhook.
El webhook responde Earlier charge of the order, order not changed: el evento corresponde a un intento anterior del pedido que fue sustituido por un reintento. No se modifica nada en el pedido. Si ese cargo anterior sigue pagado o autorizado en Omise, una nota del pedido lo indica una vez: revisa el panel de Omise por si hay un pago doble y reembólsalo o anúlalo allí.
El webhook responde Charge ID does not match order: el cargo del evento pertenece a otro pedido. No se cambia nada.
El webhook responde Order is being processed, retry later o Failed to verify charge: otra solicitud bloqueó el pedido, o no se pudo acceder a la API de Omise. Omise reintenta el webhook.
Error al guardar: key must start with ... o must be a live key: se pegó una clave en el campo equivocado. Las claves de prueba empiezan por pkey_test_ / skey_test_, y las de producción por pkey_ / skey_.
El cliente ve 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). Revisa las claves y Test mode.
El cliente ve 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; la nota del pedido te pide que revises el panel de Omise antes de volver a cobrar el pedido.
El cliente ve This order is already being paid: la finalización de compra se envió dos veces al mismo tiempo. El cliente debe esperar y revisar el correo electrónico antes de volver a intentarlo.
El pedido está En espera tras el pago: lee la nota del pedido. El pedido espera la captura, Omise todavía no ha confirmado el pago, o el importe o la moneda no coinciden con el pedido.
El reembolso falla con un mensaje sobre el modo: 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.
Falla un reembolso parcial de un pedido autorizado: el pago solo está autorizado. Captúralo primero, o reembolsa el importe total para anularlo.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya está usada 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 acceder al 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 la licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Delete data on uninstall estaba activado. En caso contrario se conservan para una reinstalación posterior. Los datos de Omise guardados en los pedidos forman parte del historial de pagos y siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Omise es una marca registrada de su respectivo propietario. Este plugin no está afiliado a Omise ni cuenta con su respaldo.