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

Вимоги

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

PHP: 8.0 або новіша.

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

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

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

Після нового встановлення спосіб оплати вимкнено.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit. Розділи перелічені ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо відсутні Receiver ID, API key або secret key (тоді Khipu не пропонується на оформленні), і якщо валюта магазину за замовчуванням не підтримується Khipu (тоді Khipu пропонується лише тоді, коли покупець платить у CLP, ARS або PEN). Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

При збереженні Title не може бути порожнім або довшим за 128 символів, Sort Order має бути цілим числом, Total — числом 0 або більше, а географічна зона та статуси замовлень мають існувати. Інакше нічого не зберігається, і сторінка називає поле. Відсутні ключі не заважають збереженню.

Khipu

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

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

Description: текст, який показується покупцю на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Оплата банківським переказом через Khipu.

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

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

Total: сума оформлення в валюті магазину за замовчуванням, яку має досягти замовлення, перш ніж буде запропоновано Khipu. Залиште порожнім, щоб пропонувати 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 the saved value під полем і натисніть Save.

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

Notification URL: Khipu підтверджує платежі, викликаючи показану тут URL. На OpenCart 3 вона має вигляд https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook, на OpenCart 4 — https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook. Вона формується з адреси вітрини вашої інсталяції OpenCart. URL автоматично передається з кожним платежем, тому в обліковому записі Khipu нічого налаштовувати не потрібно, але URL має бути доступний з інтернету.

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

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

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

Paid Order Status: статус після підтвердженого платежу, коли Status after payment — Processing. За замовчуванням: Обробляється.

Complete Order Status: статус після підтвердженого платежу, коли Status after payment — Completed. За замовчуванням: Виконано.

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

Додатково

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

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

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

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Khipu). На кроці Confirm Order покупець бачить ваш опис над кнопкою підтвердження. OpenCart створює замовлення на цьому кроці, ще без статусу. Коли покупець натискає Confirm Order, розширення створює платіж Khipu на суму замовлення у валюті замовлення і надсилає покупця на сторінку оплати Khipu. У Khipu платіж відображається як Order # з номером замовлення та назвою магазину, разом зі списком товарів. E-mail покупця передається в Khipu, якщо він дійсний. На сторінці Khipu покупець платить банківським переказом зі свого банку.

На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Khipu: підписаним сповіщенням або запитом статусу до Khipu, коли покупець повертається. Саме повернення ніколи нічого не позначає як оплачене. Замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням складських залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо банк ще перевіряє переказ або Khipu недоступний, сторінка Payment confirmation показує Khipu is confirming your bank transfer. Your order will be confirmed 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. Кошик зберігається. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення. Кожна нова спроба (OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 оновлює замовлення оформлення і оплачує його новим платежем Khipu) видаляє попередній неоплачений платіж Khipu замовлення або кошика, тож старе посилання більше не можна оплатити. Якщо Khipu вже отримав попередній платіж, він застосовується, і покупець переходить на сторінку успіху без нового платежу. Якщо попередній переказ ще перевіряє банк, покупець бачить Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again. Якщо попередній платіж на перевірці, покупцеві пропонують звернутися до магазину, перш ніж платити знову. Зміна кошика, зокрема нова кількість, вважається новим кошиком, який потребує власної оплати.

На OpenCart 4 замовлення зберігається в оформленні, доки не буде показано сторінку успіху. Якщо замовлення тим часом закрили без оплати (наприклад, ви його скасували), покупця повертають до оформлення з повідомленням Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Якщо замовлення вже розміщено, а кошик відтоді змінився, повідомлення таке: Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. В обох випадках наступне натискання Confirm Order оплачує нове замовлення з кошика.

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

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

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

Замовлення

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

Без статусу (відсутнє замовлення): покупця надіслано до Khipu, він не оплатив, або Khipu ще не підтвердив переказ. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

Paid Order Status або Complete Order Status (за замовчуванням Обробляється або Виконано): Khipu підтвердив платіж. Статус слідує за Status after payment. Примітка показує Khipu payment verified. Payment ID: з ID платежу та сумою.

On Hold (Review) Status (за замовчуванням Очікує оплати): Khipu підтвердив платіж, сума або валюта якого не збігається із замовленням, або платіж надійшов після того, як замовлення було скасовано чи відхилено. Примітка пояснює це. Перевірте платіж у вашому обліковому записі Khipu, а потім завершіть замовлення або поверніть кошти покупцеві. Якщо пізніше для того самого замовлення надійде платіж правильної суми, замовлення перейде в статус оплаченого, а покупець отримає сповіщення e-mail. Якщо платіж надійде після того, як замовлення було переведено в інший статус обробки, статус не змінюється, а додається лише примітка.

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

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

Вкладка VibeFox Khipu Gateway

У Sales > Orders відкрийте замовлення, оплачене через Khipu. Унизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox Khipu Gateway показує спроби оплати Khipu для замовлення (дата, сума, ID платежу Khipu, статус Khipu і результат), попередження Manual review, поки замовлення перебуває в статусі перевірки, і Khipu notes замовлення. Вкладка лише для читання і показується користувачам, які мають доступ до розширення.

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

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

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

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

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

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

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

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

Оплата пройшла, але замовлення залишається без статусу: 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 not found for this account або 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 updated, retry later: замовлення в той самий момент підтверджував інший запит, або не вдалося встановити статус замовлення. Khipu надішле сповіщення повторно. Причина міститься в лозі.

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

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

Для розробників: розширення викликає події OpenCart wc_khp_supported_currencies (щоб додати валюту, яку приймає ваш рахунок Khipu, наприклад EUR для Khipu Іспанія), wc_khp_currency_decimals та wc_khp_payment_data.

Видалення

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

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

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