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

Вимоги

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

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

Проєкт Paysera: потрібні ID проєкту та пароль проєкту (ключ підпису) вашого проєкту Paysera. Способи оплати, які бачить покупець, — це способи, увімкнені в цьому проєкті. Для зворотного виклику в Paysera нічого налаштовувати не потрібно: його URL передається з кожним платіжним запитом.

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

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

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

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

OpenCart 3

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

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

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

4. Введіть Project ID і Project password з вашого облікового запису Paysera (див. Конфігурація).

5. За бажанням: увімкніть Allow test payments у проєкті Paysera і Test payments у розширенні, щоб перевірити процес без списання коштів. Вимкніть перед початком продажів.

6. Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

Нове встановлення починається з вимкненим способом оплати, вимкненими тестовими платежами та середовищем Production.

Конфігурація

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка показує Paysera is hidden at checkout until the project ID and the project password are entered., поки не заповнено одне з двох, і Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders., поки увімкнено тестові платежі або пісочницю. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

Paysera

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

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

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely via Paysera.

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

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

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

Проєкт Paysera

ID проєкту та пароль проєкту знаходяться у вашому обліковому записі Paysera: Projects and activities, ваш проєкт, General project settings. У розділі є посилання на обліковий запис Paysera.

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

Project ID: числовий ID вашого проєкту Paysera. Приймаються лише цифри: будь-яке інше значення дає помилку Project ID must contain digits only: the numeric ID of your Paysera project., і нічого не зберігається.

Project password: пароль проєкту (ключ підпису). Він підписує платіжні запити та перевіряє зворотні виклики Paysera. Збережений пароль більше не показується. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений пароль, позначте Clear saved password (tick and save; an empty field keeps the saved value) під полем і натисніть Save.

Тестування

Test payments: надсилає платежі в тестовому режимі, тож кошти не списуються. Paysera повертає успішний тестовий платіж без списання з покупця. Спочатку увімкніть Allow test payments в налаштуваннях проєкту Paysera. Поки цю опцію увімкнено, тестові платежі позначають замовлення оплаченими; коли вимкнено, тестовий платіж переводить замовлення на утримання. За замовчуванням: вимкнено. Поки опцію увімкнено, покупець бачить на кроці Confirm Order повідомлення TEST MODE — no money will be charged.

Environment: куди надсилається покупець. Для звичайного проєкту Paysera залиште Production, зокрема для тестових платежів. За замовчуванням: Production.

Замовлення

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

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

Awaiting Payment Status: банк прийняв платіжне доручення, але ще не виконав його. Замовлення позначається оплаченим, коли Paysera підтверджує платіж. За замовчуванням: Pending.

On Hold Status: ТЕСТОВИЙ платіж, коли Test payments вимкнено, інша сума або валюта, або платіж після скасування покупцем. Замовлення не позначається оплаченим; примітка пояснює причину. За замовчуванням: Pending, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

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

Додатково

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

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

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

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Paysera). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. OpenCart створює замовлення на цьому кроці, ще без статусу. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати у вікні Payment method options і натискає Confirm Order внизу сторінки оформлення замовлення. Коли покупець натискає Confirm Order, розширення формує підписаний платіжний запит із номером замовлення, сумою замовлення в найменшій одиниці валюти замовлення, іменем, електронною поштою та платіжною адресою покупця, а також мовою сторінки магазину (литовська, латвійська, естонська, російська, німецька, польська; інакше англійська). Покупець переходить до вікна оплати Paysera і там обирає банк, картку або інший спосіб.

Paysera підтверджує платіж серверним зворотним викликом. Замовлення позначається оплаченим лише після підписаного підтвердження від Paysera; повернення покупця до магазину ніколи не оплачує замовлення. Потім замовлення отримує статус звичним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків. Коли покупець повертається після зворотного виклику, показується сторінка успішного оформлення замовлення OpenCart. Якщо банк прийняв платіжне доручення, але ще не виконав його, замовлення отримує Awaiting Payment Status, а сторінка показує Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Для замовлення на утриманні сторінка показує Your payment is being reviewed. We will contact you if anything else is needed.

Якщо покупець повертається до зворотного виклику, з'являється сторінка Payment confirmation, яка пояснює, що замовлення буде підтверджено, щойно Paysera підтвердить платіж, і пропонує Check again та Back to checkout.

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

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

Якщо платіж не вдається розпочати, покупець залишається на кроці Confirm Order з повідомленням Paysera payments are temporarily unavailable. Please choose another payment method. або, для недійсної суми замовлення, з повідомленням This order cannot be paid via Paysera. Причина записується в журнал.

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

Розширення не підтримує повернення коштів з адмін-панелі, вибір банку чи способу оплати на сторінці оформлення замовлення, підписки, збережені картки та служби доставки чи кур'єрські служби Paysera.

Замовлення

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

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

Order Status After Payment (за замовчуванням Processing): Paysera підтвердила платіж із відповідними сумою та валютою. Примітка показує запит і спосіб оплати, а для тестових платежів — позначку (TEST — no money charged).

Awaiting Payment Status (за замовчуванням Pending): Paysera прийняла платіжне доручення, але банк ще не виконав його. Замовлення переходить у Order Status After Payment, коли Paysera підтверджує платіж.

On Hold Status (за замовчуванням Pending): платіж потребує ручної перевірки. Сплачена сума або валюта не збігаються із сумою замовлення; ТЕСТОВИЙ платіж надійшов, поки Test payments вимкнено (кошти не списувалися); або платіж підтверджено після того, як покупець його скасував. Примітка це пояснює, а вкладка замовлення просить перевірити платіж у вашому обліковому записі Paysera, а потім або перевести замовлення в статус оплаченого, або скасувати його й повернути платіж у Paysera. Пізніший коректний платіж для того самого замовлення позначає його оплаченим.

Cancelled Order Status (за замовчуванням Canceled): платіж, підтверджений пізніше для скасованого замовлення, не змінює його статус. Примітка пропонує відновити замовлення (перевести в статус оплаченого) або повернути платіж у Paysera. Якщо спосіб оплати замовлення вже не Paysera, підтверджений платіж лише додає примітку.

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

Вкладка VibeFox Paysera Payment

У Sales > Orders відкрийте замовлення, оплачене через Paysera. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Paysera Payment показує Paysera order ID (номер замовлення та спробу), Paysera request ID, Environment і позначку TEST payment, Status платежу, суми Requested / paid, Payment method і Notes розширення. Для замовлення на утриманні вона показує, що перевірити. Вкладка лише показує інформацію і видна користувачам, які мають доступ до розширення.

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

Повернення коштів з адмін-панелі не підтримуються: протокол вікна оплати Paysera не має API повернень. Оформлюйте повернення у вашому обліковому записі Paysera. Коли Paysera повідомляє про повернення, до замовлення додається примітка із сумою повернення, а статус замовлення не змінюється. За потреби зафіксуйте повернення в OpenCart вручну. Повернення товарів у Sales > Returns не повертають кошти через Paysera.

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

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

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

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

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

Paysera не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, і заповнені обидва поля: Project ID та Project password. Сторінка налаштувань показує попередження, поки чогось із цього бракує. Також перевірте, що платіжна адреса входить до вибраної Geo Zone, і що замовлення досягає Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення залишається без статусу: замовлення отримує статус із зворотного виклику Paysera, а не з повернення покупця. Перевірте, що магазин доступний з інтернету за Callback URL, вказаною в налаштуваннях (не за логіном, базовою автентифікацією чи брандмауером), і перегляньте поле Log на сторінці розширення.

Зворотний виклик відповідає Invalid signature: Project password не відповідає проєкту, або зворотний виклик не від Paysera. Скопіюйте пароль проєкту знову. Якщо ви змінювали проєкт або пароль, платежі, розпочаті до зміни, більше не можна перевірити.

Зворотний виклик відповідає Project ID mismatch: Project ID у налаштуваннях відрізняється від проєкту, який здійснив платіж.

Зворотний виклик відповідає Order not found: замовлення зі зворотного виклику не має платежу Paysera в цьому магазині, наприклад платіж розпочато в іншому магазині з тим самим проєктом.

Зворотний виклик відповідає Gateway not configured, Busy або Temporary error: ID або пароль проєкту порожній, інший зворотний виклик для того самого кошика ще виконується, або не вдалося встановити статус замовлення. Paysera повторює зворотний виклик. Увімкніть Debug log, щоб побачити причину.

Paysera відхиляє вікно оплати або повідомляє, що проєкту не існує: перевірте Environment. Звичайний проєкт Paysera працює лише з Production; Sandbox потребує проєкту, створеного в пісочниці Paysera.

Тестовий платіж не оплачує замовлення: ТЕСТОВИЙ платіж оплачує замовлення, лише поки увімкнено Test payments. Інакше замовлення переводиться на утримання з приміткою, що кошти не списано. Також увімкніть Allow test payments у проєкті Paysera.

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

Покупець бачить Paysera payments are temporarily unavailable: перегляньте поле Log. ID або пароль проєкту можуть бути порожніми, або одна з адрес магазину, переданих у Paysera, довша за 255 символів.

Покупець бачить This payment method is not available. Please reload the checkout page.: сесія оформлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнено. Покупець перезавантажує сторінку оформлення.

Видалення

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

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

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