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

Вимоги

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

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

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

Валюта магазину: перуанський соль (PEN) або долар США (USD). Culqi не приймає інших валют, тому за будь-якої іншої валюти магазину спосіб оплати приховується на сторінці оформлення замовлення.

Обліковий запис Culqi: вам потрібні публічний і секретний ключі вашого облікового запису Culqi. Ключі інтеграції (тестові) беруться на integ-panel.culqi.com, робочі (live) — на mipanel.culqi.com, у розділі CulqiPanel > Desarrollo > API Keys. Публічний ключ використовується спливним вікном Culqi у браузері. Секретний ключ використовується лише на вашому сервері й ніколи не передається в браузер. Вебхук не потрібен.

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

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

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

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

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

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

5. Вставте ключі інтеграції та, для реальних платежів, робочі ключі (див. «Налаштування»).

6. Увімкніть Enable/Disable. Поки тестуєте, залиште Test Mode увімкненим, а потім зніміть прапорець, щоб приймати реальні платежі.

7. Переконайтеся, що валюта магазину — PEN або USD.

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Payments > Culqi. Над полями сторінка показує Test mode is active: the integration keys are used and no real money is charged., поки ввімкнено тестовий режим. Вона попереджає, коли шлюз увімкнено, але ключів поточного режиму немає, а також коли валюта магазину не підтримується Culqi. В обох випадках спосіб оплати приховується на сторінці оформлення замовлення. У списку способів оплати Culqi позначено як такий, що потребує налаштування, доки не задано обидва ключі поточного режиму.

Загальні

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

Title: назва способу оплати, яку покупці бачать на сторінці оформлення замовлення. За замовчуванням: Credit/Debit Card or Yape (Culqi).

Description: текст під способом оплати на сторінці оформлення замовлення. За замовчуванням: Pay securely with your credit/debit card or Yape via Culqi.

API-ключі

Скопіюйте ключі з CulqiPanel > Desarrollo > API Keys: ключі інтеграції (тестові) — на integ-panel.culqi.com, робочі ключі — на mipanel.culqi.com. Тестовий режим використовує лише тестові ключі, робочий режим — лише робочі. Кожен ключ має починатися з префікса свого поля. Ключ із неправильним префіксом не зберігається: сторінка показує помилку й залишає попереднє значення.

Test Mode: Use the Culqi integration (test) environment. Коли режим увімкнено, використовуються тестові ключі (pk_test_ / sk_test_), і реальні гроші не списуються. За замовчуванням: увімкнено. Зніміть прапорець, щоб приймати реальні платежі з робочими ключами.

Test Public Key: публічний ключ середовища інтеграції. Починається з pk_test_.

Test Secret Key: секретний ключ середовища інтеграції. Починається з sk_test_ і ніколи не передається в браузер.

Live Public Key: публічний ключ робочого середовища. Починається з pk_live_.

Live Secret Key: секретний ключ робочого середовища. Починається з sk_live_ і ніколи не передається в браузер.

Якщо ви оновлюєтеся з версії 1.0, єдина пара ключів тієї версії переноситься до тестових або робочих полів за префіксом. Після оновлення перевірте ключі.

Способи оплати

Картки пропонуються завжди. Банківський переказ, агенти, гаманці та Cuotéalo потребують Culqi Orders API і цим плагіном не пропонуються.

Yape: Offer Yape in the Culqi popup показує Yape поруч із картками у вікні Culqi. За замовчуванням: увімкнено.

Додатково

Debug log: Log API requests and payment steps записує подробиці до WooCommerce > Status > Logs, джерело wcp_culqi_payment. Помилки записуються завжди. Ключі, дані картки та дані покупця до журналу не потрапляють ніколи. За замовчуванням: вимкнено.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Деактивація плагіна нічого не видаляє. Дані Culqi, збережені в замовленнях, залишаються завжди. За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням Credit/Debit Card or Yape (Culqi)) і натискає кнопку оформлення замовлення. На тій самій сторінці відкривається спливне вікно Culqi Checkout з назвою вашого магазину, сумою замовлення та валютою. У ньому покупець вводить дані картки або платить через Yape. Поки ввімкнено тестовий режим, спосіб оплати показує TEST MODE: No real charges will be made.

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

Якщо банк вимагає 3-D Secure, покупець бачить Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Після автентифікації списання автоматично надсилається повторно. Якщо перевірку не завершено, покупець бачить The 3-D Secure verification was not completed. Please try again or use another card.

Якщо картку відхилено, покупець бачить повідомлення від Culqi, наприклад Payment failed: із зазначенням причини, і може повторити спробу з іншою карткою. Якщо Culqi не відповідає, покупець бачить We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Якщо покупець закриває вікно Culqi, нічого не списується, покупець бачить The payment window was closed before the payment was completed. і може оформити замовлення знову.

Спосіб оплати працює в класичному оформленні замовлення, у блоці «Оформлення замовлення» і на сторінці Pay for order. Він сумісний із високопродуктивним сховищем замовлень WooCommerce (HPOS).

Плагін приймає лише разові платежі карткою та через Yape з негайним списанням. У ньому немає кодів PagoEfectivo чи CIP, банківського застосунку, агентів, гаманців і Cuotéalo, немає збережених карток, підписок і платежів частинами, немає вебхуків Culqi та немає окремої авторизації та захоплення.

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

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

Pending payment: замовлення створено, але ще не списано кошти, або Culqi не відповів. У цьому разі в примітці зазначено Culqi did not confirm the charge. Перш ніж приймати інший платіж, знайдіть у CulqiPanel списання за цим замовленням.

Processing: платіж підтверджено (значення WooCommerce за замовчуванням; замовлення лише з віртуальними товарами для завантаження отримують статус «Виконано»). У примітці до замовлення вказано ID списання Culqi, режим (тестовий чи робочий) і чи використовувався 3-D Secure. ID транзакції — це ID списання Culqi.

On hold: Culqi повідомив про списання, сума або валюта якого не збігається із замовленням, або про платіж, який авторизовано, але не захоплено. Примітка до замовлення пояснює причину й показує ID списання. Перевірте списання в CulqiPanel і завершіть замовлення або поверніть кошти вручну.

Failed: картку відхилено. У примітці до замовлення вказано причину, код відмови та ID списання. Покупець може оплатити знову іншою карткою.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму й натисніть Refund via Culqi. Підтримуються повні та часткові повернення. Повернення надсилається з ключами того режиму, в якому було здійснено платіж (тестового чи робочого), навіть якщо відтоді ви переключили режим, тож секретний ключ цього режиму має бути заданий. Якщо Culqi не приймає повернення, WooCommerce показує помилку, і повернення не записується. Успішне повернення додається до приміток замовлення з ID повернення Culqi, сумою та причиною.

Повернення, зроблені в CulqiPanel, не синхронізуються назад із WooCommerce. За потреби створіть повернення вручну в WooCommerce без Refund via Culqi.

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

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

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

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

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

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

Culqi не з’являється на сторінці оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, задано обидва ключі поточного режиму (Test Public Key і Test Secret Key у тестовому режимі, Live Public Key і Live Secret Key у робочому режимі), а валюта магазину — PEN або USD. У кожному з цих випадків сторінка налаштувань показує попередження.

Платіж пройшов, але замовлення залишається в статусі Pending payment: плагін не використовує вебхуки. Списання підтверджується лише відповіддю Culqi вашому серверу. Якщо Culqi не відповів вчасно, у примітці до замовлення зазначено Culqi did not confirm the charge. Знайдіть списання за цим замовленням у CulqiPanel і, якщо воно є, завершіть замовлення вручну.

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

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

Покупець бачить Payment gateway misconfiguration. Please contact the store owner.: ключів поточного режиму немає, або Culqi відхилив секретний ключ. Перевірте ключі в налаштуваннях.

Покупець бачить Payment token is invalid. Please try again.: токен із вікна Culqi належить іншому режиму, наприклад після перемикання Test Mode, коли сторінка оформлення замовлення була відкрита. Покупцеві слід перезавантажити сторінку й оплатити знову.

Вікно Culqi не відкривається: покупець бачить The Culqi payment window could not be loaded. Please reload the page and try again. Перевірте, що скрипти з js.culqi.com і 3ds.culqi.com не блокуються на вашій сторінці оформлення замовлення, наприклад плагіном оптимізації.

Покупець бачить This order is already being paid: у той самий момент виконувався інший платіжний запит за цим замовленням. Покупцеві слід зачекати й перевірити пошту, перш ніж спробувати знову.

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

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

Для розробників: у документації плагіна перелічено фільтри culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon і culqi_p_lock_timeout.

Видалення

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

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