VibeFox Conekta 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: la moneda del carrito debe ser MXN o USD. Para otras monedas, el método de pago se oculta.

Cuenta de Conekta: necesitas las claves privadas de API de tu cuenta de Conekta (de prueba y de producción) y un webhook en el panel de Conekta (ver Configuración). Solo se usan las claves privadas. La clave pública no es necesaria, porque el pago se realiza en la página de pago alojada de Conekta.

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 Conekta 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 de configuración y haz clic en Activate (ver Clave de licencia).

4. Introduce tus claves privadas de prueba y de producción, elige el modo y añade el webhook en el panel de Conekta (ver Configuración).

5. Activa Enable / Disable y haz clic en Save. Prueba un pago en modo de prueba y después desactiva Test mode.

Al instalarse, el módulo crea dos estados de pedido: Awaiting Conekta payment y Conekta 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.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Conekta 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 Conekta está activado pero la clave privada del modo actual está vacía (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 MXN o USD. Mientras el modo de prueba está activado, muestra El modo de prueba está activado: los pagos se simulan con la clave privada de prueba. Cuando guardas una pasarela activada sin la clave del modo actual, un aviso te pide que la introduzcas.

Conekta

Enable / Disable: Enable Conekta payments activa o desactiva el método de pago. Predeterminado: desactivado.

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 guardado en el pedido. Predeterminado: Conekta. Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: los métodos que se ofrecen en la página de pago de Conekta. Predeterminado: card, cash and bank transfer. Efectivo, SPEI y BNPL están disponibles solo para pedidos en MXN (los pedidos en USD solo admiten tarjetas) y deben estar activados en tu cuenta de Conekta. Si no se selecciona ninguno, se usa la tarjeta y la página te avisa al guardar.

Claves API

Copia tus claves privadas desde el panel de Conekta en Developers > API keys. Las claves de prueba y de producción son distintas.

Test mode: usa la clave privada de prueba. No se cobra dinero real y se muestra una insignia TEST MODE con No se realizará ningún cargo real. debajo del método de pago en la finalización de compra. Los reembolsos siempre usan la clave del modo en el que se hizo el pago. Predeterminado: activado.

Test private key: la clave privada de API del modo de prueba de tu cuenta de Conekta.

Live private key: la clave privada de API del modo de producción de tu cuenta de Conekta. Manténla en secreto.

Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Guardada — deja el campo vacío para conservarla. Escribe un valor nuevo solo si quieres cambiarla.

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

Cada pedido de Conekta recuerda su modo: las notificaciones y los reembolsos usan la clave correspondiente. Mantén ambas claves rellenadas mientras haya pedidos de prueba antiguos abiertos.

Webhook

El webhook informa a tu tienda sobre los pagos, por ejemplo los pagos en OXXO o SPEI realizados después de que el cliente abandonó la página de Conekta. En el panel de Conekta ve a Developers > Webhooks y añade la URL que aparece en el campo Webhook de la sección API keys, tanto para el modo de prueba como para el de producción. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_conekta_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en los ajustes.

Selecciona estos eventos (también aparecen en los ajustes):

El cuerpo del webhook solo indica al módulo qué pedido de Conekta cambió. Cada notificación se verifica leyendo el pedido de nuevo desde la API de Conekta con la clave privada de su modo; la cabecera de firma Digest del webhook no se usa. Las notificaciones de pedidos de Conekta que no fueron creados por esta tienda para ese carrito se confirman y se ignoran. Sin el webhook, el pedido se crea solo cuando el cliente vuelve a la tienda después de pagar, o en el siguiente intento de pago del mismo carrito.

Avanzado

Debug log: registra las llamadas a la API y las notificaciones en logs/wc_ckt_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, incluso cuando este interruptor está desactivado. Los registros nunca contienen claves API ni datos de contacto de clientes. Predeterminado: desactivado.

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 el módulo se eliminan los ajustes y el registro. Las transacciones y los reembolsos de Conekta, los estados de pedido y los pedidos siempre se conservan, para que los pedidos antiguos puedan confirmarse y reembolsarse 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 Conekta) y confirma. El módulo crea un pedido de Conekta por el total del carrito en la moneda del carrito, con los productos, el envoltorio de regalo, los descuentos, los impuestos y el envío, y envía al cliente a la página de pago alojada de Conekta. El pago aparece en la página de Conekta como Order # y el número del carrito. Allí el cliente paga con uno de los métodos permitidos. En este punto 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 Conekta lo confirma: el módulo lee el pedido desde la API de Conekta cuando llega el webhook y cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Hemos recibido tu pago con Conekta. Si el cliente eligió OXXO o SPEI y recibió una referencia de pago, el pedido se crea como Awaiting Conekta payment y la página muestra Se ha generado tu referencia de pago de Conekta. El pedido se confirmará en cuanto se reciba el pago. Si la referencia caduca después, el pedido se cancela y su página de confirmación muestra Tu pago con Conekta no se completó. Ponte en contacto con nosotros sobre este pedido.

Si el pago todavía no puede confirmarse cuando el cliente vuelve, aparece una página de Confirmación del pago con Estamos confirmando tu pago con Conekta. El pedido se actualizará automáticamente; por favor, no vuelvas a pagar. y un botón Check again. El webhook crea el pedido en cuanto llega.

Si el pago es rechazado, no se crea ningún pedido y el cliente vuelve a la finalización de compra con El pago con Conekta no se completó. Vuelve a intentarlo o elige otro método de pago. Si la página de pago caducó o se canceló, el mensaje es El pago con Conekta ha caducado o se ha cancelado. Vuelve a intentarlo. El carrito se conserva. Cuando el cliente paga de nuevo, se reutiliza una página de pago abierta de Conekta con el mismo importe; en caso contrario, la anterior se cancela en Conekta antes de crear una nueva, de modo que un enlace antiguo no pueda pagarse dos veces. Si la página anterior ya estaba pagada, se crea el pedido en lugar de cobrar de nuevo.

Si Conekta no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo El pago no pudo iniciarse. Vuelve a intentarlo en un momento o elige otro método de pago. Los mensajes de validación de Conekta, como un importe mínimo, se muestran tal como los envía Conekta. El motivo técnico se escribe en el registro.

El webhook funciona con la tienda en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.

El módulo acepta pagos solo en la página de Conekta. No tiene formulario de tarjeta en tu página de finalización de compra, ni tarjetas guardadas, suscripciones, preautorización y captura, ni pagos a plazos mensuales (MSI).

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a Conekta y no ha pagado, el pago fue rechazado o Conekta todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: Conekta confirmó el pago con el mismo importe y moneda. El pago se registra con el ID del cargo de Conekta como ID de transacción, y una nota muestra el método de pago (por ejemplo, la marca de la tarjeta y las últimas cuatro cifras, OXXO / efectivo o transferencia SPEI), el pedido de Conekta y el cargo.

Awaiting Conekta payment: el cliente recibió una referencia de pago de OXXO o SPEI. El pedido pasa a Payment accepted cuando Conekta informa del pago.

Conekta payment on hold: el importe o la moneda recibidos de Conekta no coinciden con el carrito (por ejemplo, si el carrito se modificó después de iniciar el pago), llegó un pago en modo de prueba mientras la tienda estaba en modo de producción (no se cobró dinero real), o el pago llegó para un pedido que ya estaba cancelado. La nota lo explica y el pago se registra con el importe realmente pagado. Revisa el pedido y después procésalo o reembolsa el pago. Un pedido que solo está preautorizado en Conekta también se pone en espera, con una nota para capturarlo o anularlo en el panel de Conekta.

Canceled: expiró la referencia de OXXO o SPEI de un pedido pendiente, o su pedido de Conekta fue cancelado.

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

Un pedido pagado o reembolsado nunca se degrada ni se vuelve a abrir. Si llega otro pago de Conekta para un pedido que ya está pagado, una nota WARNING te pide que lo reembolses en el panel de Conekta.

Bloque de pago de Conekta

La página del pedido muestra un bloque Conekta payment con el pedido de Conekta, el cargo, el estado del pago, el importe pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Conekta notes del pedido.

Reembolsos

En el bloque Conekta payment, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Conekta. Confirma la pregunta ¿Reembolsar este importe a través de Conekta? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos se limitan al importe y la moneda que Conekta realmente cobró, así que tras una diferencia de importe puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. El reembolso se envía al pedido de Conekta que contiene el pago y usa la clave del modo en el que se hizo el pago, así que esa clave debe estar configurada. Si Conekta no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el importe, el modo, el pedido de Conekta, el ID del reembolso y el motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Conekta ha informado del pago.

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

Los reembolsos hechos en el panel de Conekta llegan mediante el webhook y se añaden como nota con el importe reembolsado en Conekta y en PrestaShop. No se registran automáticamente. Actualiza el pedido manualmente sin usar Refund via Conekta. Un contracargo notificado por Conekta también se añade como nota.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Conekta Gateway es el primer bloque de Modules > Module Manager > VibeFox Conekta 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 quitar la clave de esta tienda. Debajo de ellos aparece la línea Product: presta-payment-conekta y el enlace Gestionar licencias y dominios en tu cuenta, 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 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 y una fecha. Después de 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 no se puede contactar con el servidor de licencias, 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Conekta 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. 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 después de introducir la clave y, después, una vez por semana. No se necesita ninguna tarea programada (cron). Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Conekta no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable / Disable está activado, que la clave privada del modo actual está rellenada (Test private key en modo de prueba, Live private key en modo de producción) y que la moneda del carrito es MXN o USD. La página de ajustes muestra un aviso cuando falta la clave o la moneda de la tienda no es compatible. 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 Conekta comprueba que el webhook existe para el modo que usas (prueba o producción), que su URL es exactamente la que aparece en los ajustes y que los eventos están seleccionados. Comprueba que la clave privada de ese modo está configurada, porque cada notificación se verifica con ella. El pedido también se crea cuando el cliente vuelve a la tienda o cuando intenta pagar de nuevo el mismo carrito.

El webhook responde Temporarily unavailable: no se pudo contactar con la API de Conekta, falta la clave privada del modo del pedido, otra solicitud estaba procesando el carrito o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Conekta reintenta el webhook. Consulta el campo Log para ver el motivo.

El webhook responde Verification failed, Invalid payload o Invalid order id: la API de Conekta no confirmó el pedido, o la notificación no era un evento válido de pedido de Conekta.

El webhook responde Ignored: la notificación pertenece a un pedido de Conekta que no fue creado por esta tienda para ese carrito (por ejemplo, otra tienda o un enlace de pago en la misma cuenta), o a un objeto distinto de un pedido.

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

El cliente ve No hemos podido comprobar el estado de tu intento de pago anterior: no se pudo leer la página de pago anterior de Conekta del carrito, así que no se crea una nueva para evitar un doble pago. Inténtalo de nuevo en un momento.

El cliente ve La pasarela de pago no está configurada: falta la clave privada del modo actual.

El cliente ve La verificación del pago ha fallado: el enlace de retorno de Conekta no coincidía con el carrito. Comprueba el pedido en el panel de Conekta; el webhook sigue confirmando un pago real.

El pedido está en Awaiting Conekta payment o Conekta payment on hold: lee las Conekta notes en el bloque del pedido. El cliente aún no ha pagado la referencia de OXXO o SPEI, el importe o la moneda no coincidían, llegó un pago en modo de prueba mientras la tienda estaba en modo de producción, o el pago solo está preautorizado.

El reembolso falla con un mensaje sobre el modo de prueba o de producción: el pago se realizó en ese modo y su clave privada no está configurada. Introdúcela y vuelve a intentarlo.

Para desarrolladores, el README enumera los hooks actionWcpConektaSupportedCurrencies, actionWcpConektaOrderRequest, actionWcpConektaAllowedPaymentMethods y actionWcpConektaRefundReason.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Conekta 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 y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Conekta y los estados de pedido Awaiting Conekta payment y Conekta payment on hold siempre se conservan, de modo que los pedidos pagados antes pueden reembolsarse tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Conekta es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por Conekta.