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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

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

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

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

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

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

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет OpenCart 3 wcp_culqi_payment-oc3-(version).ocmod.zip і пакет OpenCart 4 wcp_culqi_payment.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_culqi_payment-oc3-(version).ocmod.zip. Розширення не містить модифікацій OCMOD, тому оновлювати Extensions > Modifications не потрібно. Замість інсталятора можна скопіювати вміст папки upload з цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Culqi Payment і натисніть Install (зелена кнопка +). Вашому адміністратору потрібне право змінювати список розширень оплати.

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань. Вставте ліцензійний ключ VibeFox у поле License key у блоці ліцензії у верхній частині сторінки і натисніть Activate (див. Ліцензійний ключ).

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

5. Увімкніть Enable/Disable і натисніть Save. Поки ви тестуєте, залишайте Test Mode увімкненим, а для прийому реальних платежів вимкніть його.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_culqi_payment.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Culqi Payment, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і ключі Culqi так само, як у кроках 3–5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Нове встановлення починає роботу з вимкненим способом оплати та увімкненим тестовим режимом.

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

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

Під час збереження неправильне значення не зберігається і лишається попереднім, а інші поля зберігаються. Сторінка показує помилку для кожного такого поля: ключ з неправильним префіксом (наприклад, Live Secret Key must start with sk_live_ — the previous value was kept.), порожній Title або довший за 128 символів, Sort Order, який не є цілим числом, Total, який не є числом 0 або більше, а також геозона чи статус замовлення, яких не існує.

Culqi

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

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

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

Sort Order: місце Culqi серед способів оплати на оформленні замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати Culqi лише для адрес оплати в обраній геозоні. За замовчуванням: All zones. Геозони налаштовуються в розділі System > Localisation > Geo Zones.

Total: сума замовлення у валюті магазину за замовчуванням, яку має досягти замовлення, перш ніж буде запропоновано Culqi. Залиште поле порожнім, щоб пропонувати Culqi за будь-якою сумою.

API-ключі

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

Test Mode: коли увімкнено, використовуються тестові ключі (pk_test_ / sk_test_), і реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі робочими ключами. Поки режим увімкнено, покупці на кроці Confirm Order бачать напис 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 the saved key on save під полем і натисніть Save.

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

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

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

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після того, як Culqi підтвердив списання. Кожне з полів нижче перелічує статуси замовлень вашого OpenCart.

Order Status After Payment: Culqi підтвердив списання, і його сума та валюта збігаються із замовленням. За замовчуванням: Processing.

On Hold (Review) Status: Culqi списав суму або валюту, які не збігаються із замовленням, або не захопив платіж. Примітка пояснює, що перевірити в CulqiPanel. За замовчуванням: Pending, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у розділі System > Localisation > Order Statuses і вибрати його тут.

Refunded Status: платіж повністю повернено зі сторінки замовлення. Часткові повернення лише додають примітку. За замовчуванням: Refunded.

Додатково

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

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

Delete data on uninstall: коли увімкнено, під час видалення розширення видаляються налаштування шлюзу та журнал. Списання й повернення Culqi завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. За замовчуванням: вимкнено.

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. Секретні ключі не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені секретні ключі зберігаються.

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit/Debit Card or Yape (Culqi)). На кроці Confirm Order покупець бачить ваш опис, і OpenCart створює замовлення, поки що без статусу. Коли покупець натискає Confirm Order, на тій самій сторінці відкривається спливаюче вікно Culqi Checkout із назвою вашого магазину, сумою замовлення та валютою. Там покупець вводить дані картки або платить через Yape. Скрипти Culqi завжди завантажуються з Culqi. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options, і натискає Confirm Order у блоці підтвердження внизу сторінки оформлення замовлення. Якщо магазин не запитує платіжну адресу (типова поведінка OpenCart 4), дані покупця, що передаються разом зі списанням, беруться з адреси доставки та імені покупця.

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

Якщо банк вимагає 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, нічого не списується, і кнопку Confirm Order можна натиснути знову. Кошик у всіх цих випадках зберігається.

Замовлення ніколи не списується двічі. Якщо покупець надсилає знову, поки триває оплата того самого замовлення, він бачить 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. Списання зберігається, а наступна спроба з тим самим кошиком встановлює статус замовлення на його основі без нового списання. Кошик оплачується лише один раз: якщо інше замовлення з того самого кошика (OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order) вже оплачене, покупець переходить на сторінку успіху і повторно не списується. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, тож після відхиленої картки покупець сплачує те саме замовлення.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успіху. Якщо магазин тим часом закрив це замовлення (наприклад, скасував або повернув кошти), або воно вже оплачене, а кошик відтоді змінився (інші товари або кількості), Confirm Order повертає покупця на оформлення, і для кошика створюється нове замовлення з власним платежем. Замовлення, яке було оплачене, а потім закрите, більше не утримує кошик.

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

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

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

No status (missing order): покупець ще не оплатив, картку відхилено або Culqi не відповів. У розділі Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders. Примітки в історії замовлення пояснюють невдалі спроби.

Order Status After Payment (default Processing): списання підтверджено і відповідає замовленню. Примітка показує Culqi payment successful з режимом (тестовий або робочий), 3-D Secure, якщо він використовувався, та ID списання Culqi (chr_...).

On Hold (Review) Status (default Pending): Culqi повідомив про списання, сума або валюта якого не збігаються із замовленням, або про платіж, який авторизовано, але не захоплено. Примітка пояснює це і показує ID списання. Перевірте списання в CulqiPanel, потім виконайте замовлення або поверніть платіж.

Refunded Status (default Refunded): платіж повністю повернено через розширення.

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox Culqi Payment

У розділі Sales > Orders відкрийте замовлення, оплачене через Culqi. Внизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Culqi Payment показує Charge ID з позначкою Test для тестових платежів, списану Amount (з 3-D Secure, якщо він використовувався), підказку Review для замовлень на перевірці, суми Paid / refunded, форму повернення, історію повернень і Culqi notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

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

На вкладці VibeFox Culqi Payment введіть Amount (підставляється сума, яку ще не повернуто), за бажанням Reason (optional), і натисніть Refund via Culqi. Підтвердіть запитання Refund this amount through Culqi? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право змінювати розширення (задається в розділі System > Users > User Groups). Повернення виконуються в тій сумі та валюті, які списав Culqi, тож після розбіжності суми можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається з ключами того режиму, у якому було здійснено оплату (тестового або робочого), навіть якщо ви з того часу змінили режим, тому секретний ключ цього режиму має бути вказаний. Якщо Culqi не приймає повернення, вкладка показує помилку, і повернення не фіксується. Успішне повернення додається до історії повернень і приміток із ID повернення Culqi, сумою та вашою причиною. Повне повернення переводить замовлення в Refunded Status без сповіщення покупця і без повернення товарів на склад, як і ручна зміна статусу. Часткове повернення статус не змінює.

Повернення товарів у розділі Sales > Returns не повертають гроші через Culqi. Повернення, зроблені в CulqiPanel, не синхронізуються з OpenCart. За потреби оновіть замовлення вручну.

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Culqi Payment — це перший блок у розділі Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен), а також кнопки Check now, щоб повторно перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розміщено рядок Product: opencart-payment-culqi і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис на vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify на розширення. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

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

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

Без активного ключа Culqi не показується покупцям на оформленні замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратор, що ввійшов в адмін-панель у тому самому браузері, усе ще бачить спосіб оплати в магазині, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати й протестувати розширення до купівлі ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тому без активного ключа спосіб оплати приховано для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard адмін-панелі з'явиться нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не зачіпаються: вже розпочаті платежі й далі підтверджуються, а повернення працюють.

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

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

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

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

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

Ключ не зберігається: помилка повідомляє, що поле має починатися з префікса, наприклад 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 payment method is not available.: у сесії оформлення більше немає замовлення Culqi, або спосіб оплати тим часом вимкнули. Покупець перезавантажує оформлення замовлення.

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

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

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

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox Culqi Payment. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень у розділі Orders, які під час повторного встановлення повертаються до значень за замовчуванням. Якщо Delete data on uninstall увімкнено, видаляються інші налаштування шлюзу (назва, опис, тестовий режим, ключі, Yape, логування) і журнал. Якщо вимкнено, вони зберігаються для подальшого повторного встановлення. Списання та повернення Culqi завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої платіжні примітки.

На OpenCart 4, щоб видалити також файли розширення, після видалення перейдіть до Extensions > Installer і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox Culqi Payment у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

Culqi є торговою маркою її власника. Це розширення не пов'язане з Culqi і не схвалене компанією Culqi.