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

Вимоги

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

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

Доступ до магазину з Інтернету: MakeCommerce надсилає повідомлення про платежі до вашого магазину, тож сайт має бути доступний з Інтернету. Брандмауер або базова автентифікація можуть їх блокувати. Режим обслуговування їх не блокує: OpenCart 3 пропускає запити розширень оплати, а на OpenCart 4 розширення додає для них стартову дію.

Обліковий запис MakeCommerce: потрібні Shop ID і Secret key з MakeCommerce Merchant Portal (Settings > API). Тестове та робоче середовища мають окремі облікові записи й ключі. Які способи оплати й валюти доступні, визначає ваш договір із MakeCommerce. Валюти з трьома десятковими знаками, як-от KWD або BHD, не пропонуються.

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

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

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

OpenCart 3

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

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

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

4. Введіть Shop ID і Secret key тестового середовища, а для реальних платежів — робочі ключі (див. Налаштування). У Merchant Portal нічого налаштовувати не потрібно.

5. Увімкніть Enable/Disable і натисніть Save. Перевірте платіж із увімкненим Test mode, потім вимкніть його, щоб приймати реальні платежі.

OpenCart 4

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

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

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

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

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

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

Усі параметри розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox MakeCommerce Payment > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка показує Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged., поки тестовий режим увімкнено. Вона попереджає, коли спосіб оплати увімкнено, але Shop ID або Secret key поточного середовища порожні (тоді спосіб оплати приховано під час оформлення замовлення), і коли валюта за замовчуванням магазину не може бути списана MakeCommerce (тоді спосіб приховується для замовлень у цій валюті). Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження поле Title не може бути порожнім і довшим за 128 символів, Sort Order має бути цілим числом (від'ємні числа дозволено), Total має бути числом не менше 0, а кожен статус замовлення має існувати. Якщо поле заповнено неправильно, нічого не зберігається, і сторінка вказує на це поле. Пробіли з Shop ID і ключів видаляються під час збереження.

MakeCommerce

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

Title: назва способу оплати, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Bank link or card (MakeCommerce). Обов'язкове, до 128 символів.

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

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

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

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

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

Shop ID і Secret key містяться в MakeCommerce Merchant Portal у розділі Settings > API. Тестовий і робочий портали мають окремі облікові записи та ключі. Розділ містить посилання на обидва портали та на сторінку реєстрації MakeCommerce.

Test mode: використовує тестове середовище MakeCommerce (реальні кошти не списуються). Нові платежі створюються у вибраному середовищі з його ключами. Кожне замовлення пам'ятає середовище, в якому його оплачено: перевірки статусу та повернення завжди виконуються там. Поки режим увімкнено, покупці бачать TEST MODE — MakeCommerce test environment, no real money is charged. на кроці Confirm Order. За замовчуванням: увімкнено.

Test Shop ID: Shop ID вашого тестового облікового запису у форматі xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key: Secret key вашого тестового облікового запису. Він підписує й перевіряє повідомлення про платежі.

Live Shop ID: Shop ID вашого робочого облікового запису у тому самому форматі.

Live Secret key: Secret key вашого робочого облікового запису.

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

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

У Merchant Portal нічого налаштовувати не потрібно. Callback URLs показує для довідки адресу повернення або скасування для покупця та адресу повідомлень про платежі. Вони формуються з адреси вітрини вашої інсталяції OpenCart, наприклад https://your-store/index.php?route=extension/payment/wcp_makecommerce_payment/notification на OpenCart 3 і https://your-store/index.php?route=extension/wcp_makecommerce_payment/payment/wcp_makecommerce_payment.notification на OpenCart 4. Кожна транзакція має власні URL повернення, скасування та повідомлення, засновані на цих адресах з номером замовлення та доданим ключем. MakeCommerce надсилає підписане повідомлення на URL повідомлень (від сервера до сервера), а через браузер покупця — на URL повернення або скасування. Підпис перевіряється Secret key того середовища, у якому створено транзакцію. Повідомлення без дійсного підпису відхиляються.

Розширення обробляє такі статуси транзакцій MakeCommerce:

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

Замовлення

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

Order Status After Payment: статус після перевіреного платежу MakeCommerce. За замовчуванням: В обробці.

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

Cancelled Order Status: статус, який у вашому магазині означає «скасовано». Платіж MakeCommerce, що надходить за таким замовленням, переводить його на утримання. Розширення ніколи саме не встановлює цей статус. За замовчуванням: Скасовано.

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

Додатково

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

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

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

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Bank link or card (MakeCommerce)). На кроці Confirm Order покупець бачить ваш опис. OpenCart створює замовлення на цьому кроці, усе ще без статусу. Коли покупець натискає Confirm Order, розширення створює транзакцію MakeCommerce на суму замовлення у валюті замовлення і надсилає покупця на сторінку оплати MakeCommerce. Там покупець обирає банківське посилання або картку. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. E-mail і країну покупця передають до MakeCommerce, а сторінка відкривається мовою магазину, якщо MakeCommerce її підтримує (естонська, англійська, латвійська, литовська, фінська, російська, німецька, польська), інакше англійською.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження MakeCommerce: підписаним повідомленням або підписаним поверненням покупця з перевіркою транзакції через API MakeCommerce. Потім замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням складських залишків, і покупець бачить сторінку успішного замовлення OpenCart з повідомленням Your MakeCommerce payment has been received. Якщо замовлення потрапило в статус перевірки, сторінка показує Your MakeCommerce payment was received and is being reviewed by the store.

Якщо платіж схвалено, але ще не завершено, якщо замовлення в ту саму мить підтверджується іншим запитом або MakeCommerce недоступний, з'являється сторінка Payment confirmation з повідомленням We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. і кнопками Check again та Back to checkout. Check again запитує в MakeCommerce статус останніх транзакцій замовлення. Повідомлення встановлює статус замовлення, щойно платіж завершено.

Якщо покупець скасовує оплату на сторінці MakeCommerce, або платіж завершився чи не відбувся, покупець повертається до оформлення замовлення з повідомленням, наприклад The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. або The payment was not completed. Please try again or choose another payment method. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення. Кошик зберігається, і покупець може оплатити знову. Кожна спроба — це нова транзакція MakeCommerce (OpenCart 3 також створює нове замовлення щоразу, коли показується крок Confirm Order, а OpenCart 4 зберігає одне замовлення для оформлення і оплачує його знову). Перед новою транзакцією відкриті спроби того самого кошика перевіряються в MakeCommerce: якщо одна з них уже оплачена, покупець одразу потрапляє на сторінку успіху. Старе посилання на оплату того самого кошика ще працює, але кошик ніколи не оплачується двома замовленнями: пізній платіж за старим замовленням уже оплаченого кошика лише додає примітку до оплаченого замовлення.

На OpenCart 4 замовлення зберігається в оформленні, доки не буде показано сторінку успіху. Якщо замовлення тим часом закрили без оплати (наприклад, ви його скасували), покупця повертають до оформлення з повідомленням Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., а наступне натискання Confirm Order створює нове замовлення. Таке замовлення більше не утримує кошик, навіть якщо його було оплачено, а потім скасовано.

Якщо MakeCommerce не може розпочати платіж, покупець лишається на кроці Confirm Order з повідомленням MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. або MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. Технічна причина записується в журнал.

Банк або картку вибирають на сторінці MakeCommerce, а не в оформленні замовлення вашого магазину. Розширення не має збережених карток, регулярних платежів чи підписок, а також доставки через MakeCommerce (поштомати, етикетки).

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

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

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

Order Status After Payment (за замовчуванням В обробці): платіж підтверджено. Примітка показує суму, транзакцію, середовище та спосіб перевірки (API MakeCommerce або підписане повідомлення).

Payment On Hold Status (за замовчуванням Очікує оплати): оплачена сума або валюта відрізнялися від замовлення, сума була відсутня, транзакція в MakeCommerce ще не була остаточною, хоча її повідомлено як завершену, або платіж надійшов після скасування замовлення. Примітка пояснює це. Транзакція з розбіжністю ніколи не оплачує замовлення пізніше; транзакція, що не була остаточною, завершує замовлення, коли MakeCommerce повідомляє про її завершення. Перевірте транзакцію в Merchant Portal і виконайте замовлення або поверніть платіж.

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

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

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

Вкладка VibeFox MakeCommerce Payment

В Sales > Orders відкрийте замовлення, оплачене через MakeCommerce. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox MakeCommerce Payment показує всі транзакції MakeCommerce цього замовлення (дата, ID транзакції, мітку Test для тестових платежів, суму, статус і результат MakeCommerce), суми Paid / refunded, форму повернення, історію повернень і MakeCommerce notes замовлення. Вкладку показують користувачам, які мають доступ до розширення; її кнопки потребують права змінювати розширення (задається в System > Users > User Groups).

Check MakeCommerce payment status: запитує в API MakeCommerce статус транзакцій замовлення (спочатку найновіші), застосовує його і додає примітку з результатом. Використовуйте, коли покупець каже, що оплатив, але замовлення не має статусу.

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

На вкладці VibeFox MakeCommerce Payment введіть Amount (сума, яка ще не повернута, підставляється автоматично), за бажанням Reason (optional), і натисніть Refund via MakeCommerce. Підтвердіть питання Refund this amount via MakeCommerce? Підтримуються повні та часткові повернення. Повернення обмежені сумою й валютою транзакції MakeCommerce, тож після розбіжності суми можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається в те середовище, де було зроблено платіж (тестове або робоче), тож ключі цього середовища мають бути задані. Причина передається в MakeCommerce як коментар до повернення; без причини коментар — Refund for order і номер замовлення. Якщо MakeCommerce не приймає повернення, вкладка показує помилку, додається примітка і повернення не фіксується. Якщо MakeCommerce ще обробляє платіж, повідомлення — MakeCommerce is still processing this payment — try the refund again later. Успішне повернення додається до історії повернень і приміток з ID повернення MakeCommerce. Повне повернення переводить замовлення в Refunded Status без повідомлення покупця і без повернення товарів на склад, як під час ручної зміни статусу. Часткове повернення статус не змінює. Повернення доступні після того, як MakeCommerce підтвердив платіж.

Повернення товарів у Sales > Returns не повертають кошти через MakeCommerce.

Повернення, зроблені в Merchant Portal, надходять разом зі статусом транзакції і додаються до приміток. Статус замовлення автоматично не змінюється.

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

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

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

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

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

MakeCommerce не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і в поточному середовищі задані ключі: Test Shop ID і Test Secret key у тестовому режимі, Live Shop ID і Live Secret key у робочому. Перевірте, що валюта замовлення має не більше двох десяткових знаків, що адреса оплати входить до вибраної Geo Zone і що сума замовлення досягає Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення лишилося без статусу: повідомлення не змогли дійти до магазину, наприклад через брандмауер або базову автентифікацію. Замовлення також отримує статус, коли покупець повертається до магазину або натискає Check again, а також коли ви натискаєте Check MakeCommerce payment status на вкладці замовлення. Перевірте, що ключі середовища, в якому було зроблено платіж, задані: повідомлення перевіряється Secret key цього середовища, а без нього MakeCommerce отримує помилку і повторює надсилання. Увімкніть Debug log, щоб бачити повідомлення.

Замовлення в статусі перевірки: прочитайте MakeCommerce notes на вкладці замовлення (див. Статуси замовлень), перевірте транзакцію в Merchant Portal, а потім виконайте замовлення або поверніть платіж.

Повідомлення відхиляються: повідомлення з неправильним підписом, для іншого замовлення, іншого магазину або транзакції, не створеної для цього замовлення, відхиляється, і нічого не змінюється. Перевірте, що Shop ID і Secret key належать одному обліковому запису MakeCommerce і одному середовищу.

Покупець бачить помилку після Confirm Order: увімкніть Debug log і перегляньте поле Log на сторінці розширення. This payment method is not available. Please reload the checkout page. означає, що сесія оформлення більше не відповідає замовленню або спосіб оплати тим часом вимкнули: покупцеві потрібно перезавантажити оформлення замовлення. Валюта, яку MakeCommerce не може списати, дає MakeCommerce cannot process payments in і код валюти.

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

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

Для розробників: розширення викликає події OpenCart wc_mkc_transaction_data, wc_mkc_customer_data, wc_mkc_supported_locales і wc_mkc_is_available, щоб змінити дані транзакції, дані покупця, мови сторінки оплати та доступність способу оплати.

Видалення

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

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

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