VibeFox Midtrans 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: rupia indonesia (IDR). Midtrans cobra solo en IDR, así que el método de pago se ofrece únicamente cuando la moneda del carrito es IDR. No hay conversión de moneda. Añade la moneda IDR en International > Localization si tu tienda no la tiene.
Cuenta de Midtrans: necesitas la Server Key de Midtrans Dashboard > Settings > Access Keys, tanto en el panel de sandbox como en el de producción. Solo se usa la Server Key. La Client Key no es necesaria para Snap Redirect. Los métodos de pago en sí (GoPay, QRIS, cuentas virtuales y otros) se activan en tu cuenta de Midtrans.
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 subida, haz clic en Configure, o busca más tarde VibeFox Midtrans Payment Gateway 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 (ver Clave de licencia).
4. Introduce las Server Keys y copia la URL de notificación de pago en el panel de control de Midtrans (consulta Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba en Sandbox y después cambia Environment a Production.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Midtrans payment y Midtrans payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences. El módulo debe seguir permitido para la moneda IDR.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa cuando falta la Server Key del entorno seleccionado (en ese caso el método de pago se oculta en la finalización de compra) y cuando la moneda predeterminada de la tienda no es IDR, y muestra Sandbox mode: payments are simulated, no real money is charged. mientras esté seleccionado Sandbox.
Midtrans
Enable/Disable: Enable Midtrans payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el título 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. Predeterminado: Midtrans. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. En Sandbox se añade la línea SANDBOX MODE: no real money is charged.
Credenciales de API
Copia la Server Key de Midtrans Dashboard > Settings > Access Keys. La sección tiene enlaces al panel de producción y al panel de sandbox.
Environment: qué entorno de Midtrans usan los nuevos pagos. Al cambiarlo se usan la clave y la API del entorno seleccionado. Los pagos conservan el entorno en el que se hicieron, para los reembolsos y las notificaciones. Predeterminado: Sandbox.
Production Server Key: empieza por Mid-server-. Manténla en secreto.
Sandbox Server Key: empieza por SB-Mid-server-.
Las claves guardadas no se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla.
Clear saved keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
URL de notificación de pago
La notificación informa a tu tienda de que se ha realizado un pago. El campo Notification URL muestra la URL que hay que usar. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_midtrans_payment_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes y pégala en Midtrans Dashboard > Settings > Payment > Notification URL, en el panel de sandbox y en el de producción que uses. Si abres la URL en un navegador, aparece una breve explicación, así puedes comprobar que es accesible. El botón Test notification URL del panel de Midtrans también recibe respuesta.
Cada notificación debe llevar una firma válida hecha con una de tus Server Keys, y el entorno de la clave debe coincidir con el entorno del pago. Las notificaciones sin firma válida se rechazan. Entonces el estado se vuelve a leer en la API de estado de Midtrans. El módulo gestiona estos estados de transacción de Midtrans:
Sin la URL de notificación, el pedido solo se crea cuando el cliente vuelve a la tienda tras pagar, y un pago diferido hecho más tarde no se ve hasta que el cliente regresa.
Ajustes de pago
Midtrans cobra solo en IDR, y los importes se envían en rupias enteras. Si las líneas del pedido no suman el total redondeado, se envía a Midtrans una línea Rounding adjustment.
Status after payment: el estado del pedido tras un pago confirmado.
Payment page expiry (minutes): cuánto tiempo puede pagar el cliente (página Snap, cuenta virtual, etc.). Déjalo vacío o en 0 para el valor predeterminado de Midtrans. Un valor que no sea un número entero de minutos se rechaza con un error al guardar.
Order ID prefix: se añade al número enviado a Midtrans, para que varias tiendas puedan compartir una cuenta de Midtrans. El número es el ID del carrito con una marca de tiempo, por ejemplo WC-123-1700000000. Solo letras, dígitos y - _ . ~, hasta 20 caracteres; los demás caracteres se eliminan al guardar. Las notificaciones de otras tiendas se ignoran. Predeterminado: WC-.
Avanzado
Debug log: escribe las llamadas a la API y las notificaciones en logs/midtrans_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran. Las claves y los datos de los clientes nunca 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 sus ajustes y el registro. Los pedidos, sus referencias de pago y reembolsos de Midtrans y los estados de pedido del módulo siempre se conservan, para que los pedidos antiguos se puedan reembolsar tras una reinstalación. Predeterminado: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Midtrans) y confirma. El módulo crea una transacción Midtrans Snap por el total del carrito en rupias enteras, con las líneas del pedido, el envío, los descuentos, el envoltorio de regalo, los impuestos y los datos de facturación y envío del cliente, y envía al cliente a la página de pago de Midtrans. Allí el cliente elige cualquier método habilitado en tu cuenta de Midtrans. Todavía no existe ningún pedido en este punto.
Tras pagar, el cliente vuelve a tu tienda. El enlace de retorno nunca marca un pedido como pagado: el pedido solo se marca como pagado cuando Midtrans lo confirma, mediante la notificación firmada o mediante una consulta a la API de estado de Midtrans cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con el método de pago utilizado. En un pago diferido, la página muestra We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Para un pedido cerrado sin pago, muestra Your Midtrans payment was not completed. Please contact us about this order. Si no se puede contactar con Midtrans cuando el cliente vuelve, aparece una página Payment confirmation que muestra We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. con un botón Check again.
Si el cliente salió de la página de Snap sin pagar, vuelve a la finalización de compra con el mensaje The Midtrans payment was not completed. You can try again below. Si el pago fue rechazado o caducó, el mensaje es Your Midtrans payment was declined or has expired. Please try again or choose another payment method. El carrito se conserva. Cuando el cliente vuelve a pagar, se reutiliza un Snap no usado o pendiente del mismo importe. Si el importe cambió, primero se caduca en Midtrans la transacción pendiente. Si el Snap anterior se pagó entretanto, se crea el pedido y no se hace ninguna transacción nueva. Si el pedido ya existe y se cerró sin pago, el mensaje es Your Midtrans payment was declined or has expired. Please place a new order or contact us.
Si Midtrans no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve: Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (por ejemplo, con una Server Key incorrecta) o el motivo que indique Midtrans. El motivo técnico se escribe en el registro. Un carrito que no esté en IDR muestra Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
La notificación funciona mientras la tienda está en modo de mantenimiento y no se bloquea con la restricción por país de tu tienda.
El módulo usa solo Snap Redirect. No tiene ventana emergente de Snap, ni formulario de tarjeta en tu sitio, ni tarjetas guardadas ni pagos de un clic, ni ajustes de cuotas o promociones (configura los métodos de pago en el panel de Midtrans) ni suscripciones. Los pagos con tarjeta se capturan de inmediato, sin autorización y captura por separado.
Pedidos y reembolsos
Estados de pedido
No order yet: el cliente fue enviado a Midtrans y no ha pagado, o Midtrans todavía no ha confirmado el pago. Solo existe el carrito.
Awaiting Midtrans payment: el cliente eligió un método diferido (cuenta virtual, tienda de conveniencia) o inició un pago con tarjeta que no ha terminado. El pedido pasa a pagado cuando Midtrans informa del pago.
Payment accepted, Delivered o Midtrans payment on hold: el pago fue confirmado. El estado sigue a Status after payment. El pago se registra con el ID de transacción de Midtrans, y una nota muestra el método de pago y el ID de pedido de Midtrans.
Midtrans payment on hold: también se establece cuando un pago con tarjeta está en revisión por fraude (challenge, sin pago registrado todavía), cuando el importe o la moneda pagados no coinciden con el pedido (el pedido no se marca como pagado) o cuando llega un pago para un pedido cancelado (el pedido no se reabre automáticamente). La nota lo explica. Revisa el pedido y después complétalo o reembolsa el pago.
Canceled: la transacción sin pagar caducó o se canceló. Cuando tú cancelas manualmente un pedido de Midtrans sin pagar, su transacción pendiente de Midtrans, por ejemplo una cuenta virtual emitida, caduca para que ya no pueda pagarse.
Payment error: el pago falló, o un pago con tarjeta en revisión fue denegado.
Refunded: el pago se reembolsó por completo.
Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que reembolses el segundo pago en el panel de Midtrans. Un pago para un pedido reembolsado solo añade una nota.
Bloque de pago de Midtrans
La página del pedido muestra un bloque Midtrans payment con el ID de pedido de Midtrans, el ID de transacción (enlazado a la transacción en el panel de Midtrans del entorno del pago), el método de pago, el estado, el importe pagado y reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las Midtrans notes del pedido.
Reembolsos
En el bloque Midtrans payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Midtrans. Confirma la pregunta Refund this amount through Midtrans? This cannot be undone. Se admiten reembolsos totales y parciales en rupias enteras; un importe con decimales se rechaza. Necesitas el permiso para editar pedidos. Puedes reembolsar hasta el importe que Midtrans cobró realmente, aunque el pedido se haya editado después. El reembolso se envía en el entorno en el que se hizo el pago, así que debe estar configurada la Server Key de ese entorno. Midtrans solo permite reembolsos por API para algunos métodos de pago y estados de transacción (por ejemplo, pagos con tarjeta liquidados, GoPay, QRIS o ShopeePay). Si Midtrans no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso; entonces reembolsa desde el panel de Midtrans. Un reembolso correcto se añade al historial de reembolsos y a las notas. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Midtrans haya informado de que el pago está liquidado.
El módulo no crea notas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Midtrans.
Los reembolsos hechos en el panel de Midtrans llegan mediante la notificación y se añaden automáticamente al historial de reembolsos, con el motivo Refunded in the Midtrans dashboard. Cuando todo el pago se reembolsa allí, el pedido pasa a Refunded.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Midtrans Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox Midtrans Payment Gateway > 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-midtrans 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 el inglés y el 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. 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, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un 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. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Midtrans no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, 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. 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 funcionan.
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 tras 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
Midtrans does not appear at checkout: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el Environment seleccionado tenga su Server Key. Comprueba que la moneda del carrito sea IDR. En Payment > Preferences comprueba que el módulo esté permitido para IDR, para el país del cliente y para su grupo. La página de ajustes muestra una advertencia cuando falta la clave o cuando la moneda de la tienda no es IDR.
The payment went through, but no order was created: la notificación no funciona. Comprueba que la URL de notificación de pago esté configurada en el panel de Midtrans del entorno que usas (sandbox o producción), que sea exactamente la URL que muestra Notification URL y que sea accesible: ábrela en un navegador, debe mostrar una breve explicación. Activa Debug log para ver las notificaciones. El pedido también se crea cuando el cliente vuelve a la tienda tras pagar.
Notification answers Invalid signature: la notificación no se firmó con tu Server Key de Sandbox o de Production. Comprueba que las claves de los ajustes pertenezcan a la misma cuenta de Midtrans que el panel que envía las notificaciones.
Notification answers Server key not configured: no hay ninguna Server Key configurada. Introdúcela en los ajustes; Midtrans reintenta la notificación.
Notification answers Order not found — ignored: el ID de pedido de Midtrans no lo emitió esta tienda, por ejemplo otra tienda de la misma cuenta de Midtrans. Asigna a cada tienda un Order ID prefix distinto.
Notification answers Environment mismatch — ignored: la notificación se firmó con la clave del entorno distinto de aquel en el que se hizo el pago.
Notification answers Verification failed, please retry: no se pudo contactar con la API de estado de Midtrans. Midtrans reintenta la notificación.
Notification answers Busy, please retry: el carrito estaba siendo actualizado por otra petición en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Midtrans reintenta la notificación. Consulta el registro para ver el motivo.
The order is Midtrans payment on hold: lee las Midtrans notes del bloque. El pago con tarjeta está en revisión por fraude, el importe o la moneda pagados no coinciden con el pedido, o el pago llegó después de cancelar el pedido.
The customer sees an error when choosing Midtrans: consulta el campo Log de la página del módulo; los errores siempre se registran. Una Server Key incorrecta muestra el mensaje de que los pagos de Midtrans no están disponibles temporalmente.
Refund fails: el método de pago o el estado de la transacción no permite reembolsos por API; reembólsalo desde el panel de Midtrans, y el reembolso se registrará automáticamente en el pedido. Si el mensaje dice que no hay ninguna Server Key configurada para el entorno en el que se pagó el pedido, introduce esa clave y vuelve a intentarlo.
Los desarrolladores pueden cambiar los datos enviados a Midtrans con el hook actionWcpMidtransSnapPayload; el ID de pedido y el importe no se pueden cambiar.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Midtrans Payment Gateway 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 del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las referencias de pago de Midtrans y los reembolsos de los pedidos, así como los estados de pedido Awaiting Midtrans payment y Midtrans payment on hold, siempre se conservan, para que los pedidos pagados antes se puedan reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Midtrans es una marca registrada de su respectivo titular. Este módulo no está afiliado a Midtrans ni cuenta con su respaldo.