VibeFox IntaSend for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con la versión 3.0.5.0) o 4.0.2 y posteriores (probado con la versión 4.1.0.3).

PHP: 8.0 o posterior con la extensión 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 dirección de la tienda no es HTTPS.

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

Moneda: KES, USD, EUR, GBP, UGX, TZS, NGN, GHS, XAF o XOF. Cuando la moneda de la finalización de compra del cliente es otra, 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

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_intasend_pay-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_intasend_pay.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_intasend_pay-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox IntaSend Pay Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (consulta Clave de licencia).

4. Pega tus claves de sandbox y/o de producción de IntaSend, añade el webhook en el panel de IntaSend e introduce la misma frase de desafío en la extensión (consulta 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.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_intasend_pay.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox IntaSend Pay Gateway, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).

4. Introduce la clave de licencia, las claves de IntaSend y el webhook como en los pasos 3 a 5 de OpenCart 3. La página de configuración y sus campos son los mismos en ambas versiones. Solo la URL del webhook es distinta (consulta Webhook).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox IntaSend Pay Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, 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 para el webhook y cuando se usa el modo de producción sin HTTPS. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío ni tener más de 128 caracteres, Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido seleccionados deben existir. Si no, no se guarda nada y el error indica el campo. Los problemas con las claves no impiden guardar: el cuadro de estado los indica. Las claves pegadas se recortan (se eliminan los espacios sobrantes).

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, de 1 a 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Predeterminado: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

Sort Order: la posición de IntaSend entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece IntaSend solo para las direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el importe total de la finalización de compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca IntaSend. Déjalo vacío para ofrecer IntaSend con cualquier importe.

Claves API

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

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, los clientes ven TEST MODE - IntaSend sandbox, no real money is charged. en el paso Confirm Order.

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 los pagos con la API de estado del pago (Payment Status API).

Live publishable key: empieza por ISPubKey_live.

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

Las claves secretas guardadas y la frase de desafío del webhook no 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. Para eliminar un valor guardado, marca Clear the saved value debajo del campo y haz clic en Save.

Webhook

El webhook informa a tu tienda de que se ha realizado un pago, aunque el cliente no vuelva a la tienda (navegador cerrado, M-Pesa confirmado más tarde). En el panel de IntaSend, tanto en el sandbox como en producción, abre Webhooks y añade la URL que aparece en Webhook URL en esta sección. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_intasend_pay/webhook; en OpenCart 4, este otro: https://your-store/index.php?route=extension/wcp_intasend_pay/payment/wcp_intasend_pay.webhook. Se genera a partir de la dirección de la tienda de tu instalación de OpenCart. Copia la URL exactamente como aparece en los ajustes. Introduce allí una frase de desafío y la misma frase en la extensión. Usa un mismo desafío para el sandbox y para producción.

Webhook challenge: la misma frase de desafío que en el panel de IntaSend. Los webhooks con otra frase de desafío 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 se responden como ignorados, no como un error, para que IntaSend no desactive el webhook antes de que introduzcas la frase de desafío.

La extensión reacciona a estos estados de pago informados por IntaSend. Cada vez, antes de cambiar nada, consulta a la API de estado del pago cuál es el estado real:

Las notificaciones que no son pagos de la 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.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido «missing order»). El pedido recibe un estado solo después de que IntaSend haya confirmado el pago a través de la API de estado del pago. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Paid Order Status: el estado que se asigna tras un pago confirmado por IntaSend. Predeterminado: Procesando.

On Hold Status: IntaSend informó de un importe o una moneda distintos, de un pago parcial o de un pago posterior a la cancelación del pedido. El pedido recibe este estado y una nota que explica el motivo. Predeterminado: Pendiente de pago, porque OpenCart no tiene un estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Refunded Status: un pago que llega para un pedido en este estado solo añade una nota; el pedido no se reabre. Predeterminado: Reembolsado. La propia extensión no realiza reembolsos.

Avanzado

Debug log: registra los eventos de la finalización de compra, del retorno y de los webhooks en intasend_p_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se mueve a intasend_p_debug.old.log.php. Los errores y las advertencias siempre se registran. Las claves API, la frase de desafío 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 la extensión se eliminan los ajustes de la pasarela y el registro. Las referencias de IntaSend guardadas para los pedidos forman parte del historial de pagos y siempre se conservan. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes como archivo JSON. Las claves secretas y la frase de desafío del webhook no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves secretas guardadas y la frase de desafío del webhook se mantienen.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (de forma predeterminada, IntaSend (M-Pesa, card)). En el paso Confirm Order, el cliente ve tu descripción. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea una finalización de compra de IntaSend por el importe total del pedido, en la moneda del pedido, y envía al cliente a la página de pago alojada por IntaSend. Allí el cliente paga con M-Pesa, con tarjeta o con otro método activado en tu cuenta de IntaSend. El correo electrónico y el teléfono del cliente, así como el nombre, la dirección y el país de la dirección de pago, se envían a IntaSend cuando cumplen las reglas de campos de IntaSend. Los campos vacíos o no válidos se omiten. Cada intento recibe su propia referencia de IntaSend.

En OpenCart 4, el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra. De forma predeterminada, OpenCart 4 no pide una dirección de pago; en ese caso, la extensión envía a IntaSend la dirección, la ciudad, el código postal y el país de la dirección de envío.

Tras pagar, el cliente vuelve a través de la dirección de la página de inicio de tu tienda, porque IntaSend no admite algunos caracteres en la dirección de retorno; la extensión redirige al cliente a su página de retorno. El pedido se marca como pagado solo cuando IntaSend lo confirma: la extensión consulta la API de estado del pago cuando el cliente regresa y cuando llega el webhook. Después, el pedido recibe su estado de la forma habitual de OpenCart, con los correos electrónicos de pedido habituales y la actualización del stock, y el cliente ve la página de confirmación del pedido de OpenCart. Si el pedido se puso en espera, la página también 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 si IntaSend no responde en ese momento, aparece la página Payment confirmation con 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., junto con los botones Check again y Back to checkout. El webhook asigna el estado del pedido en cuanto IntaSend confirma el pago.

Si el pago ha fallado, 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 regresó 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. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 actualiza el pedido de la compra, de modo que, tras un pago fallido, el cliente paga el mismo pedido con un nuevo intento. Un carrito solo se paga una vez: si otro pedido del mismo carrito ya está pagado, el cliente va a la página de éxito en lugar de a un nuevo pago. Un cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se ha cerrado mientras tanto (por ejemplo, lo has cancelado o reembolsado), el cliente vuelve a la finalización de compra con Your previous order was cancelled or refunded. Please confirm the order again. Si el pedido ya está realizado y el carrito contiene ahora otros productos, el mensaje es Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. En ambos casos, el siguiente Confirm Order paga un nuevo pedido del carrito.

Si IntaSend no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un mensaje encima del botón: IntaSend could not start the payment: seguido del motivo de IntaSend, o bien IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. Los detalles se escriben en el registro. Un pedido con importe total cero no se puede pagar con IntaSend.

El webhook también funciona mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio que deja pasar el webhook y el regreso del cliente.

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

Pedidos

Estados del pedido

No status (missing order): el cliente fue enviado a IntaSend y no ha pagado, el pago ha fallado o IntaSend todavía no ha confirmado el pago. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Paid Order Status (default Processing): el pago fue confirmado. Una nota muestra la factura de IntaSend, el método de pago en IntaSend, el importe, el modo (sandbox o producción) y cómo se confirmó (webhook o retorno del cliente).

On Hold Status (default Pending): IntaSend informó de un importe o una moneda distintos al total del pedido, de un pago parcial o de un pago que llegó después de cancelar el pedido. La nota lo explica. Revisa el pago en el panel de IntaSend y completa el pedido o reembolsa el pago. Si el pago correcto llega más tarde, el pedido pasa a Paid Order Status y el cliente recibe un correo electrónico de aviso.

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 en Refunded Status añade una nota y no reabre el pedido.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox IntaSend Pay Gateway

En Sales > Orders, abre un pedido pagado con IntaSend. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox IntaSend Pay Gateway muestra los IntaSend checkout attempts del pedido (fecha, referencia, finalización de compra de IntaSend, entorno, importe, factura y método de pago, resultado con el motivo del fallo), las Invoices processed (factura, estado en IntaSend, importe y resultado) y las IntaSend notes del pedido. La pestaña es solo de lectura y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos no se envían a IntaSend desde la tienda. Reembolsa el pago en el panel de IntaSend y registra el reembolso en OpenCart manualmente, por ejemplo, cambiando el pedido al estado Refunded Status.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox IntaSend Pay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox IntaSend Pay Gateway > Edit, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-intasend y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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 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 no se puede acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda según la configuración de OpenCart. Eliminar 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. Un usuario administrador que haya iniciado sesión en el panel en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que, sin una clave activa, el método de pago se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del administrador. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del administrador: 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 es necesaria ninguna tarea cron. Al desinstalar la extensión, siempre se eliminan 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 corresponden a ese modo: claves del sandbox (con _test) en el modo de prueba, claves de producción (con _live) en el modo de producción. El cuadro de estado de la parte superior de la página de ajustes indica qué falla. La moneda de la finalización de compra del cliente debe ser compatible. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total definido en los ajustes.

El pago se realizó, pero el pedido se queda sin estado: las confirmaciones de M-Pesa pueden tardar un momento. El webhook asigna el estado cuando IntaSend informa del estado final. Comprueba que la URL del webhook en el panel de IntaSend (sandbox o producción, el modo que uses) sea exactamente la que aparece en Webhook URL y que la frase de desafío allí sea la misma que Webhook challenge. El pedido también recibe su estado 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 la frase de desafío del panel de IntaSend.

El webhook responde Invalid challenge: la frase de desafío de IntaSend y la de la extensión no coinciden, o el webhook no tiene frase de desafío.

El webhook responde Verification unavailable, retry later o Busy, retry later: no se pudo contactar con IntaSend en ese momento, el pedido (su carrito) estaba siendo confirmado por otra solicitud, o no se pudo asignar el estado del pedido. IntaSend reintenta el webhook. El motivo aparece en el registro.

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

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

El pedido está en On Hold Status: lee las notas de la pestaña VibeFox IntaSend Pay Gateway. El importe o la moneda pagados no coincidían con el pedido, el pago fue parcial o llegó después de cancelar el pedido. Revisa el pago en el panel de IntaSend.

El cliente ve un error después de Confirm Order: revisa el campo Log de la página de la extensión (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. This payment method is not available. significa que la sesión de finalización de compra ya no coincide con el pedido o que el método de pago se desactivó entretanto: el cliente debe recargar la finalización de compra. Si el registro dice que la URL de retorno contiene caracteres que IntaSend no admite, 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 se cambió o pertenece a otro pedido. Si el cliente pagó, el webhook asigna igualmente el estado del pedido.

Para desarrolladores: antes de crear la finalización de compra, la extensión dispara el evento de OpenCart intasend_p_checkout_payload con los datos de la solicitud, el pedido y el modo; el evento intasend_p_supported_currencies puede cambiar la lista de monedas.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox IntaSend Pay Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart elimina siempre sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. También se eliminan los eventos de OpenCart de la extensión (en OpenCart 4, también su acción de inicio, que deja pasar el webhook y el regreso del cliente en modo de mantenimiento). Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, claves, frase de desafío del webhook, interruptor del registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las finalizaciones de compra de IntaSend y las facturas de los pedidos siempre se conservan. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox IntaSend Pay Gateway en la lista de extensiones instaladas; después, haz clic en Delete (el botón rojo de papelera) para eliminar el paquete subido.

IntaSend es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por IntaSend.