VibeFox Klarna for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более ранних версиях PHP.

Учётная запись мерчанта Klarna: нужны учётные данные API (имя пользователя и пароль) вашей учётной записи мерчанта Klarna для одного региона API, а также тестовые учётные данные из портала тестовой среды Klarna (см. Настройка). У каждого региона API свои учётные данные. На один магазин можно использовать только одну учётную запись мерчанта (один регион API).

Валюта: валюта Klarna вашего региона: EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF или RON в Европе; USD, CAD или MXN в Северной Америке; AUD или NZD в Океании.

Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В админ-панели перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По завершении загрузки нажмите Configure или позже найдите VibeFox Klarna Payments в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Выберите API region вашей учётной записи мерчанта Klarna.

5. Введите тестовые имя пользователя и пароль из портала тестовой среды Klarna, оставьте включённым Test mode, включите Enable/Disable, нажмите Save и оформите тестовый заказ.

6. Введите рабочие имя пользователя и пароль из Klarna Merchant Portal, выключите Test mode и выберите, когда списывать средства по заказам (по умолчанию: при отгрузке).

При установке модуль создаёт два статуса заказа: Awaiting Klarna fraud review и Klarna payment on hold. Ни один из них не считается оплаченным и не отправляет письмо. PrestaShop предлагает новый платёжный модуль для всех валют, стран и групп клиентов. Ограничить его можно в разделе Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Klarna Payments > Configure. Каждый раздел имеет собственную кнопку Save, которая сохраняет всю страницу. Над полями страница показывает TEST MODE: Klarna playground, no real payments. или LIVE: real Klarna payments. Она предупреждает, если не заполнены имя пользователя или пароль активного режима (тогда Klarna скрывается на шаге оплаты), и если валюта магазина по умолчанию не продаётся Klarna в выбранном регионе API.

Klarna Payments

Enable/Disable: Enable Klarna Payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель на шаге оплаты. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Klarna. Обязательное поле.

Description: текст, который показывается покупателю над виджетом Klarna. По умолчанию: Pay now, later or in instalments with Klarna.

Учётные данные API

Учётные данные API Klarna (имя пользователя и пароль) создаются в Klarna Merchant Portal (portal.klarna.com) в разделе Settings > Klarna API credentials. Тестовые учётные данные выдаются на портале тестовой среды: playground.eu.portal.klarna.com для Европы, playground.us.portal.klarna.com для Северной Америки и Океании.

Test mode: использует тестовую среду Klarna (тестовые учётные данные, без реальных платежей). По умолчанию: включено. Пока тестовый режим включён, покупатель видит под способом оплаты надпись TEST MODE: Klarna playground, no real payment is made. Заказы сохраняют среду, в которой были оформлены: списания и возвраты по заказам тестовой среды всегда используют тестовые учётные данные.

API region: регион вашей учётной записи мерчанта Klarna. Покупатели могут платить через Klarna только из стран этого региона, в валюте своей страны. Страна берётся из адреса выставления счёта в корзине.

Europe: Австрия, Бельгия, Финляндия, Франция, Германия, Греция, Ирландия, Италия, Нидерланды, Португалия, Словакия и Испания (EUR), Швеция (SEK), Норвегия (NOK), Дания (DKK), Великобритания (GBP), Швейцария (CHF), Польша (PLN), Чехия (CZK), Венгрия (HUF), Румыния (RON). По умолчанию.

North America (US, CA, MX): США (USD), Канада (CAD), Мексика (MXN).

Oceania (AU, NZ): Австралия (AUD), Новая Зеландия (NZD).

Live username (UID): имя пользователя рабочего API, например PK12345_abcdef012345.

Live password: пароль рабочего API (общий секрет).

Test username (UID): имя пользователя API тестовой среды.

Test password: пароль API тестовой среды (общий секрет).

Сохранённые пароли больше не показываются. Поле остаётся пустым и содержит Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved passwords: отметьте пароль и нажмите Save, чтобы удалить его. Пустое поле сохраняет уже записанное значение.

Управление заказами

Оформленный заказ Klarna является авторизацией: покупатель списывается только тогда, когда заказ захвачен (списан). Неподтверждённые авторизации истекают, обычно через 28 дней, поэтому отправляйте заказы вовремя или используйте автоматическое списание.

Capture: момент списания средств с покупателя. Возвраты возможны только для списанных сумм.

When the order is shipped (recommended): списание при переводе заказа в статус отгрузки, например Shipped или Delivered (по умолчанию). Списываемая сумма — итог заказа за вычетом уже списанного, но не больше суммы, которая ещё авторизована. Если списание не удалось, статус не меняется, а причина показывается на странице заказа.

Immediately (auto capture): списание сразу после оформления, для цифровых товаров или услуг.

Manually in the Klarna portal: модуль не списывает средства. Выполните списание заказа в Klarna Merchant Portal.

Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. По умолчанию: включено.

Уведомления

Klarna сообщает результат проверки на мошенничество (заказы, оформленные как «pending») на адрес, указанный в Notification URL. При понятных URL он выглядит так: https://your-shop/module/wcp_klarna_payment/notification, возможно с кодом языка, например /en/. URL автоматически передаётся с каждым заказом, поэтому в Klarna ничего настраивать не нужно. Содержимому уведомления никогда не доверяют: каждое уведомление проверяется через Klarna Order Management API с учётными данными той среды и региона, в которых был оформлен заказ, и заказ Klarna должен относиться к корзине этого магазина. Модуль действует в соответствии с тем, что сообщает Klarna:

ACCEPTED: Klarna одобрила покупку. После проверки суммы и валюты заказ помечается как оплаченный.

REJECTED or STOPPED: покупка не прошла проверку на мошенничество. Заказ переходит в статус Payment error.

Klarna order CANCELLED, EXPIRED or CLOSED: покупатель не был списан. Заказ отменяется.

Если Klarna одобрит покупку после того, как вы отменили или вернули заказ, заказ не будет открыт заново, а авторизация Klarna будет снята. Уведомления работают, пока магазин находится в режиме обслуживания, и не блокируются ограничением по странам вашего магазина.

Дополнительно

Debug log: записывает вызовы API и платёжные события в файл logs/wc_kl_debug.log.php в папке модуля. Файл не открывается из браузера. Ошибки записываются всегда. Журнал никогда не содержит учётных данных, токенов авторизации или данных покупателей. По умолчанию: выключено.

Log: показывает размер журнала и его последние записи, а также кнопку для очистки.

Uninstall: при удалении модуля удаляет его настройки и журнал. Данные заказов (ID заказов Klarna, возвраты) всегда сохраняются. По умолчанию: выключено.

Оформление заказа

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Klarna, с логотипом Klarna), и виджет Klarna загружается внутри шага оплаты. Модуль создаёт сессию Klarna на сервере из корзины. В виджете покупатель выбирает оплату сразу, оплату позже или рассрочку — в зависимости от того, что предлагает Klarna. Когда покупатель оформляет заказ, сессия Klarna сначала обновляется итоговой корзиной, и Klarna подтверждает покупку в виджете. Затем модуль создаёт заказ Klarna на сервере с позициями, суммами и адресами корзины. Скидки корзины передаются в Klarna отдельной строкой. Заказа не существует до ответа Klarna.

Результат зависит от статуса проверки на мошенничество Klarna:

ACCEPTED: заказ создаётся со статусом Payment accepted, и покупатель видит стандартную страницу подтверждения заказа. Сумма авторизована и списывается согласно настройке Capture.

PENDING: заказ создаётся со статусом Awaiting Klarna fraud review до получения уведомления от Klarna. До этого момента не отправляйте его.

REJECTED: заказ не создаётся. Покупатель остаётся на оформлении с сообщением Klarna could not approve this purchase. Please choose another payment method.

Если Klarna не может принять заказ, покупатель остаётся на оформлении с коротким сообщением, например 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. или, если авторизация истекла, с просьбой нажать «Place order» ещё раз. Подробности записываются в журнал. Если страна и валюта покупателя не соответствуют ни одному рынку Klarna вашего региона, покупатель видит Klarna is not available for your billing country and currency. Please choose another payment method.

Двойной клик никогда не создаёт второй заказ Klarna для той же корзины. Если корзина меняется, пока Klarna отвечает, например в другой вкладке браузера, заказ создаётся со статусом Klarna payment on hold и примечанием. Если Klarna одобрила покупку, но заказ не удалось создать, покупатель видит Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. Следующая попытка или уведомление Klarna создаст заказ из сохранённого заказа Klarna без новой авторизации.

В Klarna Merchant Portal заказ Klarna содержит номер корзины в качестве референса мерчанта, потому что на момент оформления заказа в PrestaShop ещё не существует.

В модуле нет Klarna Checkout (KCO, полная замена оформления заказа), кнопок Klarna Express Checkout, On-site messaging или Sign in with Klarna, подписок или сохранённых способов оплаты, а также частичного списания по позициям заказа. Позиции заказа повторно не отправляются в Klarna, когда вы редактируете заказ после оформления.

Заказы и возвраты

Order statuses

No order yet: покупатель не завершил авторизацию Klarna или Klarna отклонила покупку. Существует только корзина.

Payment accepted: Klarna одобрила покупку. Платёж записывается с ID заказа Klarna в качестве ID транзакции, а приватное примечание показывает ID заказа Klarna и время списания.

Awaiting Klarna fraud review: покупка ожидает проверки на мошенничество Klarna. Уведомление Klarna переводит заказ в статус Payment accepted, Payment error или Canceled.

Klarna payment on hold: Klarna вернула неожиданный статус проверки или сообщила сумму или валюту, которые не совпадают с заказом. Примечание объясняет причину. Проверьте заказ в Klarna Merchant Portal.

Payment error: Klarna отклонила или остановила покупку после проверки на мошенничество. Не отправляйте заказ.

Canceled: вы отменили заказ или Klarna сообщает, что заказ Klarna отменён, истёк или закрыт. При включённой настройке Cancellation отмена заказа, по которому ещё не выполнено списание, отменяет и заказ Klarna и снимает авторизацию, поэтому покупатель не списывается. Заказ, по которому уже выполнено списание, в Klarna не отменяется: оформите возврат, чтобы вернуть деньги.

Refunded: списанная сумма полностью возвращена через модуль.

Capture

При When the order is shipped перевод заказа в статус отгрузки списывает сумму заказа до сохранения нового статуса. Если Klarna отказывает в списании, например потому что после редактирования сумма заказа превысила авторизованную, статус не меняется, письмо не отправляется, а причина показывается на странице заказа и в примечании: покупатель НЕ списан. Устраните проблему и измените статус снова, чтобы повторить попытку, или выполните списание в Klarna Merchant Portal и переключите Capture на ручной режим. В PrestaShop 8 в производственном режиме бэк-офис может всё равно сохранить статус; тогда модуль вместо этого устанавливает Klarna payment on hold с примечанием, чтобы заказ никогда не отображался как отгруженный без списания. Успешное списание добавляет примечание с суммой и ID списания.

Блок Klarna payment

На странице заказа показан блок Klarna payment с ID заказа Klarna, его средой и регионом, значком Playground для тестовых заказов, статусом проверки и статусом Klarna, авторизованной суммой, списанной и возвращённой суммами и историей возвратов.

Возвраты

В блоке Klarna payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Klarna. Подтвердите вопрос Refund this amount through Klarna? This cannot be undone. Полные и частичные возвраты поддерживаются для списанных сумм, в пределах того, что Klarna сообщает как списанное, за вычетом уже возвращённого. Нужно право на редактирование заказов; доступ к модулям не требуется. Возврат отправляется в ту среду и регион, в которых был оформлен заказ, поэтому должны быть заполнены учётные данные этой среды. Если Klarna не принимает возврат, блок показывает ошибку, и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания с ID возврата Klarna. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет. Повторно запущенный возврат никогда не выполняется дважды.

Заказ, по которому ещё не выполнено списание, нельзя вернуть: вместо этого отмените его, чтобы снять авторизацию. Если Capture установлен в ручной режим, магазин не знает, что вы списали в Klarna Merchant Portal. Тогда форма возврата показывается с пустой суммой, и Klarna проверяет сумму при отправке.

Модуль не создаёт кредитовых счетов. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Klarna. Возвраты, оформленные в Klarna Merchant Portal, в блоке не отображаются, но учитываются в сумме, которую Klarna ещё разрешает вернуть.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox Klarna Payments — первый блок на странице Modules > Module Manager > VibeFox Klarna Payments > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус повторно, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-klarna и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку админ-панели (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения места для домена в вашей учётной записи нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: на домене основного магазина, в том числе при мультимагазинной конфигурации. Удаление ключа из магазина не освобождает место для домена. Освободите место в своей учётной записи vibefox.net.

Без активного ключа Klarna не показывается покупателям на шаге оплаты. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в админ-панель, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на шаге оплаты нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уведомления Klarna по-прежнему обрабатываются, а заказы можно списывать, отменять и возвращать.

Когда срок лицензии истекает, модуль продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется снова во время работы в админ-панели: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Klarna не появляется на шаге оплаты: проверьте, что лицензия активна, Enable/Disable включено и заполнены учётные данные активного режима: тестовые имя пользователя и пароль в тестовом режиме, рабочие — в рабочем. Страница настроек показывает предупреждение, если они не заполнены. Страна выставления счёта покупателя должна входить в регион API region, и покупатель должен платить в валюте этой страны (например, покупатель из Швеции должен платить в SEK). В разделе Payment > Preferences проверьте, разрешён ли модуль для валюты корзины, страны покупателя и группы клиентов.

Платёж прошёл, но заказ остаётся в статусе Awaiting Klarna fraud review: покупка ожидает проверки на мошенничество Klarna, и заказ обновится, когда придёт уведомление Klarna. Проверьте, что ваш магазин может принимать запросы Klarna по Notification URL, указанному в настройках, и что учётные данные среды, в которой был оформлен заказ, всё ещё заполнены. Включите Debug log и посмотрите поле Log на странице модуля.

Уведомление отвечает Not configured: не заполнены учётные данные среды (тестовой или рабочей), в которой оформлен заказ, поэтому уведомление невозможно проверить. Введите их. Klarna повторит уведомление.

Уведомление отвечает Verification failed: заказ Klarna не удалось прочитать через Order Management API. Klarna повторит уведомление.

Уведомление отвечает Busy: заказ в это же время обновлял другой запрос. Klarna повторит уведомление.

Уведомление отвечает mismatch_ref или Unknown order: заказ Klarna не относится к корзине этого магазина, или модуль его не знает. Заказ не изменяется.

Виджет не загружается: покупатель видит Klarna could not be loaded. Please try again or choose another payment method. или Klarna is not available for this purchase. Проверьте учётные данные активного режима, а также страну и валюту покупателя.

Переход в статус Shipped отклоняется: списание Klarna не удалось. Причину смотрите в блоке Klarna payment или в примечании. Возможно, сумма заказа превышает то, что ещё авторизовано, заказ Klarna ещё не принят, или авторизация истекла. Исправьте проблему и измените статус снова или выполните списание в Klarna Merchant Portal.

Возврат не проходит: прочитайте сообщение в блоке. Возможно, заказ ещё не списан (тогда отмените его), сумма превышает то, что ещё можно вернуть, или не заполнены учётные данные среды заказа.

Покупатель видит This order is already being paid: выполняется другой запрос для той же корзины, например двойной клик. Подождите немного и проверьте, создан ли заказ.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Klarna Payments и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Uninstall включено в разделе Advanced, настройки модуля, журнал и временные сессии виджета удаляются. Если выключено, все настройки сохраняются для последующей повторной установки. Заказы и возвраты Klarna, а также статусы заказов Awaiting Klarna fraud review и Klarna payment on hold всегда сохраняются, поэтому заказы, оформленные до удаления, можно списать и вернуть после повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Klarna является товарным знаком его владельца. Этот модуль не связан с Klarna и не одобрен компанией Klarna.