VibeFox IntaSend for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior con la extensión cURL. El módulo no se instala en versiones anteriores de PHP ni sin cURL.

HTTPS: IntaSend requiere HTTPS para los pagos en producción y los webhooks. La página de configuración te avisa cuando el modo de producción está activado y la tienda no usa HTTPS.

Cuenta de IntaSend: necesitas la clave pública (ISPubKey_...) y la clave secreta (ISSecretKey_...) de tu cuenta de IntaSend, para el sandbox, para producción o para ambos, y un webhook con frase de desafío en el panel de IntaSend (ver Configuración). La clave pública crea la finalización de compra. La clave secreta se usa solo en tu servidor para pedir a IntaSend el estado del pago.

Moneda de la tienda: KES, USD, EUR, GBP, UGX, TZS, NGN, GHS, XAF o XOF. Para otras monedas el método de pago se oculta.

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 IntaSend Pay 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 (ver Clave de licencia).

4. Pega tus claves de IntaSend de sandbox y/o de producción, añade el webhook en el panel de IntaSend e introduce el mismo desafío en el módulo (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Prueba un pago con Test mode activado y luego desactiva Test mode para aceptar pagos reales.

Al instalarse, el módulo crea el estado de pedido IntaSend 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 IntaSend Pay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, un cuadro de estado muestra Test mode: IntaSend sandbox, no real money is charged. o Live mode: real payments are accepted. También avisa cuando faltan o son incorrectas las claves del modo actual (en ese caso el método de pago se oculta en la finalización de compra), cuando la moneda predeterminada de la tienda no es compatible, cuando no hay frase de desafío del webhook y cuando se usa el modo de producción sin HTTPS. Al guardar, se quitan los espacios sobrantes de las claves pegadas.

IntaSend

Enable/Disable: Enable IntaSend 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 guardado en el pedido. Predeterminado: IntaSend (M-Pesa, card). Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

Claves de API

Obtén las claves en el panel de IntaSend, en Settings > API Keys, por separado en el panel de sandbox y en el de producción (la sección tiene enlaces a ambos). El modo de prueba usa las claves de sandbox y la API de sandbox; el modo de producción usa las claves de producción y la API de producción. El módulo comprueba que la clave pública empiece por ISPubKey_, que la clave secreta empiece por ISSecretKey_, y que las claves pertenezcan al modo actual: las claves de sandbox contienen _test, las de producción contienen _live. Si no es así, el método de pago se oculta y el cuadro de estado explica por qué.

Test mode: usa el sandbox de IntaSend, no se cobra dinero real. Predeterminado: activado. Desactívalo para aceptar pagos reales con las claves de producción. Mientras el modo de prueba esté activado, la finalización de compra muestra TEST MODE - IntaSend sandbox, no real money is charged. debajo del método de pago.

Sandbox publishable key: empieza por ISPubKey_test. Identifica tu negocio cuando se crea una finalización de compra.

Sandbox secret key: empieza por ISSecretKey_test. Se usa solo en tu servidor para confirmar pagos con la API de estado de pago.

Live publishable key: empieza por ISPubKey_live.

Live secret key: empieza por ISSecretKey_live. Se usa solo en tu servidor para confirmar pagos.

Las claves secretas guardadas y la frase de desafío del webhook 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.

Webhook

El webhook avisa a tu tienda de que se ha realizado un pago, incluso cuando el cliente no vuelve a la tienda (navegador cerrado, M-Pesa confirmado más tarde). En el panel de IntaSend, en sandbox y en producción, abre Webhooks y añade la URL que aparece en Webhook URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_intasend_pay/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestra la configuración. Introduce allí una frase de desafío y la misma frase en el módulo. Usa un solo desafío para sandbox y producción.

Webhook challenge: la misma frase de desafío que en el panel de IntaSend. Los webhooks con otra frase se rechazan. Mientras este campo esté vacío, los webhooks no se procesan y los pagos solo se confirman cuando el cliente vuelve a la tienda. Estos webhooks reciben como respuesta Ignored, no un error, para que IntaSend no desactive el webhook antes de que introduzcas la frase.

Borrar secretos guardados: marca Sandbox secret key, Live secret key o Webhook challenge y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

El módulo reacciona a estos estados de pago informados por IntaSend. Cada vez, consulta a la API de estado de pago el estado real antes de cambiar nada:

Las notificaciones que no son pagos de finalización de compra de esta tienda, por ejemplo enlaces de pago o eventos de envío de dinero de la misma cuenta de IntaSend, se responden con Ignored, para que IntaSend no desactive el webhook.

Avanzado

Debug log: registra los eventos de finalización de compra, retorno y webhook en logs/intasend_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. Las claves de API 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 los ajustes de la pasarela y el registro. Las referencias de IntaSend guardadas para los pedidos son historial de pagos y siempre se conservan. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (de forma predeterminada IntaSend (M-Pesa, card)) y confirma. El módulo crea una finalización de compra de IntaSend por el importe total del carrito en la moneda del carrito y envía al cliente a la finalización de compra alojada por IntaSend. Allí el cliente paga con M-Pesa, con tarjeta u otro método activado en tu cuenta de IntaSend. El correo electrónico del cliente, así como el nombre, la dirección, el teléfono y el país de la dirección de facturación, se envían a IntaSend cuando cumplen las reglas de campos de IntaSend. Los campos vacíos o no válidos se omiten. 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 IntaSend lo confirma: el módulo consulta la API de estado de pago cuando el cliente vuelve y cuando llega el webhook. Entonces se crea el pedido y el cliente ve la página estándar de confirmación de pedido. Si el pedido quedó en espera, la página muestra Your payment was received and your order is being reviewed. We will contact you if anything is needed. Si el pago aún no está confirmado, o IntaSend no responde en ese momento, aparece una página de Payment confirmation con el mensaje Your payment is being confirmed by IntaSend (M-Pesa confirmations can take a minute). You will receive an e-mail as soon as it is confirmed. y con los botones Check again y Back to checkout. El webhook crea el pedido en cuanto IntaSend confirma el pago.

Si el pago falló, el cliente vuelve a la finalización de compra con The payment was not successful. Please try again or choose another payment method. (con el motivo de IntaSend, si se indica). Si el cliente volvió sin pagar, el mensaje es The payment was not completed. Please try again or choose another payment method. El carrito se conserva y el cliente puede volver a pagar. Cada intento tiene su propia referencia de IntaSend.

Si IntaSend no puede iniciar el pago, el cliente se queda en la finalización de compra con IntaSend could not start the payment: y el motivo de IntaSend, o con IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. Los detalles se escriben en el registro. Un carrito con importe cero no se puede pagar con IntaSend.

El webhook funciona aunque la tienda esté en modo de mantenimiento y no se ve afectado por la restricción de países de tu tienda. Si las URL amigables están desactivadas, el cliente vuelve a través de la página de inicio de la tienda, porque IntaSend no acepta algunos caracteres en la dirección de retorno.

El módulo solo acepta pagos únicos. Los reembolsos no se envían a IntaSend desde la tienda, y no tiene tarjetas guardadas, suscripciones ni formulario de pago integrado (emergente). Los enlaces de finalización de compra anteriores del mismo carrito no se pueden cancelar en IntaSend.

Pedidos

Estados del pedido

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

Payment accepted: el pago fue confirmado. El pago se registra con el ID de la factura de IntaSend como ID de transacción, y una nota muestra la factura, el método de pago en IntaSend, el importe, el modo (sandbox o producción) y la forma en que se confirmó (webhook o retorno del cliente).

IntaSend payment on hold: IntaSend informó de un importe o una moneda distintos del total del carrito, de un pago parcial o de un pago que llegó después de que el pedido se cancelara. La nota lo explica, y el importe que IntaSend cobró se registra como pago cuando está en la moneda del pedido. Comprueba el pago en el panel de IntaSend y tramita el pedido o reembolsa el pago. Si después llega el pago correcto, el pedido pasa a Payment accepted.

Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que lo reembolses en el panel de IntaSend si es un duplicado. Un pago para un pedido reembolsado añade una nota y no reabre el pedido.

Bloque de pago de IntaSend

La página del pedido muestra un bloque IntaSend payment con cada intento de finalización de compra del carrito del pedido (fecha, referencia, finalización de compra de IntaSend, entorno, importe, factura y resultado, con el motivo del fallo) y las Invoices processed (factura, estado en IntaSend, importe y resultado). El bloque es de solo lectura.

Reembolsos

Los reembolsos no se envían a IntaSend desde la tienda. Reembolsa el pago en el panel de IntaSend y registra el reembolso manualmente en PrestaShop.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox IntaSend Pay Gateway es el primer bloque de Modules > Module Manager > VibeFox IntaSend Pay 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-intasend 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. 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 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, IntaSend 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 aviso 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 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

IntaSend no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que las claves del modo actual estén rellenadas y pertenezcan a ese modo: claves de sandbox (con _test) en modo de prueba, claves de producción (con _live) en modo de producción. La moneda del carrito debe ser compatible. El cuadro de estado en la parte superior de la página de ajustes muestra qué falla. 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: las confirmaciones de M-Pesa pueden tardar un momento. El webhook crea el pedido cuando IntaSend informa del estado final. Comprueba que la URL del webhook en el panel de IntaSend (sandbox o producción, el modo que usas) sea exactamente la que aparece en Webhook URL y que el desafío allí sea el mismo que Webhook challenge. El pedido también se crea cuando el cliente vuelve a la tienda o hace clic en Check again.

El webhook responde Ignored: webhook challenge not configured: Webhook challenge está vacío. Introduce el desafío del panel de IntaSend.

El webhook responde Invalid challenge: el desafío en IntaSend y en el módulo no coinciden, o el webhook no tiene desafío.

El webhook responde Verification unavailable, retry later o Busy, retry later: en ese momento no se pudo contactar con IntaSend, otra petición estaba confirmando el carrito, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). IntaSend vuelve a intentar el webhook. El motivo está en el registro.

El webhook responde Invoice not verified o Invoice does not match the reference: IntaSend no confirmó que esta factura pertenezca al carrito. No se cambia nada.

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

El pedido está en IntaSend payment on hold: lee las notas del pedido. El importe o la moneda pagados eran distintos del carrito, el pago fue parcial, o llegó después de que se cancelara el pedido. Comprueba el pago en el panel de IntaSend.

El cliente ve un error al elegir IntaSend: revisa el campo Log de la página del módulo (activa Debug log para más detalle). Si las claves del modo actual son incorrectas, el cliente ve IntaSend is not available at the moment. Please choose another payment method or contact the store. Si el registro dice que la URL de retorno contiene caracteres que IntaSend no acepta, la causa es la dirección de la tienda.

El cliente ve We could not match this payment to an order: el enlace de retorno fue modificado o pertenece a otro carrito. Si el cliente pagó, el webhook crea el pedido igualmente.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox IntaSend Pay 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 de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de finalización de compra y las facturas de IntaSend de los pedidos, así como el estado de pedido IntaSend payment on hold, siempre se conservan. Los pedidos existentes conservan sus notas de pago e ID de transacción.

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