VibeFox Razorpay 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.

Cuenta de Razorpay: necesitas el Key ID y el Key Secret de tu cuenta de Razorpay para el modo de prueba, y para el modo en vivo una vez activada tu cuenta. Se recomienda encarecidamente un webhook con un secreto de tu elección (consulta Configuración). Los pagos en monedas distintas de INR requieren tener activado International Payments en tu cuenta de Razorpay.

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 VibeFox Razorpay Payment más tarde en la lista de módulos y haz clic en Configure.

3. Pega 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 (consulta Clave de licencia).

4. Introduce tu Test Key ID y tu Test Key Secret, configura el webhook en el Razorpay Dashboard e introduce su secreto (consulta Configuración).

5. Activa Enable/Disable y haz clic en Save. Haz un pago de prueba con Test mode activado. Cuando estés listo, introduce las claves en vivo y desactiva Test mode.

Al instalar, el módulo crea dos estados de pedido: Razorpay payment authorized y Razorpay 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 Razorpay Payment > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, la página muestra avisos: faltan las claves del modo actual (en ese caso Razorpay no se muestra en la finalización de compra), el Key ID no empieza por rzp_test_ en modo de prueba o por rzp_live_ en modo en vivo, el modo de prueba está activado, el secreto del webhook está vacío, o la moneda predeterminada de la tienda no es INR y requiere International Payments en tu cuenta de Razorpay. Los espacios pegados con los Key ID se eliminan al guardar.

Razorpay

Enable/Disable: Enable Razorpay Payment Gateway 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. Es también el nombre del método de pago guardado en el pedido. Por defecto: UPI, Cards, NetBanking. Obligatorio: un título vacío da el error Enter a title for the payment method.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

Claves de API

Obtén tus claves en el Razorpay Dashboard, en Account & Settings > API Keys. Cambia el Dashboard al modo de prueba para generar claves de prueba (rzp_test_...). Las claves en vivo (rzp_live_...) están disponibles una vez activada tu cuenta.

Test mode: usa las claves del modo de prueba, así que no se cobra dinero real. Por defecto: activado. Desactívalo para aceptar pagos reales. Los pagos, las capturas y los reembolsos de un pedido siempre usan las claves del modo en que se pagó el pedido, así que cambiar el modo más tarde no afecta a los pedidos existentes.

Test Key ID: el Key ID del Razorpay Dashboard en modo de prueba. Empieza por rzp_test_.

Test Key Secret: el Key Secret del Razorpay Dashboard en modo de prueba.

Live Key ID: el Key ID del Razorpay Dashboard en modo en vivo. Empieza por rzp_live_.

Live Key Secret: el Key Secret del Razorpay Dashboard en modo en vivo.

Los secretos guardados 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.

Borrar secretos guardados: marca Test Key Secret, Live Key Secret o Webhook Secret y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Pago

Payment Action: cuándo se cobra el dinero. Por defecto: Authorize & Capture.

Webhook

El webhook confirma los pagos incluso cuando el cliente cierra el navegador justo después de pagar, y registra los reembolsos hechos en el Razorpay Dashboard. En el Razorpay Dashboard, ve a Account & Settings > Webhooks y añade un webhook en modo de prueba y otro en modo en vivo. Usa la URL que se muestra en Webhook URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_razorpay_payment/webhook, posiblemente con un código de idioma como /en/. Cópiala exactamente como aparece en los ajustes. Introduce en Razorpay un secreto de tu elección y selecciona estos eventos (también aparecen en esta sección):

Webhook Secret: el secreto que introdujiste al crear el webhook. Usa el mismo secreto para el webhook de prueba y el de vivo, porque el módulo tiene un único campo para ambos. Los webhooks sin una firma válida se rechazan. Sin el webhook, un pago se confirma solo cuando el cliente vuelve de la ventana emergente, o cuando el cliente inicia de nuevo el pago para el mismo carrito más adelante.

Avanzado

Enable Logging: el registro se escribe en logs/razorpay_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; esta opción añade los detalles de depuración. Las claves, las firmas y los datos de contacto del cliente nunca se registran. Por defecto: 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, las transacciones y los reembolsos de Razorpay y los estados de pedido del módulo siempre se conservan. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto UPI, Cards, NetBanking) y confirma. El módulo crea un pedido de Razorpay por el total exacto del carrito y la moneda, y abre la página Razorpay payment de tu tienda. La ventana emergente de Razorpay Checkout se abre allí automáticamente, con el nombre, el correo electrónico y el teléfono del cliente ya rellenados. El pago aparece en Razorpay como Cart y con el número del carrito. Todavía no existe ningún pedido de PrestaShop. Si se cierra la ventana emergente, el cliente puede hacer clic en Pay Now para abrirla de nuevo, o en Choose another payment method para volver a la finalización de compra. El carrito se conserva. En modo de prueba, la página muestra Razorpay Test mode: no real money will be charged.

Tras un pago correcto, el cliente ve Please wait while we process your payment... El módulo comprueba la firma de Razorpay, obtiene el pago de la API de Razorpay y compara el importe y la moneda con el carrito. El pedido se marca como pagado solo después de que Razorpay lo confirme. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. Si la firma es válida pero el pago no se puede obtener en ese momento, el pedido se crea en Razorpay payment on hold y el webhook lo confirma más tarde.

Si el cliente vuelve a iniciar el pago para el mismo carrito, el módulo reutiliza su pedido de Razorpay cuando no cambian el importe, la moneda ni el modo. Si ese pedido de Razorpay ya estaba pagado, por ejemplo porque el cliente cerró el navegador y no hay webhook, el módulo crea el pedido a partir de ese pago en lugar de pedir un segundo. Si cambió el total del carrito, se crea un nuevo pedido de Razorpay.

Mensajes que puede ver el cliente:

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

El módulo acepta solo pagos únicos. No admite suscripciones ni pagos recurrentes, tarjetas guardadas, Razorpay Magic Checkout, Payment Links ni Route (pagos divididos), ni widgets de ofertas o de asequibilidad.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente no ha pagado, o Razorpay todavía no ha confirmado el pago. Solo existe el carrito. Un intento de pago fallido no crea un pedido; el cliente puede volver a pagar.

Payment accepted: el pago se capturó y se confirmó. El pago se registra con el ID de pago de Razorpay (pay_...) como ID de transacción, y una nota muestra el ID del pago, el importe y cómo se confirmó (callback, webhook, sync o admin).

Razorpay payment authorized: el pago solo se autorizó (Authorize Only). Captúralo para completar el pedido.

Razorpay payment on hold: se establece en estos casos, cada uno con una nota: el importe o la moneda pagados no coinciden con el carrito (por ejemplo, el carrito se cambió después de iniciar el pago), el pago se capturó para un pedido cancelado, o el pago no se pudo verificar mediante la API de Razorpay en ese momento. El importe pagado en la moneda del pedido se registra en el pedido. Revisa el pedido y procésalo o reembolsa el pago.

Cancelled: un pago que llega después para un pedido cancelado no reabre el pedido automáticamente: un pago autorizado no se captura y solo recibe una nota, y un pago capturado pone el pedido en Razorpay payment on hold. Una notificación repetida del pago que ya pagó el pedido no cambia nada, aunque hayas cancelado el pedido después.

Refunded: el pago se reembolsó por completo.

Si llega un pago adicional para un pedido que ya está pagado, el pedido no cambia. Una nota pide que lo reembolses en el Razorpay Dashboard si no era intencionado. Un payment.failed tardío para un pedido pagado solo añade una nota.

Bloque de pago de Razorpay

La página del pedido muestra un bloque Razorpay payment con el ID del pago de Razorpay, el pedido de Razorpay, el estado del pago, Paid / refunded (el importe que Razorpay cobró y el importe reembolsado), una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Razorpay notes del pedido. La captura y los reembolsos requieren el permiso para editar pedidos; no hace falta acceso a la configuración del módulo.

Captura (Authorize Only)

Abre el pedido en Razorpay payment authorized, haz clic en Capture Razorpay payment en el bloque Razorpay y confirma. El pago se captura en el modo en que se autorizó, y el pedido pasa a Payment accepted. Si Razorpay lo rechaza, el bloque y las notas muestran Razorpay capture failed: con el motivo. Una captura hecha en el Razorpay Dashboard completa el pedido mediante el webhook.

Reembolsos

En el bloque de Razorpay, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Razorpay. Confirma la pregunta Refund this amount through Razorpay? This cannot be undone. Se admiten reembolsos totales y parciales. Los reembolsos se hacen por el importe y en la moneda que Razorpay cobró, así que, tras una diferencia de importe, puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. Un importe mayor muestra Invalid refund amount: at most seguido del importe. El reembolso se envía con las claves del modo en que se realizó el pago. Si Razorpay no acepta el reembolso, el bloque muestra Razorpay refund failed: con el motivo, y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID del reembolso de Razorpay, el importe y el estado. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez capturado el pago.

El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Razorpay.

Los reembolsos hechos en el Razorpay Dashboard llegan mediante el webhook y se registran una sola vez en el historial de reembolsos y en las notas. Cuando el pedido se reembolsa por completo, su estado pasa a Refunded. Un reembolso del Dashboard en otra moneda o mayor que el importe reembolsable no se registra automáticamente; una nota pide registrarlo manualmente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Razorpay Payment es el primer bloque de Modules > Module Manager > VibeFox Razorpay Payment > Configure, 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: presta-payment-razorpay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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 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 tras liberar un hueco 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 hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.

Sin una clave activa, Razorpay 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 queda oculto 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 las capturas 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

Razorpay no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga ambas claves: Test Key ID y Test Key Secret en modo de prueba, Live Key ID y Live Key Secret en modo en vivo. La página de ajustes muestra un aviso cuando faltan. 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 Razorpay Dashboard comprueba que el webhook exista en el modo que usas (Test o Live), que su URL sea exactamente la que se muestra en Webhook URL y que estén seleccionados los cinco eventos. Comprueba que Webhook Secret sea el mismo secreto que en Razorpay. El pedido también se crea cuando el cliente vuelve de la ventana emergente o inicia de nuevo el pago para el mismo carrito.

El webhook responde Webhook secret not configured: Webhook Secret está vacío. Introduce el secreto del webhook de Razorpay. Razorpay volverá a enviar el evento más tarde.

El webhook responde Invalid signature o Missing signature: el secreto de los ajustes es distinto del secreto del webhook de Razorpay. Introduce el mismo secreto en ambos lugares, para el webhook de prueba y el de vivo.

El webhook responde Retry later: el módulo no pudo confirmar una captura con la API de Razorpay, el pedido no se pudo crear (por ejemplo, el módulo está desactivado) o el carrito se estaba actualizando por otra solicitud en ese mismo momento. Razorpay vuelve a enviar el evento automáticamente. El motivo está en el Log.

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

Un pedido está en Razorpay payment on hold: lee las notas del bloque Razorpay. El importe o la moneda no coincidían con el carrito, el pago llegó para un pedido cancelado, o no se pudo verificar mediante la API de Razorpay en ese momento y está pendiente del webhook.

El cliente ve un error al pagar: consulta el campo Log en la página del módulo. Los errores se registran incluso con Enable Logging desactivado. Las claves incorrectas muestran el mensaje de que el método de pago no está disponible en este momento. Otros motivos de Razorpay se muestran después de Razorpay could not accept this payment:.

La ventana emergente no se abre: el script de Razorpay Checkout fue bloqueado por un bloqueador de contenido o por la conexión. El cliente ve un mensaje y puede recargar la página.

La captura o el reembolso falla con un mensaje sobre el modo: el pago se realizó en modo de prueba o en vivo, y las claves de ese modo no están configuradas. Introdúcelas e inténtalo de nuevo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Razorpay Payment 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 transacciones y los reembolsos de Razorpay y los estados de pedido Razorpay payment authorized y Razorpay payment on hold siempre se conservan, así que los pedidos pagados antes pueden seguir capturándose y reembolsándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago e ID de transacción.

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