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

Вимоги

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

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

Валюта: AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK або USD. Для будь-якої іншої валюти оформлення замовлення спосіб оплати приховується під час оформлення. Суми надсилаються з 2 десятковими знаками; сума з більшою кількістю десяткових знаків (наприклад, у валюті з 3 знаками, як BHD) відхиляється, а не округлюється.

Обліковий запис CorvusPay: вам потрібен обліковий запис мерчанта CorvusPay. CorvusPay видає Store ID та Secret Key для кожного магазину окремо для тестового і робочого магазину; вони відображаються в CorvusPay Merchant Center. Success URL і Cancel URL розширення потрібно вказати там (див. розділ Configuration).

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

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

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

OpenCart 3

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

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

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

4. Введіть Store ID та Secret Key вашого тестового магазину CorvusPay (і магазину для реальних платежів). Скопіюйте Success URL і Cancel URL, які відображаються на сторінці налаштувань, до CorvusPay Merchant Center — для тестового та для робочого магазину.

5. Увімкніть Enable/Disable і натисніть Save. Оформіть тестове замовлення, а потім вимкніть Test Mode, щоб перейти до реальних платежів.

OpenCart 4

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

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

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

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

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

Configuration

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > Edit. Розділи перелічені зліва; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка показує Test mode is on. Payments go to the CorvusPay test environment — no real money is taken., поки ввімкнено тестовий режим, попереджає, якщо шлюз увімкнено, але Store ID або Secret Key поточного режиму порожні (тоді спосіб оплати приховується під час оформлення, доки їх не заповнено), а також якщо валюта за замовчуванням вашого магазину не підтримується CorvusPay. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

CorvusPay

Enable/Disable: Enable CorvusPay Gateway. вмикає або вимикає спосіб оплати. Default: off.

Title: назва способу оплати, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. Default: Credit/Debit Card (CorvusPay). До 128 символів; якщо залишити порожнім, показується назва за замовчуванням.

Description: текст, який показується покупцеві на кроці Confirm Order, над кнопкою підтвердження. Default: Pay securely with your credit or debit card via CorvusPay. У тестовому режимі до нього додається (Test mode — no real payment is taken.)

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

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

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

Облікові дані магазину

Store ID і Secret Key видає CorvusPay для кожного магазину (тестового та робочого окремо); вони відображаються в CorvusPay Merchant Center.

Test Mode: використовує тестове середовище CorvusPay (wallet.test.corvuspay.com) і тестові Store ID та Secret Key. Default: on. Вимкніть, щоб приймати реальні платежі на wallet.corvuspay.com.

Test Store ID: числовий Store ID вашого тестового магазину CorvusPay.

Test Secret Key: Secret Key вашого тестового магазину CorvusPay, що використовується для підписів HMAC-SHA256.

Live Store ID: числовий Store ID вашого робочого магазину CorvusPay.

Live Secret Key: Secret Key вашого робочого магазину CorvusPay, що використовується для підписів HMAC-SHA256.

Store ID має містити лише цифри. Якщо ви введете щось інше, сторінка покаже … must contain digits only — the previous value was kept., а інші поля все одно збережуться. Збережені Secret Key ніколи не показуються знову: поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений ключ, позначте Clear the saved value on save під полем і натисніть Save. Платіж завжди перевіряється за Secret Key магазину, в якому він був розпочатий, тож тримайте тестовий ключ заповненим, поки можуть надійти тестові платежі.

Success та Cancel URL

Скопіюйте дві адреси, що відображаються в Merchant Center URLs, до CorvusPay Merchant Center — для тестового та для робочого магазину. CorvusPay повертає на них покупця після оплати. Вони формуються з адреси вітрини вашої інсталяції OpenCart; копіюйте їх точно так, як їх показує сторінка.

Оплата

Transaction Type: як саме списуються кошти з картки.

Payment Page Language: мова сторінки оплати CorvusPay. Site language (за замовчуванням) використовує поточну мову вашого магазину, якщо CorvusPay її підтримує, інакше англійську. Також можна вибрати Hrvatski, English, Deutsch, Italiano, Srpski або Slovenščina.

Order Status After Payment: статус замовлення після успішної оплати Sale. Варіанти посилаються на статуси OpenCart, вибрані в розділі Order statuses.

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

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Це статуси OpenCart, які встановлює шлюз; кожне поле перелічує ваші статуси замовлень OpenCart. В OpenCart немає статусу On hold, тому статус перевірки використовується для Authorize only, для розбіжностей суми чи валюти та для платежів після скасування; примітка до замовлення пояснює причину.

Processing status: використовується, коли Order Status After Payment — Processing. Default: Processing.

Completed status: використовується, коли Order Status After Payment — Completed. Default: Complete.

On hold (review) status: Authorize only, розбіжність суми або валюти, платіж після скасування або Order Status After Payment, встановлений на On hold. Default: Pending. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Додатково

Logging: записує налагоджувальну інформацію у corvuspay_p_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити через веб. Помилки завжди записуються, навіть коли цей параметр вимкнено; секрети, підписи та дані покупців не записуються ніколи. Default: off.

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

Delete Data: якщо увімкнено, під час видалення розширення видаляються налаштування шлюзу та файли журналів. Замовлення та дані транзакцій CorvusPay завжди зберігаються. Default: off.

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit/Debit Card (CorvusPay)). На кроці Confirm Order покупець бачить ваш опис; OpenCart створює замовлення на цьому кроці, але ще без статусу. Коли покупець натискає Confirm Order, сторінка показує Redirecting to CorvusPay for payment. Please wait... і надсилає підписану форму на сторінку оплати CorvusPay. Якщо перенаправлення не починається, покупець натискає Pay via CorvusPay. Надсилаються сума замовлення у валюті замовлення, короткий опис (Order, номер замовлення та назва магазину), а також дані адреси та електронна пошта покупця (щоб попередньо заповнити сторінку оплати). Той самий номер замовлення CorvusPay використовується повторно, доки не змінюються сума, валюта, режим і тип транзакції, і CorvusPay не приймає для нього другий платіж. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Якщо магазин не запитує платіжну адресу (типова поведінка OpenCart 4), дані власника картки беруться з імені покупця та адреси доставки.

Після оплати CorvusPay повертає покупця на Success URL. Замовлення позначається оплаченим лише після підтвердження CorvusPay: номер замовлення CorvusPay має бути виданий цим магазином, підпис має збігатися з Secret Key магазину, в якому розпочато оплату, а сума та валюта мають збігатися із замовленням. Потім замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків, і покупець бачить сторінку успішного оформлення замовлення OpenCart з написом Your CorvusPay payment has been received. Для Authorize only сторінка показує Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order., а для замовлення в статусі перевірки — Your payment was received and is being reviewed by the shop.

Якщо оплату в цей момент не вдається застосувати (наприклад, інший запит підтверджує те саме замовлення), покупець бачить Your payment is being confirmed з кнопкою Check again, яка веде на сторінку успіху, щойно замовлення отримає статус. Якщо запит на Success URL не вдається перевірити, покупець бачить Payment not confirmed і We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. Нічого не змінюється. Success URL також працює, поки магазин перебуває в режимі обслуговування: OpenCart 3 пропускає запити платіжних розширень, а на OpenCart 4 розширення додає стартову дію для Success і Cancel URL. На OpenCart 4 браузер не надсилає сесію магазину, коли CorvusPay повертає покупця, тому розширення спочатку показує коротку сторінку, яка знову відкриває ту саму адресу у вашому магазині: покупець зберігає кошик і вхід до облікового запису.

Якщо покупець скасовує оплату на сторінці CorvusPay, замовлення залишається без статусу, а покупець повертається до оформлення замовлення з незмінним кошиком і повідомленням The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. На OpenCart 4 це повідомлення показується над сторінкою оформлення замовлення. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, а нова спроба отримує новий номер замовлення CorvusPay. Якщо інше замовлення того самого кошика вже оплачено, покупець переходить на сторінку успіху замість повторної оплати.

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

Якщо оплату не вдається розпочати, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою: CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … або This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

Замовлення підтверджується лише тоді, коли CorvusPay повертає покупця на Success URL; серверних сповіщень від сервера до сервера немає. Якщо покупець закриє браузер одразу після оплати, замовлення залишиться без статусу. Розширення не підтримує повернення коштів, захоплення та анулювання з OpenCart (серверний API CorvusPay потребує клієнтського сертифіката), а також збережених карток, підписок, розстрочки та форми картки на самому сайті.

Замовлення

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

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

Processing, Completed або статус перевірки: оплату Sale підтверджено. Статус відповідає Order Status After Payment. Примітка показує номер замовлення CorvusPay, код авторизації та тип картки.

Статус перевірки, авторизовано: вибрано Authorize only. Захопіть оплату в CorvusPay Merchant Center, а потім змініть статус замовлення.

Статус перевірки, розбіжність суми або валюти: сплачена сума або валюта не збігаються із замовленням. Не відправляйте товар, доки не перевірите оплату в CorvusPay Merchant Center.

Статус перевірки, платіж після скасування: надійшов успішний платіж для спроби оплати, яку покупець скасував. Виконайте замовлення або поверніть оплату в CorvusPay Merchant Center.

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

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

Вкладка VibeFox CorvusPay Gateway

У Sales > Orders відкрийте замовлення, оплачене через CorvusPay. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox CorvusPay Gateway показує CorvusPay order number, Status спроби оплати, Transaction type, Amount (і отриману суму, якщо CorvusPay її повідомила), Approval code, Transaction, тип Card та CorvusPay notes. Тестові платежі позначено як Test. Вкладка доступна лише для читання і показується користувачам, які мають доступ до розширення.

Повернення коштів: повернення, захоплення та анулювання з OpenCart не підтримуються. Виконуйте їх у CorvusPay Merchant Center і вручну фіксуйте результат в OpenCart. Повернення товарів у Sales > Returns не повертають гроші через CorvusPay.

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

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

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

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

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

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

Оплату пройдено, але замовлення залишається без статусу: найімовірніше, Success URL не вказано в CorvusPay Merchant Center, або Secret Key в OpenCart не збігається з магазином. Знайдіть INVALID signature у полі Log на сторінці розширення (помилки завжди записуються). Замовлення також залишиться без статусу, якщо покупець закрив браузер до повернення; тоді перевірте оплату в Merchant Center і встановіть статус замовлення вручну.

Покупець бачить Payment not confirmed: запит на Success URL було відхилено: бракувало обов'язкових полів, номер замовлення CorvusPay не був виданий цим магазином, Secret Key цього магазину порожній або підпис не збігся. Нічого не змінюється. Журнал показує причину.

Покупець довго бачить Your payment is being confirmed: не вдалося встановити статус замовлення. Журнал показує причину; перевірте оплату в Merchant Center.

Покупець бачить This order total cannot be paid via CorvusPay: сума дорівнює нулю або має більше 2 десяткових знаків.

Покупець бачить CorvusPay is not configured або CorvusPay does not accept payments in …: бракує Store ID або Secret Key поточного режиму, або валюта оформлення не підтримується.

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

Замовлення має статус перевірки: прочитайте примітки на вкладці VibeFox CorvusPay Gateway. Вибрано Authorize only, сплачена сума або валюта не збігалися із замовленням, платіж надійшов після того, як покупець скасував оплату, або Order Status After Payment встановлено на On hold.

Для розробників: до підпису форми розширення викликає подію OpenCart corvuspay_p_form_params з полями форми та замовленням.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox CorvusPay Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Minimum Total і статуси з розділу Order statuses, які повертаються до значень за замовчуванням під час повторного встановлення. Подія OpenCart розширення також видаляється (на OpenCart 4 — його події та стартова дія, яка пропускає CorvusPay у режимі обслуговування). Якщо Delete Data увімкнено, видаляються решта налаштувань шлюзу (назва, опис, Store ID, Secret Key, тестовий режим, налаштування оплати, журналювання) та файли журналів. Якщо вимкнено, вони зберігаються для пізнішого повторного встановлення. Дані транзакцій CorvusPay завжди зберігаються, тож вкладка CorvusPay у старих замовлень повернеться після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

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

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