VibeFox Klarna 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 comerciante de Klarna: necesitas las credenciales de API (nombre de usuario y contraseña) de tu cuenta de comerciante de Klarna para una región de API, y las credenciales de prueba del portal del entorno de pruebas de Klarna (ver Configuración). Cada región de API tiene sus propias credenciales. Solo se puede usar una cuenta de comerciante (una región de API) por tienda.
Moneda: una moneda de Klarna de tu región: EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF o RON en Europa; USD, CAD o MXN en Norteamérica; AUD o NZD en Oceanía.
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 Klarna Payments 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. Elige la API region de tu cuenta de comerciante de Klarna.
5. Introduce el nombre de usuario y la contraseña de prueba del portal del entorno de pruebas de Klarna, deja activado Test mode, activa Enable/Disable, haz clic en Save y realiza un pedido de prueba.
6. Introduce el nombre de usuario y la contraseña reales del Klarna Merchant Portal, desactiva Test mode y elige cuándo se capturan los pedidos (por defecto: cuando el pedido se envía).
Al instalarse, el módulo crea dos estados de pedido: Awaiting Klarna fraud review y Klarna payment on hold. Ninguno de ellos cuenta como pagado ni envía un correo electrónico. 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 Klarna Payments > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra TEST MODE: Klarna playground, no real payments. o LIVE: real Klarna payments. Avisa cuando falta el nombre de usuario o la contraseña del modo activo (en ese caso Klarna no aparece en la finalización de compra) y cuando la moneda predeterminada de la tienda no la vende Klarna en la región de API seleccionada.
Klarna Payments
Enable/Disable: Enable Klarna Payments activa o desactiva el método de pago. Por defecto: 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. Por defecto: Klarna. Obligatorio.
Description: el texto que se muestra al cliente encima del widget de Klarna. Por defecto: Pay now, later or in instalments with Klarna.
Credenciales de API
Las credenciales de API de Klarna (nombre de usuario y contraseña) se crean en el Klarna Merchant Portal (portal.klarna.com) en Settings > Klarna API credentials. Las credenciales de prueba se obtienen del portal del entorno de pruebas: playground.eu.portal.klarna.com para Europa, y playground.us.portal.klarna.com para Norteamérica y Oceanía.
Test mode: usa el entorno de pruebas de Klarna (credenciales de prueba, sin pagos reales). Por defecto: activado. Mientras el modo de prueba está activo, el cliente ve TEST MODE: Klarna playground, no real payment is made. debajo del método de pago. Los pedidos conservan el entorno en el que se realizaron: las capturas y los reembolsos de los pedidos del entorno de pruebas siempre usan las credenciales de prueba.
API region: la región de tu cuenta de comerciante de Klarna. Los clientes solo pueden pagar con Klarna desde los países de esta región, en la moneda de su país. El país se toma de la dirección de facturación del carrito.
Live username (UID): el nombre de usuario de la API de producción, por ejemplo PK12345_abcdef012345.
Live password: la contraseña de la API de producción (secreto compartido).
Test username (UID): el nombre de usuario de la API del entorno de pruebas.
Test password: la contraseña de la API del entorno de pruebas (secreto compartido).
Las contraseñas guardadas 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 cambiarla.
Clear saved passwords: marca una contraseña y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Gestión de pedidos
Un pedido de Klarna realizado es una autorización: el cliente solo se cobra cuando el pedido se captura. Las autorizaciones no capturadas caducan, normalmente a los 28 días, así que envía los pedidos a tiempo o usa la captura automática.
Capture: cuándo se cobra al cliente. Los reembolsos solo son posibles por importes capturados.
Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. Por defecto: activado.
Notificaciones
Klarna informa del resultado de la revisión antifraude (pedidos registrados como "pending") a la dirección que aparece en Notification URL. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_klarna_payment/notification, posiblemente con un código de idioma como /en/. La URL se envía automáticamente con cada pedido, así que no hay nada que configurar en Klarna. No se confía nunca en el contenido de la notificación: cada notificación se verifica con la Klarna Order Management API, con las credenciales del entorno y la región en los que se realizó el pedido, y el pedido de Klarna debe referirse al carrito de esta tienda. El módulo actúa según lo que informa Klarna:
Si Klarna acepta una compra después de que cancelaste o reembolsaste el pedido, el pedido no se reabre y la autorización de Klarna se libera. La notificación funciona mientras la tienda está en modo de mantenimiento y no se bloquea por la restricción de países de tu tienda.
Avanzado
Debug log: registra las llamadas a la API y los eventos de pago en logs/wc_kl_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran. El registro nunca contiene credenciales, tokens de autorización ni datos de clientes. Por defecto: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro, con un botón para borrarlo.
Uninstall: elimina la configuración del módulo y el registro al desinstalar el módulo. Los datos de los pedidos (ID de pedidos de Klarna, reembolsos) 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 Klarna, con el distintivo de Klarna) y el widget de Klarna se carga dentro del paso de pago. El módulo crea la sesión de Klarna a partir del carrito en el servidor. En el widget, el cliente elige pagar ahora, pagar después o a plazos, según lo que ofrezca Klarna. Cuando el cliente realiza el pedido, la sesión de Klarna se actualiza primero con el carrito final, y Klarna autoriza la compra en el widget. Después, el módulo crea el pedido de Klarna desde el servidor con las líneas de pedido, los totales y las direcciones del carrito. Los descuentos del carrito se envían a Klarna como una línea aparte. No existe ningún pedido hasta que Klarna responde.
El resultado depende del estado de antifraude de Klarna:
Si Klarna no puede aceptar el pedido, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo Klarna could not accept this order. Please check your billing details or choose another payment method., Klarna did not respond. Please try again in a moment. o, cuando la autorización ha caducado, una indicación para volver a hacer clic en "Place order". Los detalles se escriben en el registro. Si el país y la moneda de facturación del cliente no corresponden a un mercado de Klarna de tu región, el cliente ve Klarna is not available for your billing country and currency. Please choose another payment method.
Hacer doble clic nunca crea un segundo pedido de Klarna para el mismo carrito. Si el carrito cambia mientras Klarna responde, por ejemplo en otra pestaña del navegador, el pedido se crea como Klarna payment on hold con una nota. Si Klarna aprobó la compra pero no se pudo crear el pedido, el cliente ve Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. El siguiente intento o la notificación de Klarna crea el pedido a partir del pedido de Klarna guardado, sin una nueva autorización.
El pedido de Klarna en el Klarna Merchant Portal lleva el número de carrito como referencia del comerciante, porque el pedido de PrestaShop todavía no existe cuando se realiza.
El módulo no incluye Klarna Checkout (KCO, sustitución completa de la finalización de compra), botones de Klarna Express Checkout, On-site messaging ni Sign in with Klarna, ni suscripciones ni métodos de pago guardados, ni capturas parciales por línea de pedido. Las líneas de pedido no se vuelven a enviar a Klarna cuando editas un pedido después de realizado.
Pedidos y reembolsos
Order statuses
No order yet: el cliente no ha completado la autorización de Klarna, o Klarna rechazó la compra. Solo existe el carrito.
Payment accepted: Klarna aceptó la compra. El pago se registra con el ID del pedido de Klarna como ID de transacción, y una nota privada muestra el ID del pedido de Klarna y cuándo se capturará.
Awaiting Klarna fraud review: la compra está pendiente de la revisión antifraude de Klarna. La notificación de Klarna cambia el pedido a Payment accepted, Payment error o Canceled.
Klarna payment on hold: Klarna devolvió un estado antifraude inesperado, o el importe o la moneda que informó Klarna no coinciden con el pedido. La nota lo explica. Revisa el pedido en el Klarna Merchant Portal.
Payment error: Klarna rechazó o detuvo la compra tras la revisión antifraude. No envíes el pedido.
Canceled: cancelaste el pedido, o Klarna informa de que el pedido de Klarna está cancelado, caducado o cerrado. Con Cancellation activado, al cancelar un pedido aún no capturado se cancela también el pedido de Klarna y se libera la autorización, de modo que el cliente no es cobrado. Un pedido que ya está capturado no se cancela en Klarna: reembólsalo para devolver el dinero.
Refunded: el importe capturado se reembolsó por completo a través del módulo.
Capture
Con When the order is shipped, al cambiar el pedido a un estado de envío se captura el total del pedido antes de guardar el nuevo estado. Si Klarna rechaza la captura, por ejemplo porque el total del pedido superó el importe autorizado tras editarlo, el estado no cambia, no se envía ningún correo y el motivo se muestra en la página del pedido y en una nota: el cliente NO ha sido cobrado. Corrige el problema y cambia el estado de nuevo para reintentarlo, o captura en el Klarna Merchant Portal y cambia Capture a manual. En PrestaShop 8 en modo producción, el back office puede guardar el estado de todos modos; en ese caso el módulo establece Klarna payment on hold en su lugar, con una nota, para que el pedido nunca aparezca como enviado sin la captura. Una captura correcta añade una nota con el importe capturado y el ID de la captura.
Bloque Klarna payment
La página del pedido muestra un bloque Klarna payment con el ID del pedido de Klarna, su entorno y su región, una insignia Playground en los pedidos de prueba, el estado de antifraude y el estado de Klarna, el importe autorizado, los importes capturado y reembolsado, y el historial de reembolsos.
Reembolsos
En el bloque Klarna payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Klarna. Confirma la pregunta Refund this amount through Klarna? This cannot be undone. Se admiten reembolsos totales y parciales de los importes capturados, hasta lo que Klarna informe como capturado menos lo ya reembolsado. Necesitas el permiso para editar pedidos; no hace falta acceso a los módulos. El reembolso se envía al entorno y a la región en los que se realizó el pedido, por lo que deben estar configuradas las credenciales de ese entorno. Si Klarna 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 ID de reembolso de Klarna. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Un reembolso reintentado nunca se realiza dos veces.
Un pedido que aún no se ha capturado no se puede reembolsar: en su lugar, cancélalo para liberar la autorización. Con Capture en manual, la tienda no sabe qué has capturado en el Klarna Merchant Portal. El formulario de reembolso se muestra entonces con el importe vacío, y Klarna comprueba el importe cuando lo envías.
El módulo no crea facturas rectificativas. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Klarna. Los reembolsos hechos en el Klarna Merchant Portal no se añaden al bloque, pero sí cuentan para el importe que Klarna todavía permite reembolsar.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Klarna Payments es el primer bloque de Modules > Module Manager > VibeFox Klarna Payments > 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-klarna 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, Klarna no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, 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: las notificaciones de Klarna se siguen procesando, y los pedidos pueden seguir capturándose, cancelándose y reembolsándose.
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 se necesita ninguna tarea cron. Desinstalar o restablecer el módulo siempre elimina la clave de licencia y el estado de la licencia.
Solución de problemas
Klarna no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que las credenciales del modo activo estén rellenadas: nombre de usuario y contraseña de prueba en modo de prueba, y los reales en modo real. La página de configuración muestra un aviso cuando faltan. El país de facturación del cliente debe ser un país de Klarna de tu API region, y debe pagar en la moneda de ese país (por ejemplo, un cliente de Suecia debe pagar en SEK). En Payment > Preferences, comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo de clientes.
El pago se ha realizado, pero el pedido sigue en Awaiting Klarna fraud review: la compra está pendiente de la revisión antifraude de Klarna, y el pedido se actualiza cuando llega la notificación de Klarna. Comprueba que tu tienda puede recibir peticiones de Klarna en la Notification URL que aparece en la configuración, y que las credenciales del entorno en el que se realizó el pedido siguen introducidas. Activa Debug log y revisa el campo Log en la página del módulo.
La notificación responde Not configured: faltan las credenciales del entorno (prueba o real) en el que se realizó el pedido, así que la notificación no se puede verificar. Introdúcelas. Klarna volverá a intentar la notificación.
La notificación responde Verification failed: no se pudo leer el pedido de Klarna desde la Order Management API. Klarna volverá a intentar la notificación.
La notificación responde Busy: otra petición estaba actualizando el pedido en ese mismo momento. Klarna volverá a intentar la notificación.
La notificación responde mismatch_ref o Unknown order: el pedido de Klarna no se refiere al carrito de esta tienda, o el módulo no lo conoce. El pedido no se modifica.
El widget no se carga: el cliente ve Klarna could not be loaded. Please try again or choose another payment method. o Klarna is not available for this purchase. Comprueba las credenciales del modo activo y el país y la moneda del cliente.
El cambio de estado a Shipped es rechazado: la captura de Klarna falló. Lee el motivo en el bloque Klarna payment o en la nota. Es posible que el total del pedido necesite más de lo que aún está autorizado, que el pedido de Klarna todavía no esté aceptado, o que la autorización haya caducado. Corrígelo y cambia el estado de nuevo, o captura en el Klarna Merchant Portal.
El reembolso falla: lee el mensaje del bloque. Es posible que el pedido todavía no esté capturado (en ese caso, cancélalo), que el importe supere lo que aún se puede reembolsar, o que falten las credenciales del entorno del pedido.
El cliente ve This order is already being paid: hay otra petición en curso para el mismo carrito, por ejemplo un doble clic. Espera un momento y comprueba si el pedido se creó.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Klarna Payments y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Uninstall está activado en la sección Advanced, se eliminan la configuración del módulo, el registro y las sesiones temporales del widget. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Los pedidos y reembolsos de Klarna y los estados de pedido Awaiting Klarna fraud review y Klarna payment on hold siempre se conservan, así que los pedidos realizados antes se pueden capturar y reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago e ID de transacción.
Klarna es una marca comercial de su respectivo titular. Este módulo no está afiliado a Klarna ni cuenta con su aprobación.