VibeFox Xendit for WooCommerce — Помощь

Требования

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

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

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

Валюта магазина: IDR, PHP, VND, THB, MYR, USD или SGD. Для других валют способ оплаты не показывается. Какие платёжные каналы и валюты реально доступны, зависит от вашего аккаунта Xendit.

Аккаунт Xendit: нужен секретный ключ API с правом записи для Money-in (счета) для тестового режима и ещё один для рабочего режима, а также токен верификации вебхука каждого режима (см. раздел «Настройка»). Используются только секретные ключи и токены верификации. Публичный ключ не нужен, потому что покупатель платит на размещённой на стороне Xendit странице счёта.

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

Установка

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

2. Нажмите Activate.

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

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

5. Вставьте секретные ключи Xendit, укажите URL вебхука в Xendit Dashboard и вставьте токены верификации (см. раздел «Настройка»).

6. Включите Enable/Disable. Сделайте тестовый заказ в тестовом режиме, затем снимите отметку Test Mode, чтобы принимать реальные платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Xendit. Над полями баннер показывает активный режим: TEST MODE (счета создаются с тестовым секретным ключом, реальные деньги не списываются) или LIVE MODE (счета создаются с рабочим секретным ключом, и с покупателей списываются деньги). Баннер предупреждает, когда секретный ключ активного режима отсутствует или имеет неверный префикс (тогда способ оплаты скрывается на оформлении заказа), и когда токен верификации вебхука активного режима пуст (уведомления Xendit отклоняются, поэтому заказы обновляются только когда покупатель возвращается в ваш магазин). В списке способов оплаты Xendit отмечен как требующий настройки, пока у активного режима нет действительного секретного ключа.

Общие

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

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

Description: текст под способом оплаты на оформлении заказа. По умолчанию: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Ключи API

Создайте секретный ключ API с правом записи для Money-in (счета) в Xendit Dashboard > Settings > Developers > API keys: один раз в тестовом режиме и один раз в рабочем. Ключ определяет, где создаётся счёт. При сохранении ключ, который не начинается с префикса своего поля, не сохраняется, и страница показывает, например, Test secret key was not saved: it must start with xnd_development_. Остальные настройки сохраняются.

Test Mode: Enable test mode создаёт счета с тестовым секретным ключом, поэтому реальные деньги не списываются. По умолчанию: включено. Снимите отметку, чтобы принимать реальные платежи с рабочим секретным ключом.

Test Secret Key: секретный ключ тестового режима Xendit. Начинается с xnd_development_.

Live Secret Key: секретный ключ рабочего режима Xendit. Начинается с xnd_production_.

Вебхуки

Вебхук сообщает вашему магазину, что счёт оплачен. В Xendit Dashboard > Settings > Developers > Webhooks укажите URL из этого раздела настроек для Invoices > Invoice paid — в тестовом и в рабочем режимах. По желанию укажите его и для Invoice expired. URL выглядит так: https://your-site/wc-api/xendit_p_callback/. Скопируйте его точно в таком виде, как он показан в настройках.

Затем скопируйте Webhook verification token каждого режима из Xendit Dashboard в соответствующее поле. Xendit передаёт его в заголовке x-callback-token. Уведомления без токена того режима, в котором создан счёт, отклоняются. Токен лишь подтверждает, что уведомление пришло от Xendit: статус, сумма и валюта счёта всегда повторно запрашиваются через API Xendit с секретным ключом этого режима. Без вебхука заказ подтверждается только тогда, когда покупатель возвращается в магазин после оплаты.

Test Webhook Verification Token: токен верификации вебхука тестового режима Xendit.

Live Webhook Verification Token: токен верификации вебхука рабочего режима Xendit.

Оплата

Invoice Description: описание, которое отображается в счёте Xendit. Можно использовать заполнители {order_id}, {order_number} и {site_name}. HTML удаляется, текст обрезается до 255 символов. По умолчанию: Order #{order_id}.

Order Status After Payment: статус заказа, который устанавливается после того, как Xendit подтвердит оплату. Статус устанавливается сразу, одним изменением.

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

Debug Log: Log API requests and webhooks записывает запросы, вебхуки и изменения статусов в WooCommerce > Status > Logs, источник wcp_xendit_payment_gateway. Ошибки и предупреждения записываются всегда, даже когда опция выключена. Ключи API, токены и данные покупателей не записываются. По умолчанию: выключено.

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. Деактивация плагина ничего не удаляет. Данные заказов (ID счетов в заказах) всегда сохраняются. По умолчанию: выключено.

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

Способ оплаты показывается, когда валюта магазина — IDR, PHP, VND, THB, MYR, USD или SGD. На странице Pay for order учитывается валюта заказа. Покупатель выбирает способ оплаты (по умолчанию Xendit) и оформляет заказ. Плагин создаёт счёт Xendit на сумму заказа в валюте заказа и отправляет покупателя на страницу счёта Xendit. Суммы в IDR и VND округляются до целых чисел, потому что Xendit не принимает для них десятичные знаки. Адрес электронной почты покупателя для выставления счёта передаётся в Xendit. На странице счёта покупатель платит одним из платёжных каналов, подключённых в вашем аккаунте Xendit для этой валюты, например виртуальным счётом, электронным кошельком, QR-кодом, розничной точкой или картой.

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Заказ отмечается оплаченным только после подтверждения Xendit: вебхуком или серверным запросом к API Xendit, когда покупатель попадает на эту страницу. До этого заказ остаётся в статусе «Ожидает оплаты».

Если счёт не оплачен или истекает, Xendit возвращает покупателя. Заказ, оформленный на странице оформления, тогда отменяется стандартным для WooCommerce способом, а его счёт деактивируется. Заказ, оплачиваемый со страницы Pay for order (например, созданный вами для покупателя), возвращается на свою страницу оплаты с сообщением The Xendit payment was not completed. You can try again or choose another payment method. и остаётся доступным для оплаты.

Покупатель может снова оплатить неоплаченный заказ. Если сумма заказа, валюта и режим не изменились и открытый счёт ещё действителен, покупатель переходит к тому же счёту. Иначе старый счёт сначала деактивируется и создаётся новый, поэтому у одного заказа никогда не бывает двух открытых счетов. Если старый счёт уже оплачен, заказ переходит в статус «Выполнен» вместо новой оплаты.

Если Xendit не может начать оплату, покупатель видит короткое сообщение и может выбрать другой способ оплаты, например Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., сообщение о том, что валюта не принимается для вашего аккаунта, или о том, что сумма заказа выходит за пределы лимитов Xendit. Техническая причина записывается в журнал. Заказ с нулевой суммой нельзя оплатить через Xendit.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. В тестовом режиме блок «Оформление заказа» показывает под способом оплаты Test mode: no real money is charged. Плагин совместим с WooCommerce High-Performance Order Storage (HPOS).

Оплата всегда проходит на странице Xendit. В плагине нет возвратов из WooCommerce, сохранённых карт, подписок или регулярных платежей, полей карты или электронного кошелька на странице оформления заказа, раздельных авторизации и списания, субаккаунтов xenPlatform, настраиваемого срока действия счёта и комиссий за оплату.

Заказы

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

Pending payment: счёт создан, а покупатель ещё не оплатил, или Xendit ещё не подтвердил оплату. В примечании к заказу указаны ID счёта, сумма, валюта и режим.

Processing or Completed: оплата подтверждена. Статус соответствует значению Order Status After Payment. В примечании к заказу указаны ID счёта, оплаченная сумма, платёжный канал и режим. ID транзакции — это ID счёта Xendit.

On hold: оплаченный счёт не совпал с суммой или валютой заказа, либо оплачено меньше суммы заказа (например, заказ был изменён после создания счёта). Примечание к заказу объясняет это, в том числе когда заказ уже был на удержании. Проверьте платёж в Xendit Dashboard, затем выполните заказ или сделайте возврат платежа.

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

Cancelled: покупатель вернулся после неудачного или истёкшего счёта, либо заказ отменили вы или тайм-аут WooCommerce для неоплаченных заказов. Открытый счёт деактивируется, поэтому его больше нельзя оплатить. Если Xendit не принимает это, примечание попросит вас деактивировать счёт в Xendit Dashboard.

Если счёт оплачен для заказа, который уже оплачен, отменён или возвращён, заказ не меняется. Примечание попросит вас вернуть платёж в Xendit Dashboard или восстановить заказ вручную.

Возвраты

Возвраты не отправляются в Xendit из WooCommerce. Верните платёж в Xendit Dashboard (примечание к заказу и ID транзакции содержат ID счёта) и зафиксируйте возврат в WooCommerce вручную.

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

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

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

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

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

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

Xendit не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено, что у активного режима есть секретный ключ с правильным префиксом (Test Secret Key с xnd_development_ в тестовом режиме, Live Secret Key с xnd_production_ в рабочем режиме), и что валюта магазина — IDR, PHP, VND, THB, MYR, USD или SGD. Баннер в настройках показывает предупреждение, если ключ отсутствует или неверен.

Оплата прошла, но заказ остаётся в статусе «Ожидает оплаты»: вебхук не работает. В Xendit Dashboard того режима, который вы используете (тестового или рабочего), проверьте, что URL из настроек указан для Invoice paid и что токен верификации этого режима сохранён в соответствующем поле. Xendit Dashboard показывает ответ вашего магазина на каждый вебхук. Заказ также подтверждается, когда покупатель возвращается на страницу «Заказ получен».

Ответ вебхука «Webhook verification token is not configured»: не задан ни один из двух токенов верификации. Вставьте токен в настройки.

Ответ вебхука «Unauthorized»: токен, присланный Xendit, не совпадает ни с одним токеном в настройках. Скопируйте токен нужного режима заново.

Ответ вебхука «Token does not match the mode of this invoice»: счёт создан в другом режиме. Тестовое уведомление никогда не подтверждает рабочий заказ, и наоборот. Настройте вебхук и токен в том режиме, в котором был оплачен заказ.

Ответ вебхука «Ignored: not an invoice of this store»: счёт создан не этим магазином, например другой интеграцией на том же аккаунте Xendit. Кнопка Test в Xendit Dashboard также получает этот ответ, что подтверждает работоспособность URL и токена.

Ответ вебхука «Temporary error»: не удалось обратиться к API Xendit для проверки счёта, секретный ключ режима счёта отсутствует, или заказ в тот же момент обновлялся другим запросом. Xendit повторит вебхук. Проверьте, что заданы оба секретных ключа, если у вас есть заказы из обоих режимов.

Ключ не сохраняется: значение не начинается с префикса своего поля. Тестовые ключи начинаются с xnd_development_, рабочие — с xnd_production_.

Покупатель видит «This payment method is temporarily unavailable»: Xendit отклонил запрос, например из-за неверного секретного ключа или отсутствия права записи для Money-in (счета). При необходимости включите Debug Log и посмотрите WooCommerce > Status > Logs, источник wcp_xendit_payment_gateway. Сообщение о платёжных данных означает, что Xendit не принял данные запроса, например адрес электронной почты.

Покупатель видит «A payment for this order was already received by Xendit and is being reviewed»: ранее созданный счёт этого заказа был оплачен, но не совпал с заказом, поэтому заказ на удержании. Проверьте платёж в Xendit Dashboard.

Заказ на удержании после оплаты: прочитайте примечание к заказу. Оплаченная сумма или валюта отличались от заказа. Выполните заказ или сделайте возврат платежа в Xendit Dashboard.

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

Удаление

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

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