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 в Klarna Merchant Portal містить номер кошика як референс мерчанта, оскільки замовлення 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 замовлення в Klarna і час захоплення.

Awaiting Klarna fraud review: покупка очікує перевірки на шахрайство в Klarna. Сповіщення від Klarna переводить замовлення в статус Payment accepted, Payment error або Canceled.

Klarna payment on hold: Klarna повернула неочікуваний статус перевірки, або сума чи валюта, повідомлені 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 увімкнено і заповнені облікові дані активного режиму: тестові ім'я користувача та пароль у тестовому режимі, робочі — у робочому. Сторінка налаштувань показує попередження, якщо їх немає. Країна виставлення рахунку покупця має бути країною Klarna у вашому 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 і не схвалений нею.