VibeFox Xendit for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

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

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Xendit Payment Gateway в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

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

5. Включите Enable/Disable и нажмите Save. Оформите тестовый заказ в тестовом режиме, затем выключите Test Mode, чтобы принимать реальные платежи.

При установке модуль создаёт статус заказа Xendit payment on hold. PrestaShop предлагает новый способ оплаты для всех валют, стран и групп клиентов. Ограничить их можно в Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure. В каждом разделе есть своя кнопка Save, которая сохраняет всю страницу. Над полями блок показывает активный режим: 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: создаёт счета с тестовым секретным ключом, поэтому реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи с рабочим секретным ключом. Пока режим включён, покупатели видят Test mode: no real money is charged. под способом оплаты.

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

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

Сохранённые ключи и токены больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Вебхуки

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

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

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

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

Clear saved secrets: отметьте ключ или токен и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Оплата

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

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

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

Debug Log: записывает запросы к API и вебхуки в logs/xendit_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки и предупреждения записываются всегда, даже если опция выключена. Ключи API, токены и данные покупателей не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete Data on Uninstall: если включено, при удалении модуля удаляются его настройки и журнал. Данные заказов (ID счетов заказов) и статус заказа Xendit payment on hold всегда сохраняются. По умолчанию: выключено.

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

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

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Xendit: вебхуком или серверным запросом к API Xendit, когда покупатель возвращается. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа. Если Xendit ещё не подтвердил оплату, появляется страница Payment confirmation с текстом Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. и кнопками Check again и Back to checkout. Вебхук создаёт заказ, как только получит уведомление.

Если счёт не оплачен или истекает, Xendit возвращает покупателя. Модуль сначала проверяет счёт (он мог быть оплачен в другой вкладке), затем деактивирует его, чтобы его больше нельзя было оплатить. Покупатель возвращается на оформление заказа с сообщением 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 нельзя.

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

Заказы

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

Заказа пока нет: покупатель отправлен в Xendit и не оплатил, или Xendit ещё не подтвердил оплату. Существует только корзина.

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

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

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

Блок Xendit payment

На странице заказа показан блок Xendit payment с ID счёта, режимом (со значком Test mode для тестовых платежей), статусом оплаты, списком всех счетов заказа (дата, счёт, внешний ID, сумма и оплаченная сумма, статус, платёжный канал) и Payment notes заказа.

Возвраты

Возвраты из магазина в Xendit не отправляются. Верните платёж в Xendit Dashboard (найдите ID счёта, показанный в блоке Xendit payment) и зафиксируйте возврат в заказе вручную. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Xendit.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Xendit Payment Gateway — первый блок на странице Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-xendit и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Менять ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку бэк-офиса (включены английский и русский).

Если ключ не принят, блок объясняет причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения места для домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

Без активного ключа Xendit не показывается покупателям на оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать на оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически перепроверяется во время работы в бэк-офисе: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

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

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

Платёж прошёл, но заказ не создан: вебхук не работает. В Xendit Dashboard того режима, который вы используете (тестового или рабочего), проверьте, что URL из поля Webhook 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 и токена. Ignored: unknown order и Ignored: unknown invoice означают, что корзина или счёт этому магазину неизвестны.

Вебхук отвечает Temporary error: не удалось обратиться к API Xendit для проверки счёта, не задан секретный ключ режима счёта, корзину в этот же момент обновлял другой запрос, либо заказ не удалось создать (например, модуль отключён). Xendit повторит вебхук. Проверьте, что заданы оба секретных ключа, если платежи начинались в обоих режимах, и включите Debug Log, чтобы увидеть причину.

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Xendit.

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

Покупатель видит This payment method is temporarily unavailable: Xendit отклонил запрос, например потому что секретный ключ неверен или у него нет права записи для Money-in (счета). Посмотрите поле Log на странице модуля. Сообщение о платёжных данных означает, что Xendit не принял данные запроса, например e-mail.

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

Покупатель видит We could not match this payment to an order: ссылка возврата от Xendit не относится ни к одной корзине этого магазина, либо ни один счёт корзины не удалось сопоставить. Проверьте платёж в Xendit Dashboard и журнале.

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

Для разработчиков модуль предоставляет хуки actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies и actionWcpXenditCurrencyDecimals для изменения запроса счёта, списка валют и количества знаков после запятой для каждой валюты.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Xendit Payment Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки модуля и журнал удаляются. Если выключено, все настройки сохраняются для будущей переустановки. Данные счетов Xendit по заказам и статус заказа Xendit payment on hold всегда сохраняются. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

Xendit — товарный знак его владельца. Этот модуль не аффилирован с Xendit и не одобрен Xendit.