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

Вимоги

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

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

Обліковий запис Stripe: потрібні секретні API-ключі вашого облікового запису Stripe та endpoint вебхука в Stripe Dashboard (див. Конфігурація). Використовуються лише секретні ключі та секрети підпису вебхуків. Публічні ключі (pk_...) не потрібні, оскільки Stripe Checkout — це сторінка, яку розміщує Stripe.

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

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

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

OpenCart 3

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

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

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

4. Вставте секретні ключі Stripe, налаштуйте вебхук у Stripe Dashboard і вставте його секрети підпису (див. Конфігурація).

5. Увімкніть Enable/Disable і натисніть Save. Перевірте оплату в тестовому режимі карткою 4242 4242 4242 4242, потім вимкніть Test Mode.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, коли для поточного режиму немає секретного ключа (спосіб оплати тоді приховується на оформленні замовлення) або секрету підпису вебхука (тоді замовлення підтверджуються лише після того, як покупець повертається до магазину з оплати), і показує Тестовий режим увімкнено: реальні платежі не приймаються., поки тестовий режим увімкнено. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

Stripe Checkout

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

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

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

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

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

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

Ключі API

Скопіюйте секретні ключі з Stripe Dashboard > Developers > API keys (на сторінці є посилання). Тестові та робочі ключі розділені. Тестовий режим використовує лише тестові ключі, робочий режим — лише робочі.

Test Mode: використовує тестові ключі Stripe. Реальні кошти не списуються; платіть тестовими картками Stripe, наприклад 4242 4242 4242 4242. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі. Поки режим увімкнено, покупці бачать на кроці Confirm Order повідомлення Тестовий режим: реальний платіж не приймається.

Test Secret Key: секретний ключ тестового режиму. Починається з sk_test_ (або rk_test_ для обмеженого ключа).

Test Webhook Secret: секрет підпису (whsec_...) endpoint вебхука, створеного в тестовому режимі.

Live Secret Key: секретний ключ робочого режиму. Починається з sk_live_ (або rk_live_ для обмеженого ключа).

Live Webhook Secret: секрет підпису (whsec_...) endpoint вебхука, створеного в робочому режимі.

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

Вебхук

Вебхук повідомляє вашому магазину, що оплату здійснено. У Stripe Dashboard > Developers > Webhooks додайте endpoint у тестовому режимі та ще один у робочому режимі. Використовуйте URL, який показано в полі Endpoint URL у цьому розділі. У OpenCart 3 він має такий вигляд: https://your-store/index.php?route=extension/payment/wcp_stripe_gateway/webhook, а в OpenCart 4 — https://your-store/index.php?route=extension/wcp_stripe_gateway/payment/wcp_stripe_gateway.webhook. URL формується з адреси вітрини вашої інсталяції OpenCart. Копіюйте URL точно так, як його показують налаштування.

Виберіть ці події для кожного endpoint (вони також перелічені в цьому розділі):

Після створення кожного endpoint скопіюйте його секрет підпису (whsec_...) зі Stripe і вставте його в поле Test Webhook Secret або Live Webhook Secret. Вебхуки без дійсного підпису відхиляються. Подія приймається лише тоді, коли її підписано секретом того режиму, в якому було здійснено платіж, тож тестовий секрет ніколи не підтверджує реальний платіж. Без вебхука замовлення підтверджується лише тоді, коли покупець повертається до магазину після оплати.

Замовлення

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

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

Awaiting Payment Status: відкладений платіж: оформлення замовлення завершено, але Stripe ще не підтвердив кошти. За замовчуванням: Pending.

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

Failed Payment Status: відкладений платіж не вдався. За замовчуванням: Failed.

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

Додатково

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

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

Delete Data on Uninstall: якщо увімкнено, видалення розширення також видаляє налаштування шлюзу та журнал. Транзакції й повернення Stripe завжди зберігаються, тож старі замовлення лишаються доступними для повернення коштів. За замовчуванням: вимкнено.

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Stripe). На кроці Confirm Order покупець бачить ваш опис і примітку Вас буде перенаправлено на Stripe для безпечного завершення оплати. OpenCart створює замовлення на цьому кроці, ще без статусу. Коли покупець натискає Confirm Order, розширення створює сесію Stripe Checkout на суму замовлення у валюті замовлення і надсилає покупця на сторінку оплати Stripe. Там покупець платить кредитною або дебетовою карткою. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. E-mail покупця передається до Stripe, а на сторінці Stripe платіж відображається як Order # з номером замовлення.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як Stripe його підтвердить: через підписаний вебхук або серверним запитом до Stripe, коли покупець повертається. Потім замовлення отримує статус стандартним для OpenCart способом, зі звичними листами про замовлення та оновленням залишків, і покупець бачить сторінку успішного замовлення OpenCart. Для відкладеного платежу сторінка також показує Ваш платіж підтверджується Stripe. Ви отримаєте e-mail, щойно його буде підтверджено. Якщо Stripe ще не підтвердив платіж, коли покупець повертається, з’являється сторінка Підтвердження платежу з тим самим текстом і кнопкою Check again; вебхук встановить статус замовлення, щойно прийде.

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

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

Якщо Stripe не може запустити платіж, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад Сума замовлення менша за мінімальну суму, яку Stripe може списати в цій валюті. Оберіть інший спосіб оплати. Технічна причина записується в журнал.

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

Розширення приймає лише оплату картками, які списуються одразу на сторінці Stripe. Немає збережених карток, підписок або регулярних платежів, немає форми картки на вашому сайті, немає кнопок Apple Pay або Google Pay на вашому сайті, і авторизація та списання не розділяються.

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

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

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

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

Awaiting Payment Status (за замовчуванням Pending): покупець завершив оформлення з відкладеним способом оплати. Коли Stripe підтверджує платіж, замовлення переходить до Order Status After Payment; коли платіж не вдався, воно переходить до Failed Payment Status. OpenCart сповіщає покупця про ці зміни.

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

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

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

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

Вкладка VibeFox Stripe Gateway

У Sales > Orders відкрийте замовлення, оплачене через Stripe. Унизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox Stripe Gateway показує ID платежу Stripe (з посиланням на платіж у Stripe Dashboard) з позначкою Test mode для тестових платежів, Checkout Session, Status платежу, суми Paid / refunded, форму повернення коштів, історію повернень і Stripe notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

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

На вкладці VibeFox Stripe Gateway введіть Amount (підставляється сума, яку ще не повернено), за бажанням Reason (optional), і натисніть Refund via Stripe. Підтвердьте питання Повернути цю суму через Stripe? Цю дію не можна скасувати. Підтримуються повні та часткові повернення. Потрібне право змінювати розширення (налаштовується в System > Users > User Groups). Повернення виконуються в сумі та валюті, які списав Stripe, а не в сумі замовлення. Повернення надсилається в тому режимі, в якому було здійснено платіж (тестовому або робочому), тому секретний ключ цього режиму має бути встановлено. Якщо Stripe не приймає повернення, вкладка показує помилку, і повернення не записується. Успішне повернення додається до історії та приміток разом з ID повернення Stripe. Повне повернення переводить замовлення в Refunded Status без сповіщення покупця і без повернення товарів на склад, як при ручній зміні статусу. Часткове повернення статус не змінює. Повернення доступні після того, як Stripe підтвердив платіж.

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

Повернення, зроблені в Stripe Dashboard, надходять через вебхук charge.refunded і додаються до приміток із загальною сумою повернень у Stripe. Статус замовлення автоматично не змінюється. За потреби оновіть його вручну.

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

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

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

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

Без активного ключа Stripe не показується покупцям на оформленні замовлення. Якщо платіж усе ж розпочато, покупець бачить Цей спосіб оплати недоступний. Оберіть інший. Адміністратор, який увійшов в адмін-панель у тому самому браузері, все ще бачить спосіб оплати в магазині, позначений (unlicensed — visible to admins only), тож ви можете налаштувати й протестувати розширення до купівлі ключа. В OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тож без активного ключа спосіб оплати приховано для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard адмін-панелі з’явиться нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються: уже розпочаті платежі підтверджуються, а повернення працюють.

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

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

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

Платіж пройшов, але замовлення залишається без статусу: вебхук не працює. У Stripe Dashboard перевірте, що endpoint існує в режимі, який ви використовуєте (тестовому або робочому), що його URL точно збігається з URL в Endpoint URL і що вибрано всі чотири події. Перевірте, що секрет підпису цього endpoint є в потрібному полі (Test Webhook Secret або Live Webhook Secret). Stripe Dashboard показує відповідь вашого магазину для кожного вебхука. Замовлення також отримує статус, коли покупець повертається до магазину після оплати.

Вебхук відповідає «Webhook secret not configured»: не встановлено жодного секрету вебхука. Вставте секрет підпису в налаштування.

Вебхук відповідає «Invalid signature»: секрет підпису належить іншому endpoint або іншому режиму, або на сервері неправильний час. Підписи Stripe приймаються лише протягом 5 хвилин від серверного часу. Відповідь також «Invalid signature», коли подію реального платежу підписано тестовим секретом або навпаки: перевірте, чи не переплутано тестовий і робочий секрети.

Вебхук відповідає «Busy, retry»: замовлення саме підтверджувалося іншим запитом, або не вдалося встановити статус замовлення. Stripe повторює вебхук автоматично. Увімкніть Logging, щоб побачити причину.

URL вебхука в браузері показує «Method not allowed»: це нормально. URL приймає лише запити від Stripe.

Попередження «The value does not look right» під час збереження: ключ вставлено в неправильне поле. Секретні ключі починаються з sk_test_ / rk_test_ або sk_live_ / rk_live_, секрети вебхуків — з whsec_.

Покупець бачить помилку після Confirm Order: увімкніть Logging і перегляньте поле Log на сторінці розширення. Повідомлення Цей спосіб оплати недоступний. Перезавантажте сторінку оформлення замовлення. означає, що сесія оплати вже не відповідає замовленню або спосіб оплати в цей час вимкнули: покупець перезавантажує оформлення замовлення. Неправильний ключ дає повідомлення, що спосіб оплати налаштовано неправильно. Сума замовлення нижча за мінімум Stripe для валюти (наприклад, 0,50 EUR) не може бути оплачена через Stripe.

Тестові платежі не підтверджують реальний платіж: тестові та реальні платежі розділені. Перемкніть Test Mode на потрібний режим і використовуйте ключі та вебхук цього режиму.

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

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

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

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

Видалення

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

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

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