VibeFox Kushki for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.

Moneda: USD (Ecuador) o COP (Colombia). En los carritos con otras monedas, el método de pago se oculta en la finalización de compra.

HTTPS: Kushki exige que la finalización de compra se sirva por HTTPS en modo real.

Cuenta de Kushki: necesitas los IDs de comerciante públicos y privados de tu cuenta de prueba (UAT) de Kushki y de tu cuenta de producción. Están en la consola de Kushki, en Developers > Credentials. Para el webhook opcional también necesitas la clave de firma del webhook de cada cuenta (consulta Configuración).

VibeFox license key: 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 adelante VibeFox Kushki Payment 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 (consulta Clave de licencia).

4. Introduce los IDs de comerciante públicos y privados de prueba y deja activado Test mode. Opcionalmente, configura el webhook en la consola de Kushki y pega su clave de firma (consulta Configuración).

5. Activa Enable / Disable, haz clic en Save y realiza un pedido de prueba. Cuando esté listo, introduce los IDs de comerciante reales (y la firma del webhook real) y desactiva Test mode.

Al instalarse, el módulo crea el estado de pedido Kushki payment on hold. PrestaShop asigna el nuevo módulo de pago a las monedas, países y grupos de clientes de tu tienda. En Payment > Preferences comprueba que el módulo está permitido para USD o COP y para Ecuador o Colombia.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Kushki Payment > 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 el método de pago está activado pero faltan los IDs de comerciante del modo actual (en ese caso el método de pago se oculta en la finalización de compra), cuando la moneda predeterminada de tu tienda no es USD ni COP, cuando se usa el modo real sin HTTPS y cuando el modo actual no tiene clave de firma del webhook. Mientras el modo de prueba esté activado, muestra Modo de prueba activado: se usa el entorno de pruebas de Kushki y no se cobra dinero real. Si guardas con el método de pago activado pero sin los IDs de comerciante del modo actual, los ajustes se guardan y un mensaje te recuerda que los introduzcas. Los espacios alrededor de los IDs se eliminan al guardar.

Kushki

Enable / Disable: Enable Kushki card payments 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 que se guarda en el pedido. Predeterminado: Credit / debit card (Kushki). Obligatorio.

Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Predeterminado: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

Credenciales de API

Copia los IDs de comerciante públicos y privados de la consola de Kushki (Developers > Credentials). Las cuentas de prueba (UAT) y de producción tienen IDs distintos. El modo de prueba usa solo los IDs de prueba; el modo real, solo los IDs reales.

Test mode: usa el entorno de prueba (UAT) de Kushki: los IDs de comerciante de prueba, el formulario de tarjeta de prueba y la API de prueba juntos. No se cobra dinero real y en la finalización de compra se muestra una insignia TEST MODE. Predeterminado: activado. Desactívalo para aceptar pagos reales. Los reembolsos siempre se envían al entorno en que se hizo el pago.

Test Public Merchant ID: el ID de comerciante público de tu cuenta de prueba de Kushki. Con él se carga el formulario de tarjeta.

Test Private Merchant ID: el ID de comerciante privado de tu cuenta de prueba de Kushki. Se usa en el servidor para los cobros y los reembolsos.

Live Public Merchant ID: el ID de comerciante público de tu cuenta de producción de Kushki.

Live Private Merchant ID: el ID de comerciante privado de tu cuenta de producción de Kushki. Mantenlo en secreto.

Los IDs de comerciante privados y las firmas de webhook guardados no se vuelven a mostrar. El campo queda vacío y muestra Guardado: deja el campo vacío para conservarlo. Escribe un valor nuevo solo si quieres cambiarlo.

Webhook (recomendado)

Los pagos se confirman de inmediato con la respuesta de la API de Kushki, así que el webhook no es obligatorio. Además, crea el pedido de un pago cuya respuesta se perdió (por ejemplo, por un tiempo de espera agotado) e informa de las anulaciones y los reembolsos hechos en la consola de Kushki. En la consola de Kushki (Webhooks) añade la URL que se muestra en Webhook URL para los pagos con tarjeta. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_kushki_payment/webhook, posiblemente con un código de idioma como /es/. Copia la URL exactamente como la muestran los ajustes. Hazlo para la cuenta de prueba y para la cuenta de producción.

El módulo procesa estas notificaciones de tarjeta:

Test webhook signature: la clave de firma del webhook de la cuenta de prueba de Kushki (Console > Webhooks).

Live webhook signature: la clave de firma del webhook de la cuenta de producción de Kushki.

Clear saved secrets: marca un ID de comerciante privado o una firma de webhook y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.

Los webhooks sin firma válida se rechazan. Una notificación debe estar firmada con la clave del modo en que se hizo el pago, así que una notificación de prueba nunca confirma un pago real. Sin clave de firma, se rechazan todas las notificaciones de webhook, pero los pagos siguen funcionando, porque se confirman con la respuesta de la API.

Avanzado

Debug log: escribe las solicitudes y los webhooks de Kushki en logs/kushki_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran. Los registros nunca contienen IDs de comerciante, tokens de tarjeta ni correos electrónicos de clientes. 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 y los registros. Los registros de pagos de Kushki (cobros y reembolsos) y el estado de pedido Kushki payment on hold siempre se conservan, para que los pedidos antiguos puedan reembolsarse después de una reinstalación. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (de forma predeterminada, Credit / debit card (Kushki)). Debajo aparece el formulario de tarjeta de Kushki, con el total del carrito en la moneda del carrito. El cliente introduce la tarjeta, elige las cuotas si el formulario de Kushki las ofrece y pulsa el botón de pago dentro del formulario de Kushki.

El botón Place order de PrestaShop sigue visible, porque incluye las condiciones del servicio. Si las condiciones ya están aceptadas, el pago se envía automáticamente después del botón de pago de Kushki. Si no, el cliente ve Tu tarjeta ha sido aceptada por Kushki. Acepta las condiciones del servicio y pulsa "Place order" para pagar. Si el cliente pulsa Place order sin usar el formulario de Kushki, se muestra el mensaje Introduce los datos de tu tarjeta en el formulario de Kushki y pulsa su botón de pago.

Después, tu tienda cobra la tarjeta en el servidor. El pedido se marca como pagado solo cuando Kushki lo confirma con un número de ticket. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Tu pago con tarjeta ha sido recibido. Si Kushki informa de un importe o una moneda aprobados, se comparan con el carrito. Un pedido en espera muestra Tu pago está en revisión. Actualizaremos tu pedido en cuanto termine la revisión.

Si la tarjeta es rechazada, no se crea ningún pedido y el cliente vuelve al paso de pago con Tu pago ha sido rechazado y el motivo indicado por Kushki, y puede probar con otra tarjeta. En caso de problemas de red, de claves o del servidor, el cliente ve El pago no se puede procesar en este momento. Vuelve a intentarlo en unos minutos o elige otro método de pago. El motivo técnico se escribe en el registro. Si se hace un segundo clic mientras se procesa un pago, se muestra Ya se está procesando un pago para este pedido. Espera un momento y comprueba el estado de tu pedido.

Si se pierde la respuesta de Kushki (por ejemplo, por un tiempo de espera agotado), el cliente ve el mensaje general, pero el intento de cobro se conserva. Cuando el webhook firmado informa del cobro aprobado, se crea el pedido. Un carrito que ya tiene un pedido, o un cobro aprobado cuyo pedido aún no se ha creado, nunca se vuelve a cobrar: el cliente ve la confirmación de ese pedido. Si el cliente vuelve a pagar antes de que llegue cualquier webhook, es un cobro nuevo; una aprobación tardía del primer cobro solo añade entonces una nota sobre un posible cobro duplicado.

El webhook funciona aunque la tienda esté en modo de mantenimiento y no lo bloquea la restricción por país de tu tienda. El 3-D Secure, las reglas antifraude y las cuotas ofrecidas se configuran en la consola de Kushki.

El módulo admite solo pagos con tarjeta de un solo paso. No tiene reembolsos parciales, tarjetas guardadas ni suscripciones, ni pagos en efectivo, por transferencia bancaria (PSE) o con tarjeta de débito por redirección, ni autorización y captura por separado.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente no ha pagado, la tarjeta fue rechazada o se perdió la respuesta de Kushki y el webhook todavía no ha llegado. Solo existe el carrito.

Payment accepted: Kushki ha confirmado el cobro (con la respuesta de la API o con el webhook). El pago se registra con la referencia de transacción de Kushki (o el número de ticket) como ID de transacción. Una nota muestra el modo, el número de ticket de Kushki y la referencia.

Kushki payment on hold: Kushki devolvió un éxito sin número de ticket, informó de un importe o una moneda distintos a los del carrito, o el carrito se modificó durante el pago. La nota lo explica. Comprueba la transacción en la consola de Kushki y tramita el pedido o reembolsa el pago. Una aprobación firmada posterior, con número de ticket e importe coincidente, pone el pedido en Payment accepted.

Payment error: el webhook informó de que se rechazó el cobro de un pedido en espera.

Refunded: el pago se reembolsó a través del módulo.

Si Kushki informa de otro cobro aprobado para un pedido que ya está pagado, cancelado o reembolsado, el pedido no cambia. Una nota te pide que compruebes si hay un cobro duplicado y que lo reembolses en la consola de Kushki. Un webhook del entorno de prueba para un pago real (o al revés) se ignora y queda anotado.

Bloque de pago de Kushki

La página del pedido muestra un bloque Kushki payment con el número de ticket, la referencia de transacción, el entorno (con una insignia Test para los pagos de prueba), el estado del cobro, el importe cobrado y el total del pedido, el formulario de reembolso, el historial de reembolsos y las Kushki notes del pedido.

Reembolsos

Kushki reembolsa el cobro completo, así que solo son posibles los reembolsos totales. En el bloque Kushki payment se rellena el importe que cobró Kushki. Opcionalmente, introduce un motivo y haz clic en Refund via Kushki, y luego confirma la pregunta ¿Reembolsar el pago completo a través de Kushki? Esta acción no se puede deshacer. Necesitas el permiso para editar pedidos. Para cualquier otro importe, el módulo muestra Kushki reembolsa solo el pago completo. Introduce el importe total cobrado junto con el importe, y no se envía nada. El reembolso se hace por el importe y en la moneda que cobró Kushki, así que si hubo una diferencia de importe, el cliente recibe lo que realmente se cobró, no el total del pedido. Un pago se puede reembolsar una sola vez.

El reembolso se envía en el modo en que se hizo el pago (prueba o real), así que debe estar configurado el ID de comerciante privado de ese modo. Si Kushki no acepta el reembolso, el bloque muestra Error en el reembolso de Kushki con el código y el mensaje de Kushki, y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el ticket de reembolso de Kushki, y el pedido pasa a Refunded. Los reembolsos requieren un cobro de Kushki confirmado con número de ticket.

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 Kushki. Las anulaciones y los reembolsos hechos en la consola de Kushki llegan por el webhook y se añaden a las notas. El estado del pedido no cambia automáticamente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Kushki Payment es el primer bloque de Modules > Module Manager > VibeFox Kushki 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-kushki 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 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 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. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Kushki 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 necesitan 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 se necesita 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

Kushki no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable / Disable está activado y que el modo actual tiene ambos IDs de comerciante: los IDs de prueba en modo de prueba, los IDs reales en modo real. Comprueba que la moneda del carrito es USD o COP. 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. La página de ajustes muestra una advertencia cuando faltan los IDs.

El pago se completó, pero no se creó ningún pedido: se perdió la respuesta de la API de Kushki, por ejemplo por un tiempo de espera agotado. El webhook crea el pedido para estos pagos. En la consola de Kushki comprueba que la URL del webhook es exactamente la que aparece en Webhook URL, para la cuenta del modo que usas, y que la clave de firma de esa cuenta está en el campo correspondiente (Test webhook signature o Live webhook signature). Un cobro aprobado sin importe y moneda pagados crea el pedido en Kushki payment on hold.

Webhook answers Webhook signature not configured: no está configurada ninguna de las dos firmas de webhook. Pega la clave de firma en los ajustes.

Webhook answers Invalid signature: la clave de firma pertenece a otra cuenta o modo, o la notificación se modificó durante el envío.

Webhook answers Order mismatch: la notificación no corresponde a un cobro de este carrito (clave de intento o transacción incorrecta). No se cambia nada.

Webhook answers Busy, retry later: el pedido estaba siendo procesado por otra solicitud en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Kushki puede volver a enviar la notificación. Los errores siempre se escriben en el registro.

La URL del webhook muestra POST solo en el navegador: es normal. La URL acepta solo notificaciones de Kushki.

El formulario de tarjeta no se carga: el cliente ve No se ha podido cargar el formulario de tarjeta de Kushki. Recarga la página o elige otro método de pago. Comprueba el ID de comerciante público del modo actual.

El cliente ve Esta opción de pago no está disponible en esta tienda. Paga con tarjeta.: en el formulario de Kushki se eligió una opción de pago que no es con tarjeta. El módulo solo cobra tarjetas.

El cliente ve un error al pagar: activa Debug log y revisa el campo Log en la página del módulo. Un ID de comerciante privado incorrecto o que falta da el mensaje general de que el pago no se pudo procesar.

El cliente ve Tu pago se ha recibido, pero el pedido no se pudo completar automáticamente: Kushki aprobó el cobro, pero PrestaShop no pudo crear el pedido. El registro muestra el motivo. El siguiente intento de pago del mismo carrito crea el pedido sin un nuevo cobro.

El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o real, y no está configurado el ID de comerciante privado de ese modo. Introdúcelo y vuelve a intentarlo.

No se ofrece el reembolso y aparece el mensaje No se ha encontrado ningún número de ticket de Kushki para este pedido: el pedido no tiene un cobro de Kushki confirmado. Reembólsalo en la consola de Kushki.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Kushki 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 y los registros. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos de Kushki (cobros y reembolsos) y el estado de pedido Kushki payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de una reinstalación. Los pedidos existentes conservan sus notas de pago, números de ticket de Kushki e IDs de transacción.

Kushki es una marca comercial de su respectivo titular. Este módulo no está afiliado a Kushki ni cuenta con su aprobación.