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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта магазину: перуанський соль (PEN) або долар США (USD). Culqi не приймає інших валют, а спосіб оплати показується лише для кошиків у PEN або USD.

Обліковий запис Culqi: вам потрібні публічний і секретний ключі вашого облікового запису Culqi. Ключі інтеграції (тестові) беруться на integ-panel.culqi.com, робочі (live) ключі — на mipanel.culqi.com, у розділі CulqiPanel > Desarrollo > API Keys. Публічний ключ використовується спливним вікном Culqi в браузері. Секретний ключ використовується лише на вашому сервері і ніколи не надсилається в браузер. Вебхук не потрібен.

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

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

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

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

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

4. Вставте ключі інтеграції та, для реальних платежів, робочі ключі (див. розділ «Налаштування»).

5. Увімкніть Enable/Disable і натисніть Save. Тримайте Test Mode увімкненим під час тестування, потім вимкніть його, щоб приймати реальні платежі.

6. Переконайтеся, що PEN або USD є активною валютою вашого магазину.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Culqi Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Test mode is active: the integration keys are used and no real money is charged., поки тестовий режим увімкнено. Вона попереджає, коли шлюз увімкнено, але ключів поточного режиму немає, і коли жодна валюта магазину не підтримується Culqi. В обох випадках спосіб оплати приховується на етапі оформлення замовлення. Якщо валюта за замовчуванням не PEN і не USD, сторінка повідомляє, що Culqi пропонується лише для кошиків у підтримуваних валютах.

Culqi

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

Title: назва способу оплати, яку бачать покупці під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Credit/Debit Card or Yape (Culqi). Обов'язкове поле.

Description: текст під способом оплати на сторінці оформлення замовлення. За замовчуванням: Pay securely with your credit/debit card or Yape via Culqi.

API-ключі

Скопіюйте ключі з CulqiPanel > Desarrollo > API Keys: ключі інтеграції (тестові) — на integ-panel.culqi.com, робочі — на mipanel.culqi.com. Тестовий режим використовує лише тестові ключі, робочий — лише робочі. Кожен ключ має починатися з префікса свого поля. Ключ з неправильним префіксом не зберігається: сторінка показує помилку, наприклад Live Secret Key must start with sk_live_ — the previous value was kept., а інші поля зберігаються.

Test Mode: коли увімкнено, використовуються тестові ключі (pk_test_ / sk_test_) і реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі робочими ключами. Поки режим увімкнено, покупці бачать під способом оплати TEST MODE: No real charges will be made.

Test Public Key: публічний ключ інтеграційного середовища. Починається з pk_test_.

Test Secret Key: секретний ключ інтеграційного середовища. Починається з sk_test_ і ніколи не передається в браузер.

Live Public Key: публічний ключ робочого середовища. Починається з pk_live_.

Live Secret Key: секретний ключ робочого середовища. Починається з sk_live_ і ніколи не передається в браузер.

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

Clear saved secret keys: позначте Test Secret Key або Live Secret Key і натисніть Save, щоб видалити ключ. Порожнє поле зберігає збережене значення.

Способи оплати

Картки пропонуються завжди. Банківський переказ, агенти, гаманці та Cuotéalo потребують Culqi Orders API, і цей модуль їх не пропонує.

Yape: Offer Yape in the Culqi popup показує Yape поруч із картками у вікні Culqi. За замовчуванням: увімкнено.

Додатково

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

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

Delete Data on Uninstall: коли увімкнено, під час видалення модуля видаляються налаштування шлюзу, записи про списання та повернення Culqi цього модуля і журнал. Статус замовлення та дані Culqi в замовленнях (платежі, примітки) завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit/Debit Card or Yape (Culqi)) і натискає кнопку оформлення замовлення. Спливне вікно Culqi Checkout відкривається на тій самій сторінці з назвою вашого магазину, сумою кошика та валютою. Там покупець вводить дані картки або платить через Yape. Скрипти Culqi завантажуються лише на сторінці оформлення замовлення.

Culqi перетворює платіжні дані на одноразовий токен, який надсилається у ваш магазин. Ваш сервер створює списання через Culqi Charges API на суму кошика у валюті кошика, з миттєвим списанням. Списання відображається в CulqiPanel як Cart і номер кошика, з e-mail покупця. До цього моменту замовлення не існує. Замовлення позначається оплаченим лише після підтвердження Culqi: замовлення створюється, коли Culqi відповідає про успішне списання, і покупець бачить стандартну сторінку підтвердження замовлення.

Якщо банк вимагає 3-D Secure, покупець бачить Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Після автентифікації списання автоматично надсилається повторно. Якщо перевірку не завершено, покупець бачить The 3-D Secure verification was not completed. Please try again or use another card.

Якщо картку відхилено, покупець бачить повідомлення від Culqi, наприклад Payment failed: і причину, і може спробувати іншу картку. Якщо Culqi не відповідає, покупець бачить We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Якщо покупець закриває вікно Culqi, нічого не списується, і він бачить The payment window was closed before the payment was completed. Оформити замовлення він може знову. Кошик у всіх цих випадках зберігається. Невдалі спроби записуються в журнал модуля, оскільки замовлення ще не існує.

З одного кошика кошти ніколи не списуються двічі. Якщо покупець надсилає форму повторно, поки триває оплата цього самого кошика, він бачить This order is already being paid. Please wait a moment and check your email before trying again. Якщо Culqi списав кошти, але замовлення створити не вдалося, покупець бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Списання зберігається, і наступна спроба створює замовлення на його основі без повторного списання.

Модуль приймає лише разові платежі карткою та через Yape, з миттєвим списанням. У ньому немає кодів PagoEfectivo чи CIP, банківського застосунку, агентів, гаманців і Cuotéalo, немає збережених карток, підписок і платежів частинами, немає вебхуків Culqi та немає окремої авторизації та захоплення.

Замовлення та повернення

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

No order yet: картку відхилено, покупець закрив вікно Culqi або Culqi не відповів. Існує лише кошик. Подробиці є в журналі модуля.

Payment accepted: списання підтверджено і відповідає кошику. Платіж записується з ID списання Culqi (chr_...) як ID транзакції, а примітка показує режим (тестовий або робочий) і те, чи використовувався 3-D Secure.

Culqi payment on hold: Culqi повідомив про списання, сума або валюта якого не відповідає кошику, або про платіж, який авторизовано, але не захоплено. Примітка пояснює це і показує ID списання. Списання, захоплене у валюті кошика, записується як платіж на фактично списану суму. Перевірте списання в CulqiPanel, потім виконайте замовлення або поверніть платіж.

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

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

Блок Culqi payment

На сторінці замовлення є блок Culqi payment з ID списання, списаною сумою (з 3-D Secure, якщо він використовувався), міткою Test для тестових платежів, підказкою щодо перевірки для замовлень на утриманні, сумами оплати та повернень, а також історією повернень.

Повернення

У блоці Culqi payment введіть суму (підставляється сума, яку ще не повернено), за бажанням причину, і натисніть Refund via Culqi. Підтвердіть питання Refund this amount through Culqi? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право редагувати замовлення; доступ до модулів не потрібен. Повернення здійснюються у сумі та валюті, які списав Culqi, тож після розбіжності суми ви можете повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається з ключами того режиму, в якому було здійснено платіж (тестовий або робочий), навіть якщо ви з того часу змінили режим, тож секретний ключ цього режиму має бути заданий. Якщо Culqi не приймає повернення, блок показує помилку і повернення не записується. Успішне повернення додається до історії повернень і приміток замовлення разом з ID повернення Culqi, сумою та вашою причиною. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитні накладні. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Culqi. Повернення, зроблені в CulqiPanel, не синхронізуються з PrestaShop. За потреби оновіть замовлення вручну.

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

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

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

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

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

Culqi не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, заповнені обидва ключі поточного режиму (Test Public Key і Test Secret Key у тестовому режимі, Live Public Key і Live Secret Key у робочому) і валюта кошика — PEN або USD. Сторінка налаштувань показує попередження, якщо ключів бракує. У Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: модуль не використовує вебхуки. Списання підтверджується лише відповіддю Culqi вашому серверу. Якщо Culqi не відповів вчасно, у журналі модуля буде Culqi did not confirm the charge з номером кошика. Знайдіть списання за цим cart_id у CulqiPanel. Якщо покупець бачив повідомлення, що замовлення не вдалося оформити, наступна спроба оплати того самого кошика створить замовлення без повторного списання.

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

Ключ не зберігається: помилка каже, що поле має починатися з префікса, наприклад sk_live_. Кожне поле приймає лише ключі свого типу і режиму: pk_test_, sk_test_, pk_live_ або sk_live_.

Покупець бачить Payment gateway misconfiguration. Please contact the store owner.: ключів поточного режиму немає, або Culqi відхилив секретний ключ. Перевірте ключі в налаштуваннях.

Покупець бачить Payment token is invalid. Please try again.: токен із вікна Culqi належить до іншого режиму, наприклад після перемикання Test Mode, коли сторінка оформлення замовлення була відкрита. Покупець має перезавантажити сторінку і оплатити знову.

Вікно Culqi не відкривається: покупець бачить The Culqi payment window could not be loaded. Please reload the page and try again. Перевірте, що скрипти з js.culqi.com і 3ds.culqi.com не блокуються на сторінці оформлення замовлення, наприклад кеш- або оптимізаційним модулем.

Покупець бачить Security check failed. Please reload the page and try again.: сторінка оформлення замовлення була відкрита занадто довго або в іншій сесії. Перезавантаження сторінки виправляє це.

Покупець бачить This order is already being paid: у той самий момент виконувався інший запит на оплату того самого кошика. Покупцеві слід почекати і перевірити e-mail, перш ніж пробувати знову.

Картку відхилено, і потрібна причина: перегляньте поле Log на сторінці модуля. Відмови записуються з кодом відмови Culqi, навіть коли Debug log вимкнено.

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

Видалення

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

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