VibeFox OpenPay for WooCommerce — Допомога

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 8.0 або новіша, встановлений і активний. Плагін не активується без нього.

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

HTTPS: ваш сайт має використовувати HTTPS, оскільки форма картки розміщена на вашій сторінці оформлення замовлення.

Обліковий запис OpenPay: обліковий запис OpenPay з Мексики, Колумбії або Перу. Потрібні його Merchant ID, закритий ключ (sk_...) і відкритий ключ (pk_...). Панелі пісочниці та робочого режиму мають різні Merchant ID і ключі, а плагін тримає їх окремо.

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

Картку вводять на вашій сторінці оформлення замовлення, але зчитує і токенізує в браузері openpay.js. Поля картки не мають імені і ніколи не надсилаються на ваш сервер. Оскільки форма картки розміщена на вашій сторінці, ваша зона відповідальності за PCI DSS — SAQ A-EP; уточніть це у свого еквайєра.

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити папку wcp_openpay_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > OpenPay > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки і натисніть Activate.

5. Виберіть Account country і введіть ключі пісочниці та робочого режиму (див. Налаштування).

6. Рекомендовано: додайте URL вебхука в панелі OpenPay (див. Налаштування).

7. Увімкніть Enable / Disable і збережіть. Перевірте оплату тестовими картками пісочниці OpenPay, а потім зніміть позначку з Sandbox mode, щоб приймати реальні платежі.

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

Усі параметри розміщені на одній сторінці: WooCommerce > Settings > Payments > OpenPay. Над полями сторінка попереджає, якщо ключі поточного режиму неповні (тоді спосіб оплати приховується на сторінці оформлення замовлення), якщо валюта магазину не приймається обраною країною облікового запису, і показує Sandbox mode is enabled — no real charges are made., поки режим пісочниці увімкнено. У списку способів оплати OpenPay позначено як такий, що потребує налаштування, доки в поточному режимі не заповнено всі три ключі; поки режим пісочниці увімкнено, відображається позначка тестового режиму.

Під час збереження ключі перевіряються. Merchant ID може містити лише літери та цифри, закритий ключ має починатися з sk_, а відкритий — з pk_. Некоректне значення не зберігається: лишається попереднє значення і показується помилка, наприклад Sandbox: The private key must start with sk_. Якщо спосіб оплати увімкнено, але ключі поточного режиму неповні, ви також побачите повідомлення, що шлюз залишається прихованим на сторінці оформлення замовлення.

Загальні

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

Title: назва способу оплати, яку бачать покупці на сторінці оформлення замовлення. За замовчуванням: Credit or debit card (OpenPay).

Description: текст над формою картки на сторінці оформлення замовлення. За замовчуванням: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

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

Merchant ID, закритий ключ (sk_) і відкритий ключ (pk_) розміщені в панелі OpenPay у розділі Settings (Configuración). У розділі є посилання на панелі пісочниці та робочого режиму для Мексики, Колумбії та Перу.

Account country: країна вашого облікового запису OpenPay. Вона визначає API OpenPay, бібліотеку openpay.js цієї країни та прийнятні валюти. За замовчуванням: Mexico.

Sandbox mode: Use the OpenPay sandbox (test keys, no real charges) перемикає і ключі, і API на пісочницю. Позначка SANDBOX MODE показується на сторінці оформлення замовлення, поки режим увімкнено. За замовчуванням: увімкнено. Зніміть позначку, щоб приймати реальні платежі.

Sandbox Merchant ID: Merchant ID з панелі пісочниці, Settings (Configuración), ключі API.

Sandbox Private Key: закритий ключ пісочниці. Він починається з sk_. Використовується лише на сервері; нікому його не передавайте.

Sandbox Public Key: відкритий ключ пісочниці. Він починається з pk_. openpay.js використовує його в браузері для токенізації картки.

Live Merchant ID: Merchant ID з панелі робочого режиму, Settings (Configuración), ключі API.

Live Private Key: закритий ключ робочого режиму (sk_...).

Live Public Key: відкритий ключ робочого режиму (pk_...).

Ключі з версії 1.0 плагіна (один набір ключів і прапорець пісочниці) автоматично переносяться в поля пісочниці або робочого режиму.

Вебхук

Вебхук не є обов'язковим, але рекомендований. Він підтверджує платежі, коли покупець не повертається зі сторінки 3D Secure, наприклад якщо закрив браузер. У панелі OpenPay перейдіть до Settings > Webhooks і додайте URL, який показано в цьому розділі налаштувань. Він має такий вигляд: https://your-site/wc-api/webhook_wc_openpay/. Скопіюйте його точно так, як його показано в налаштуваннях. Додайте вебхук у панель кожного режиму, який використовуєте (пісочниці та робочого режиму).

Коли ви додаєте вебхук, OpenPay надсилає на цю адресу код підтвердження. Код з'являється в цьому розділі разом із датою надходження, щоб ви могли підтвердити вебхук у панелі OpenPay.

Виберіть ці події:

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

Додатково

Debug log: Log payment steps (errors are always logged) записує кроки оплати в WooCommerce > Status > Logs, джерело wcp_openpay_gateway. Помилки та попередження записуються, навіть якщо опцію вимкнено. Ключі, дані картки та дані покупця ніколи не записуються в журнал. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням Credit or debit card (OpenPay)) і заповнює Cardholder name, Card number, Expiry (MM/YY) і Card code (CVV). Після оформлення замовлення openpay.js перетворює картку на одноразовий токен у браузері, а бібліотека OpenPay для перевірки шахрайства додає ідентифікатор сесії пристрою. Вашому магазину передаються лише ці два значення.

Далі плагін створює списання з 3D Secure на суму замовлення у валюті замовлення і спрямовує покупця на сторінку 3D Secure його банку, яку надає OpenPay. Кожна спроба отримує власне посилання на замовлення в OpenPay (номер замовлення і короткий суфікс). Описом списання є Order #, номер замовлення та назва вашого сайту. Ім'я, електронна пошта і телефон покупця передаються в OpenPay; обліковий запис клієнта в OpenPay не створюється. Замовлення залишається в статусі Очікує оплати, поки покупець перебуває на сторінці 3D Secure.

Коли покупець повертається, плагін зчитує списання з API OpenPay. Замовлення позначається оплаченим лише після підтвердження OpenPay: списання має належати цьому замовленню, бути завершеним і точно збігатися із сумою та валютою замовлення. Якщо результат ще невідомий, сторінка підтвердження замовлення показує We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Потім вебхук оновлює замовлення.

Якщо картку відхилено або 3D Secure не пройшов, покупець повертається на сторінку Pay for order з повідомленням The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. і може оплатити знову. Перед новою спробою плагін перевіряє попереднє списання замовлення: якщо воно справді оплачене, замовлення позначається оплаченим без другого списання; якщо воно ще обробляється, покупець бачить, що попередній платіж ще обробляється, і не повинен платити знову; якщо його стан не можна перевірити, нову спробу не здійснюють, і покупця просять повторити за кілька хвилин.

Відхилені картки отримують зрозуміле повідомлення, наприклад The card has insufficient funds. Please use another card., The card has expired. Please use another card. або The security code (CVV) is not valid. Please check it and try again. Технічні помилки OpenPay покупцям ніколи не показуються; вони потрапляють до нотаток замовлення та журналу.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS). На сторінці оформлення замовлення він приховується, якщо вимкнений, якщо ключі поточного режиму неповні або якщо валюта замовлення не приймається країною облікового запису.

Плагін приймає лише картки зі списанням одразу. Він не підтримує збережені картки, підписки, безвідсоткове розстрочення (MSI) чи оплату частинами, оплату бонусами картки, готівку, SPEI, PSE або CoDi, а також окремі авторизацію та списання.

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

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

Очікує оплати: покупець на сторінці 3D Secure або ще не завершив оплату. Нотатка показує ID списання.

Обробляється: оплату підтверджено. Це звичайний статус WooCommerce після оплати; замовлення лише з віртуальними товарами для завантаження переходять у статус «Виконано». Нотатка до замовлення показує ID списання та режим (робочий або пісочниця). ID транзакції — це ID списання OpenPay.

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

Невдало: картку відхилено під час створення списання, або остання спроба не вдалася, була скасована чи прострочена. Покупець може оплатити знову.

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

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

Для облікових записів з Мексики і Перу: відкрийте замовлення, натисніть Refund, введіть суму і натисніть Refund via Credit or debit card (OpenPay) (на кнопці відображається назва вашого способу оплати). Підтримуються повні та часткові повернення. Повернення надсилається в тому режимі та з тією країною облікового запису, у яких було оплачено замовлення, тож тримайте ключі пісочниці заповненими, поки є замовлення пісочниці для повернення. Якщо OpenPay не приймає повернення, WooCommerce показує помилку, наприклад OpenPay refund failed: ..., і повернення не реєструється. Успішне повернення додається до нотаток замовлення з ID повернення OpenPay.

OpenPay Colombia не підтримує повернення карткових платежів через API, як і офіційні плагіни OpenPay. Для Колумбії кнопка повернення не пропонується; поверніть списання в панелі OpenPay.

Повернення і спори, здійснені в панелі OpenPay, надходять через вебхук і один раз додаються до нотаток замовлення. Вони не реєструються автоматично як повернення WooCommerce. За потреби створіть ручне повернення в WooCommerce, не використовуючи кнопку OpenPay.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розміщено у верхній частині WooCommerce > Settings > Payments > OpenPay. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now, щоб знову перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

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

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

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

OpenPay не з'являється на сторінці оформлення замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено і в поточному режимі заповнені всі три ключі: ключі пісочниці в режимі пісочниці, ключі робочого режиму в робочому. Перевірте, що валюта магазину приймається Account country (Мексика: MXN, USD; Колумбія: COP, USD; Перу: PEN, USD). У кожному такому випадку сторінка налаштувань показує попередження.

Оплату пройдено, але замовлення залишається в статусі Очікує оплати: покупець не повернувся зі сторінки 3D Secure, а вебхук не працює. Перевірте, що URL вебхука додано в панелі OpenPay того режиму, який ви використовуєте, точно так, як показано в налаштуваннях, з переліченими вище подіями. Перевірте, що заповнені ключі режиму, у якому було оплачено замовлення: без них вебхук відповідає not configured, і OpenPay повторить спробу пізніше.

Вебхук відповідає ignored (unknown order): списання не створював цей магазин для цього замовлення, наприклад це списання іншого магазину на тому самому обліковому записі OpenPay. Нічого не змінюється.

Вебхук відповідає verification failed: не вдалося звернутися до API OpenPay, щоб прочитати списання. OpenPay повторить вебхук.

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

Покупець бачить «The secure card form could not be loaded»: openpay.js або бібліотека OpenPay для перевірки шахрайства не завантажилися в браузері, або не вдалося створити ідентифікатор сесії пристрою. Попросіть покупця перезавантажити сторінку і повторити спробу.

Покупець бачить «The payment could not be processed right now»: OpenPay відхилив запит або не відповів. Причина вказана в нотатках до замовлення і в журналі, джерело wcp_openpay_gateway. Типова причина — неправильні Merchant ID або закритий ключ. Якщо OpenPay не відповів, перевірте списання в панелі OpenPay, перш ніж покупець оплатить знову.

«This test card cannot be used for real payments»: використано тестову картку пісочниці, коли режим пісочниці вимкнено.

Замовлення «На утриманні» після оплати: прочитайте нотатку до замовлення. Списання ще триває, оплачена сума або валюта відрізняються від замовлення, або платіж надійшов після скасування замовлення.

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адресу сайту змінено, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу, збережений код перевірки вебхука та журнали плагіна видаляються, лише якщо було увімкнено Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Дані замовлень завжди зберігаються: наявні замовлення зберігають свої нотатки про оплату, ID транзакцій і дані списань, потрібні для повернень після повторного встановлення.

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