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.