VibeFox Conekta for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

Валюта: валюта магазина должна быть MXN или USD. Для других валют способ оплаты скрыт.

Учётная запись Conekta: нужны Private Key вашей учётной записи Conekta (тестовый и рабочий) и вебхук в панели Conekta (см. раздел «Настройка»). Используются только Private Key. Public Key не нужен, так как оплата проходит на платёжной странице Conekta.

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Conekta > Manage или нажмите Settings под названием плагина на странице «Плагины».

4. Введите лицензионный ключ VibeFox в блок лицензии в верхней части страницы и нажмите Activate.

5. Введите Private Key тестового и рабочего режима, выберите режим и добавьте вебхук в панели Conekta (см. раздел «Настройка»).

6. Включите Enable / Disable и сохраните. Проверьте оплату в тестовом режиме, затем снимите галочку Test mode.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Conekta. Над полями страница предупреждает, если Conekta включён, но Private Key текущего режима пуст (тогда способ оплаты скрыт на оформлении заказа), и если валюта магазина не MXN и не USD. Пока включён тестовый режим, страница показывает Test mode is on: payments are simulated with the test private key. При сохранении включённого шлюза без ключа текущего режима появляется сообщение об ошибке с просьбой его ввести.

Общие

Enable / Disable: Enable Conekta payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое покупатель видит на оформлении заказа. По умолчанию: Conekta.

Description: текст под способом оплаты на оформлении заказа. По умолчанию: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: способы, которые предлагаются на платёжной странице Conekta. По умолчанию: карта, наличные и банковский перевод. Наличные, SPEI и BNPL доступны только для заказов в MXN (заказы в USD принимают только карты) и должны быть включены в вашей учётной записи Conekta. Если ничего не выбрано, используется карта.

API-ключи

Скопируйте Private Key из панели Conekta в разделе Developers > API keys. Ключи тестового и рабочего режимов различаются.

Test mode: Enable test mode использует тестовый Private Key. Реальные деньги не списываются, а на оформлении заказа показывается значок TEST MODE. Возвраты всегда используют ключ того режима, в котором был совершён платёж. По умолчанию: включено.

Test private key: Private Key из тестового режима вашей учётной записи Conekta.

Live private key: Private Key из рабочего режима вашей учётной записи Conekta. Храните его в секрете.

Каждый заказ Conekta запоминает свой режим: уведомления и возвраты используют соответствующий ключ. Держите оба ключа заполненными, пока открыты старые тестовые заказы.

Вебхук

Вебхук сообщает вашему магазину о платежах, совершённых после того, как покупатель покинул страницу Conekta, например об оплатах через OXXO или SPEI. В панели Conekta перейдите в Developers > Webhooks и добавьте URL из этого раздела — отдельно для тестового и для рабочего режима. URL выглядит так: https://your-site/wc-api/webhook_wc_conekta/.

Выберите эти события:

Тело вебхука сообщает плагину только, какой заказ Conekta изменился. Каждое уведомление проверяется повторным чтением заказа через API Conekta с Private Key его режима; заголовок подписи Digest у вебхука не используется. Уведомления о заказах Conekta, которые этот магазин не создавал для данного заказа, принимаются и игнорируются. Без вебхука заказ подтверждается только тогда, когда покупатель возвращается в магазин после оплаты, или при следующей попытке оплатить тот же заказ.

Дополнительно

Debug log: Log API calls and notifications записывает подробности в WooCommerce > Status > Logs, источник wcp_conekta_gateway. Ошибки записываются всегда. Журналы никогда не содержат ключей API или контактных данных покупателя. По умолчанию: выключено.

Delete data on uninstall: Remove the settings, Conekta order references and logs when the plugin is deleted. По умолчанию: выключено.

Оформление заказа

Покупатель выбирает способ оплаты (по умолчанию Conekta) и оформляет заказ. Плагин создаёт заказ Conekta на сумму заказа в валюте заказа, с товарами, доставкой, налогами и скидками, и направляет покупателя на платёжную страницу Conekta. Там он платит одним из разрешённых способов.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Conekta: плагин читает заказ через API Conekta, когда приходит вебхук, и когда покупатель возвращается. Если платёж пока нельзя подтвердить, на странице «Заказ получен» показывается We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. Если покупатель выбрал OXXO или SPEI и получил платёжный референс, заказ переходит в статус «На удержании», а на странице показывается Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received.

Если платёж отклонён, заказ получает статус «Не удался», а покупатель возвращается на страницу Pay for order с сообщением The Conekta payment was not completed. Please try again or choose another payment method. Если срок действия платёжной страницы истёк или она была отменена, покупатель видит The Conekta payment has expired or was cancelled. Please place the order again. Когда покупатель оплачивает заказ повторно, открытая платёжная страница Conekta на ту же сумму используется повторно; в противном случае предыдущая отменяется в Conekta до создания новой, поэтому старая ссылка не может быть оплачена дважды. Если предыдущая страница уже была оплачена, платёж учитывается, а повторного списания не происходит.

Если Conekta не может начать платёж, покупатель видит короткое сообщение, например The payment could not be started. Please try again in a moment or choose another payment method. Техническая причина записывается в журнал.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS). Тексты переведены на испанский (Мексика).

Плагин принимает платежи только на странице Conekta. На странице оформления заказа нет формы карты, нет сохранённых карт, подписок, предавторизации и списания, а также помесячной рассрочки (MSI).

Заказы и возвраты

Статусы заказов

Pending payment: покупатель отправлен в Conekta и ещё не оплатил. В примечании к заказу указаны заказ Conekta и режим.

Processing: Conekta подтвердил оплату с той же суммой и валютой (заказы, содержащие только виртуальные загружаемые товары, переходят в статус «Выполнен» — значение WooCommerce по умолчанию). В примечании к заказу указаны способ оплаты (например, бренд карты и последние четыре цифры, OXXO / наличные или банковский перевод SPEI), заказ Conekta и списание. ID транзакции заказа — это ID списания Conekta (charge ID).

On hold, waiting for OXXO or SPEI: покупатель получил платёжный референс. Заказ переходит в статус «Обработка», когда Conekta сообщает о платеже.

On hold after payment: сумма или валюта, полученные от Conekta, не совпадают с заказом; платёж в тестовом режиме поступил, пока магазин работал в рабочем режиме (реальные деньги не получены); либо платёж поступил по уже отменённому заказу. Примечание к заказу объясняет причину. Проверьте платёж, затем завершите заказ или сделайте возврат. Заказ, который в Conekta только предавторизован, также переводится в статус «На удержании» с примечанием: выполнить списание или отмену в панели Conekta.

Failed: платёж отклонён. Примечание показывает причину. Покупатель может оплатить снова.

Cancelled: срок действия текущей платёжной страницы Conekta истёк или она была отменена.

Оплаченный или возвращённый заказ никогда не понижается в статусе и не открывается снова. Если для уже оплаченного заказа поступает ещё один платёж Conekta, примечание WARNING просит вернуть его в панели Conekta.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Conekta (на кнопке отображается название способа оплаты). Поддерживаются полные и частичные возвраты. Возврат направляется в заказ Conekta, содержащий платёж, и использует ключ режима, в котором был совершён платёж, поэтому этот ключ должен быть задан. Если Conekta не принимает возврат, WooCommerce показывает ошибку, и возврат не регистрируется. Успешный возврат добавляется в примечания к заказу с суммой, режимом, заказом Conekta, ID возврата и причиной.

Возвраты, сделанные в панели Conekta, приходят через вебхук и добавляются как примечание с суммой, возвращённой в Conekta и в WooCommerce. Они не регистрируются автоматически как возвраты WooCommerce. Регистрируйте их вручную, не используя Refund via Conekta. Чарджбэк, о котором сообщила Conekta, также добавляется как примечание.

Лицензионный ключ

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

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает его место для домена. Освободите место в вашей учётной записи vibefox.net.

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

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

Устранение неполадок

Conekta не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable / Disable включён, что Private Key текущего режима заполнен (Test private key в тестовом режиме, Live private key в рабочем режиме) и что валюта магазина — MXN или USD. Страница настроек показывает предупреждение по каждому из этих условий.

Платёж прошёл, но заказ остаётся в статусе Pending payment: вебхук не работает. В панели Conekta проверьте, что вебхук существует для используемого режима (тестового или рабочего), что его URL в точности совпадает с URL из настроек и что выбраны события. Проверьте, что Private Key этого режима задан, так как каждое уведомление проверяется с его помощью. Заказ также подтверждается, когда покупатель возвращается в магазин или пытается оплатить тот же заказ снова.

Вебхук отвечает Temporarily unavailable: API Conekta недоступен, Private Key режима заказа отсутствует или заказ уже обрабатывался другим запросом. Conekta повторяет вебхук.

Вебхук отвечает Verification failed, Invalid payload или Invalid order id: API Conekta не подтвердил заказ, или уведомление не было корректным событием заказа Conekta.

Вебхук отвечает Ignored: уведомление относится к заказу Conekta, который этот магазин не создавал для данного заказа (например, к другому магазину или платёжной ссылке в той же учётной записи), либо к объекту, отличному от заказа.

Покупатель видит We could not check the status of your previous payment attempt: предыдущую платёжную страницу Conekta для заказа не удалось прочитать, поэтому новая не создаётся, чтобы избежать двойной оплаты. Попробуйте через некоторое время.

Покупатель видит Payment gateway is not configured: Private Key текущего режима отсутствует.

Заказ в статусе On hold: прочитайте примечания к заказу. Покупатель ещё не оплатил референс OXXO или SPEI, сумма или валюта не совпали, либо платёж в тестовом режиме поступил, пока магазин работал в рабочем режиме.

Возврат не проходит с сообщением о тестовом или рабочем режиме: платёж был совершён в этом режиме, а его Private Key не задан. Введите его и повторите попытку.

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

Для разработчиков: readme описывает фильтр wc_ckt_supported_currencies для списка валют.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, ссылки на заказы Conekta, сохранённые в заказах, и журналы удаляются только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Conekta — товарный знак его правообладателя. Этот плагин не связан с Conekta и не одобрен компанией Conekta.