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

Вимоги

WordPress: 6.0 або новішої версії.

WooCommerce: 8.0 або новішої версії, встановлений і активний. Без WooCommerce плагін відмовляється активуватися.

PHP: 8.0 або новішої версії.

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

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити теку wcp_khipu_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Khipu > Manage або натисніть Settings під назвою плагіна на сторінці «Плагіни».

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

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

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

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

Усі налаштування на одній сторінці: WooCommerce > Settings > Payments > Khipu. Над полями сторінка попереджає, коли бракує Receiver ID, ключа API або секретного ключа (тоді Khipu не пропонується під час оформлення замовлення) і коли валюта магазину не підтримується. У списку способів оплати Khipu позначено як такий, що потребує налаштування, доки не введено всі три ключі.

Загальні

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

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

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

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

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

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

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

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

Повідомлення про платежі

Khipu підтверджує платежі, звертаючись до URL-адреси повідомлень, показаної в цьому розділі налаштувань. Вона має вигляд https://your-site/wc-api/webhook_wc_khipu/. Ця URL-адреса надсилається автоматично з кожним платежем, тому в обліковому записі Khipu нічого налаштовувати не потрібно, але вона має бути доступною з інтернету.

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

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

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

pending or verifying: переказ ще не завершено. Плагін відповідає «retry later», і Khipu надсилає повідомлення ще раз.

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

Processing: дозволяє WooCommerce вирішувати (за замовчуванням). Віртуальні замовлення з файлами, що завантажуються, автоматично завершуються.

Completed: кожне оплачене замовлення стає «Виконано».

Додатково

Debug log: Log API calls and notifications у WooCommerce > Status > Logs, джерело wcp_khipu_gateway. Помилки записуються завжди. Ключі та дані платника ніколи не записуються. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Дані замовлень (ідентифікатори платежів Khipu в замовленнях) зберігаються завжди. За замовчуванням: вимкнено.

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

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

Після оплати покупець повертається на сторінку отриманого замовлення у вашому магазині. Замовлення позначається як оплачене лише після того, як Khipu підтвердить переказ: підписаним повідомленням або запитом статусу до Khipu, коли покупець відкриває сторінку отриманого замовлення. Саме повернення ніколи не позначає замовлення як оплачене. Поки переказ не підтверджено, сторінка показує Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

Якщо покупець залишає сторінку Khipu, не заплативши, він потрапляє на сторінку Pay for order із повідомленням 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 спливає разом із часом Hold stock (minutes) у WooCommerce, тому покупець не може оплатити замовлення, яке вже скасовано.

Якщо 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. Подробиці записуються до журналу.

Спосіб оплати працює на класичній сторінці оформлення замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із високопродуктивним зберіганням замовлень (HPOS) WooCommerce.

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

Замовлення

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

Pending payment: покупця було направлено до Khipu, і він ще не оплатив, або Khipu ще не підтвердив переказ. У примітці до замовлення вказано ідентифікатор платежу Khipu.

Processing or Completed: Khipu підтвердив платіж. Статус відповідає налаштуванню Status after payment. У примітці до замовлення вказано ідентифікатор платежу Khipu, і ідентифікатор транзакції — це ідентифікатор платежу Khipu.

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

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

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

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі WooCommerce > Settings > Payments > Khipu. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія дійсна, і ваш домен. Використовуйте Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис на vibefox.net.

Один ключ працює на одному домені. Видалення ключа із сайту не звільняє його слот домену. Звільніть слот у своєму обліковому записі на vibefox.net.

Без активного ключа Khipu не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Менеджери магазину, які ввійшли в систему, все одно бачать цей спосіб оплати з позначкою (unlicensed — visible to admins only), тож ви можете налаштувати й перевірити плагін до придбання ключа. На сторінці «Плагіни» та на сторінках WooCommerce з’являється нагадування. Наявні замовлення не зачіпаються: уже розпочаті платежі все одно підтверджуються.

Коли ліцензія спливає, плагін продовжує працювати, але для оновлень і підтримки потрібне поновлення. Статус автоматично перевіряється знову у фоновому режимі.

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

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

Платіж пройшов, але замовлення залишається в статусі «Очікує оплати»: Khipu підтверджує переказ після того, як його перевірить банк. Замовлення оновлюється, коли надходить повідомлення від Khipu або коли покупець відкриває сторінку отриманого замовлення. Перевірте, що ваш сайт доступний з інтернету за URL-адресою повідомлень, показаною в налаштуваннях (без режиму обслуговування, базової автентифікації чи брандмауера, що блокує Khipu), і подивіться WooCommerce > Status > Logs, джерело wcp_khipu_gateway.

У відповідь на повідомлення надходить «Secret key not configured»: поле Secret key порожнє. Введіть його. Khipu надішле повідомлення ще раз.

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

У відповідь на повідомлення надходить «Payment does not belong to this order»: платіж було здійснено на інший Receiver ID або за іншим замовленням. Перевірте Receiver ID.

У відповідь на повідомлення надходить «Payment not final yet» або «Verification unavailable»: переказ ще перевіряється або до Khipu не вдалося звернутися. Khipu надішле повідомлення ще раз.

Замовлення в статусі «На утриманні»: прочитайте примітку до замовлення. Сума або валюта не збігалися із замовленням, або платіж надійшов після скасування замовлення.

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використано на іншому домені, звільніть слот у своєму обліковому записі на vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати з останнім відомим статусом.

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

Видалення

Під час деактивації плагіна всі дані зберігаються. Щоб видалити його, деактивуйте та видаліть його на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна видаляються завжди. Налаштування шлюзу та журнали видаляються, лише якщо було ввімкнено Delete data on uninstall. Інакше вони залишаються для повторного встановлення. Наявні замовлення зберігають свої примітки про платежі та ідентифікатори транзакцій.

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