VibeFox Khipu for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: чилійське песо (CLP), аргентинське песо (ARS) або перуанський соль (PEN). Для кошиків в інших валютах спосіб оплати приховується під час оформлення замовлення.

Обліковий запис Khipu: потрібні Receiver ID («Id de cobrador»), API key і Secret key вашого облікового запису для приймання платежів Khipu. Знайти їх можна в обліковому записі Khipu, у профілі продавця (khipu.com/merchant/profile). Усі три обов'язкові: без Secret key жоден платіж не можна підтвердити. В обліковому записі Khipu нічого налаштовувати не потрібно.

Доступний магазин: Khipu підтверджує платежі, звертаючись до вашого магазину, тому URL сповіщень має бути доступним з інтернету, без захисту паролем і без файрвола, що блокує Khipu. Режим обслуговування магазину цьому не заважає.

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

Встановлення

1. На панелі адміністратора перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Khipu Gateway у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у поле License key блоку ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

4. Введіть Receiver ID, API key і Secret key вашого облікового запису для приймання платежів Khipu (див. Налаштування).

5. Увімкніть Enable / Disable і натисніть Save. Щоб спочатку протестувати, використайте ключі тестового облікового запису розробника Khipu, а потім замініть їх ключами вашого робочого облікового запису.

Під час встановлення модуль створює статус замовлення Khipu payment on hold. PrestaShop за замовчуванням вмикає новий платіжний модуль для всіх валют, країн і груп клієнтів. Обмежити їх можна в Payment > Preferences.

Налаштування

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Khipu Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо немає Receiver ID, API key або Secret key (тоді Khipu не пропонується під час оформлення замовлення), і якщо типова валюта магазину не підтримується Khipu.

Khipu

Enable / Disable: Enable Khipu payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку клієнти бачать під час оформлення замовлення. Вона також зберігається як назва способу оплати в замовленні. За замовчуванням: Khipu. Обов'язкове поле.

Description: текст під способом оплати під час оформлення замовлення. За замовчуванням: Pay by bank transfer with Khipu.

Обліковий запис Khipu

Скопіюйте Receiver ID, API key і Secret key з вашого облікового запису для приймання платежів Khipu (khipu.com/merchant/profile). Окремого тестового сервера в Khipu немає, а перемикача тестового режиму в модулі немає. Для тестування використовуйте ключі облікового запису для приймання платежів розробника («desarrollo»): оплата проходить через тестовий банк DemoBank, і реальні гроші не переказуються. Перейдіть на ключі робочого облікового запису для приймання платежів, коли почнете приймати справжні оплати.

Receiver ID: ваш ідентифікатор отримувача («cobrador») в Khipu. Платежі з інших облікових записів Khipu відхиляються.

API key: використовується для створення платежів і для перевірки кожного платежу в Khipu.

Secret key: використовується для перевірки підпису (HMAC-SHA256) сповіщень про платежі Khipu. Без нього жоден платіж не можна підтвердити.

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

Clear saved secrets: позначте API key або Secret key і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Сповіщення про платежі

Notification URL: Khipu підтверджує платежі, звертаючись за URL, який показано тут. З увімкненими «зручними» URL він має такий вигляд: https://your-shop/module/wcp_khipu_gateway/webhook, можливо, з кодом мови. URL автоматично передається з кожним платежем, тож в обліковому записі Khipu нічого налаштовувати не потрібно, але URL має бути доступним з інтернету.

Кожне сповіщення має містити дійсний підпис, створений з вашим Secret key. Сповіщення без дійсного підпису відхиляються. Модуль ніколи не довіряє вмісту сповіщення: він запитує в Khipu статус платежу і діє відповідно до того, що повідомляє Khipu:

done: переказ підтверджено. Замовлення створюється після перевірок Receiver ID, кошика і суми.

done, reversed: платіж було скасовано. Для неоплаченого кошика замовлення не створюється. Оплачене замовлення отримує примітку, його статус не змінюється.

pending or verifying: переказ ще не остаточний. Модуль відповідає «retry later», і Khipu надсилає сповіщення повторно.

Status after payment: статус замовлення після того, як Khipu підтвердить платіж. Статус встановлюється одразу, однією зміною.

Processing: замовлення отримує Payment accepted (за замовчуванням).

Completed: замовлення отримує Delivered.

Додатково

Debug log: записує виклики API і сповіщення у файл logs/wc_khp_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки записуються завжди, навіть коли перемикач вимкнено. Ключі та дані платника ніколи не записуються. За замовчуванням: вимкнено.

Log: показує розмір журналу та його останні записи. Натисніть Clear log, щоб очистити журнал.

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування шлюзу та журнал. Дані замовлень (ідентифікатори платежів Khipu для замовлень) завжди зберігаються. За замовчуванням: вимкнено.

Оформлення замовлення

На етапі оплати клієнт обирає спосіб оплати (за замовчуванням Khipu) з його описом і підтверджує замовлення. Модуль створює платіж Khipu на суму кошика у валюті кошика та надсилає клієнта на сторінку оплати Khipu. У Khipu платіж відображається як Order # з номером кошика і назвою магазину, а також зі списком товарів. Електронна адреса клієнта передається в Khipu, якщо вона дійсна. На сторінці Khipu клієнт сплачує банківським переказом зі свого банку. На цьому етапі замовлення ще не існує.

Після оплати клієнт повертається до вашого магазину. Замовлення позначається як оплачене лише після підтвердження Khipu: за підписаним сповіщенням або за запитом статусу до Khipu, коли клієнт повертається. Саме повернення ніколи нічого не позначає як оплачене. Коли замовлення створено, клієнт бачить стандартну сторінку підтвердження замовлення. Якщо банк ще перевіряє переказ або Khipu недоступний, з'являється сторінка Payment confirmation з текстом Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. і кнопками Check again та Back to checkout. Якщо останній платіж Khipu за кошиком не вдається пов'язати з ним (наприклад, він належить іншому Receiver ID), клієнт повертається до оформлення замовлення з повідомленням We could not match this payment to an order. If you paid, please contact us.

Якщо клієнт залишає сторінку Khipu без оплати або платіж не було завершено, він повертається до оформлення замовлення з повідомленням The Khipu payment was not completed. You can try again or choose another payment method. Кошик зберігається. Нова спроба видаляє попередній неоплачений платіж Khipu, тож за старим посиланням уже не можна сплатити. Якщо Khipu вже отримав попередній платіж, замовлення створюється і новий платіж не виконується. Якщо попередній переказ ще перевіряється, клієнт бачить Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

Якщо Khipu не може створити платіж, клієнт залишається на етапі оформлення замовлення з коротким повідомленням, наприклад Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. або Khipu is temporarily unavailable. Please try again in a few minutes. Деталі записуються в журнал.

Сповіщення працюють, поки магазин у режимі обслуговування, і не блокуються обмеженням за країною для вашого магазину.

Модуль приймає лише разові платежі банківським переказом. Повернення коштів із PrestaShop до Khipu не надсилаються, а підписок, збережених способів оплати та попередніх авторизацій модуль не має. Неоплачені платежі не пов'язані з резервуванням запасів.

Замовлення

Статуси замовлення

No order yet: клієнта було перенаправлено до Khipu, і він не сплатив, або Khipu ще не підтвердив переказ. Існує лише кошик.

Payment accepted or Delivered: Khipu підтвердив платіж. Статус відповідає Status after payment. Платіж записується з ідентифікатором платежу Khipu як ID транзакції, а примітка показує Khipu payment verified. Payment ID: з ідентифікатором платежу та сумою.

Khipu payment on hold: Khipu підтвердив платіж, сума або валюта якого не відповідає замовленню (наприклад, кошик було змінено після початку оплати), або платіж надійшов після скасування замовлення. Фактично отримана сума записується в замовлення (не тоді, коли валюта інша), і примітка пояснює це. Перевірте платіж в обліковому записі Khipu, а потім завершіть замовлення або поверніть кошти клієнту. Якщо для того самого кошика надійде пізніший платіж правильної суми, замовлення переходить у статус оплаченого.

Якщо надходить платіж за замовленням, яке вже оплачено або закрито після оплати, замовлення не змінюється. Примітка просить повернути кошти клієнту, якщо це другий платіж. Якщо Khipu повідомляє, що оплачений платіж скасовано, замовлення отримує примітку, а його статус не змінюється.

Блок оплати Khipu

Сторінка замовлення показує блок Khipu payment зі спробами оплати Khipu за кошиком замовлення (дата, сума, ідентифікатор платежу Khipu, статус і результат Khipu), попередження Manual review, поки замовлення має статус Khipu payment on hold, і Khipu notes замовлення. Блок доступний лише для читання.

Повернення коштів

Повернення коштів із PrestaShop до Khipu не надсилаються, оскільки Khipu не пропонує повернення через свій API. Поверніть кошти клієнту з вашого облікового запису Khipu або банківським переказом, а потім вручну зафіксуйте повернення в PrestaShop.

Ліцензійний ключ

Модуль працює з ліцензійним ключем VibeFox із vibefox.net. Блок ліцензії License — VibeFox Khipu Gateway розташований першим на сторінці Modules > Module Manager > VibeFox Khipu Gateway > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ з цього магазину. Нижче розташовані рядок Product: presta-payment-khipu і посилання 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.

Без активного ключа Khipu не показується клієнтам під час оформлення замовлення. Якщо все ж розпочато платіж, клієнт бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в адмін-панель, тому спосіб оплати приховано й для вас: ви можете налаштувати модуль до купівлі ключа, але не можете протестувати його на оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, і далі підтверджуються.

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

Усунення несправностей

Khipu не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено і заповнено Receiver ID, API key та Secret key. Валюта кошика має бути CLP, ARS або PEN. Сторінка налаштувань показує попередження, якщо чогось бракує. У Payment > Preferences перевірте, чи дозволено модуль для валюти кошика, країни клієнта та групи клієнта.

Платіж пройшов, але замовлення не створено: Khipu підтверджує переказ після того, як банк його перевірив. Замовлення створюється, коли надходить сповіщення Khipu або коли клієнт натискає Check again. Перевірте, що ваш магазин доступний з інтернету за URL, показаним у Notification URL (без захисту паролем і без файрвола, що блокує Khipu), і подивіться поле Log на сторінці модуля.

Сповіщення відповідає Secret key not configured: Secret key порожній. Введіть його. Khipu надішле сповіщення повторно.

Сповіщення відповідає Invalid signature, Missing signature або Malformed signature: Secret key не належить обліковому запису для приймання платежів, ключі якого ви використовуєте, або запит надійшов не від Khipu.

Сповіщення відповідає Order not found або Payment does not belong to this order: платіж було зроблено на інший Receiver ID або для іншого кошика. Перевірте Receiver ID.

Сповіщення відповідає Payment not final yet або Verification unavailable: переказ ще перевіряється, або Khipu не вдалося зв'язатися. Khipu надішле сповіщення повторно.

Сповіщення відповідає Busy, retry later або Order could not be created, retry later: замовлення в цей момент підтверджувалося іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Khipu надішле сповіщення повторно. Причина є в журналі.

Замовлення має статус Khipu payment on hold: прочитайте примітки в блоці Khipu payment. Сума або валюта не відповідали замовленню, або платіж надійшов після скасування замовлення.

Клієнт бачить «Khipu payments are not available right now»: API key відсутній або невірний. Перевірте ключі в обліковому записі Khipu.

Якщо ваш обліковий запис Khipu приймає іншу валюту, наприклад EUR для Khipu Spain, розробники можуть додати її за допомогою хука actionWcpKhipuSupportedCurrencies.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Khipu Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування шлюзу та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Спроби оплати Khipu і статус замовлення Khipu payment on hold завжди зберігаються. Наявні замовлення зберігають свої примітки про оплату та ідентифікатори транзакцій.

Khipu є торговельною маркою свого власника. Цей модуль не пов'язаний із Khipu і не схвалений Khipu.