VibeFox Xendit for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Загрузка — это один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_xendit_payment_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_xendit_payment_gateway.ocmod.zip. Устанавливайте только пакет для своей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_xendit_payment_gateway-oc3-(version).ocmod.zip. У расширения нет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Xendit Payment Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю администратора нужно право изменять список расширений оплаты.

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

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

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

OpenCart 4

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_xendit_payment_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, а переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите Install (зелёная кнопка +) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Xendit Payment Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, ключи Xendit и вебхук так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL вебхука (см. Webhooks).

После новой установки способ оплаты выключен, а тестовый режим включён.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Без права изменять расширение страница показывает настройки, но не может их сохранить.

Над настройками блок показывает активный режим: TEST MODE (счета создаются с тестовым секретным ключом; реальные деньги не списываются) или LIVE MODE (счета создаются с рабочим секретным ключом, и покупатели платят реальные деньги). Страница предупреждает, если секретный ключ активного режима отсутствует или имеет неверный префикс (тогда способ оплаты скрывается на оформлении заказа), а также если токен верификации вебхука активного режима пуст (уведомления Xendit тогда отклоняются, и заказы обновляются только когда покупатель возвращается в магазин).

При сохранении поле Title не должно быть пустым (не более 128 символов), Sort Order должно быть целым числом (отрицательные числа допускаются), Total должно быть числом, 0 или больше, а геозона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница называет поле.

Xendit

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

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

Description: текст, который показывается покупателю на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Sort Order: положение Xendit среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Xendit только для адресов оплаты в выбранной геозоне. По умолчанию: All zones. Геозоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагался Xendit. Оставьте поле пустым, чтобы предлагать 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: создаёт счета с тестовым секретным ключом, поэтому реальные деньги не списываются. По умолчанию: on. Выключите, чтобы принимать реальные платежи с рабочим секретным ключом. Пока он включён, покупатели видят на шаге Confirm Order надпись 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. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённое значение, отметьте Clear the saved value под полем и нажмите Save.

Webhooks

Вебхук сообщает вашему магазину, что счёт оплачен. В Xendit Dashboard > Settings > Developers > Webhooks (в разделе есть ссылка туда) задайте URL из поля Webhook URL для Invoices > Invoice paid, в тестовом и в рабочем режиме. По желанию задайте его и для Invoice expired. На OpenCart 3 URL выглядит так: https://your-store/index.php?route=extension/payment/wcp_xendit_payment_gateway/webhook, на OpenCart 4 так: https://your-store/index.php?route=extension/wcp_xendit_payment_gateway/payment/wcp_xendit_payment_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. Копируйте его точно так, как он показан в настройках. Он должен быть доступен из интернета.

Затем скопируйте 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} (оба — номер заказа OpenCart) и {site_name} (название магазина). HTML удаляется, текст обрезается до 255 символов. По умолчанию: Order #{order_id}.

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

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только после того, как Xendit подтвердил платёж через API. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Paid Order Status: статус после подтверждённого платежа с Processing. По умолчанию: Processing.

Complete Order Status: статус после подтверждённого платежа с Completed. По умолчанию: Complete.

On Hold (Review) Status: счёт оплачен на другую сумму или в другой валюте, чем заказ (корзину изменили после создания счёта, или это частичная оплата). Примечание объясняет причину. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Свой статус можно создать в System > Localisation > Order Statuses и выбрать здесь.

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

Debug Log: записывает запросы к API и вебхуки в файл xendit_p_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть из браузера; при достижении 5 МБ он переименовывается в xendit_p_debug.old.log.php. Ошибки и предупреждения записываются всегда, даже когда эта опция выключена. Ключи API, токены и данные покупателей в журнал не попадают. По умолчанию: off.

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

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

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Секретные ключи и токены не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секретные ключи и токены сохраняются.

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

Способ оплаты показывается, когда валюта оформления заказа — IDR, PHP, VND, THB, MYR, USD или SGD. Покупатель выбирает его на шаге Payment Method (по умолчанию Xendit). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт счёт Xendit на сумму заказа в валюте заказа и отправляет покупателя на страницу счёта Xendit. Суммы в IDR и VND округляются до целых чисел, так как Xendit не принимает для них десятичные знаки. Адрес электронной почты покупателя передаётся в Xendit. На странице счёта покупатель платит одним из платёжных каналов, активированных в вашем аккаунте Xendit для этой валюты, например виртуальным счётом, электронным кошельком, QR-кодом, точкой розничной продажи или картой. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Xendit: через вебхук или через серверный запрос к API Xendit, когда покупатель возвращается. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если Xendit ещё не подтвердил платёж, страница Payment confirmation показывает Your payment has not been confirmed by Xendit yet. Your order will be confirmed 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. Корзина сохраняется.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order. OpenCart 4 оставляет один заказ для оформления и обновляет его, поэтому после неудачного или истёкшего счёта следующее нажатие Confirm Order создаёт новый счёт для того же заказа. Если другой заказ из той же корзины уже оплачен, покупатель сразу переходит на страницу успеха и не платит дважды. Если сумма заказа, валюта и режим не изменились, а открытый счёт этого заказа ещё действителен не менее пяти минут, покупатель отправляется на тот же счёт. Иначе старый счёт сначала аннулируется и создаётся новый, поэтому для одной корзины никогда не бывает двух открытых счетов. Если старый счёт уже оплачен, подтверждается именно этот платёж, а не создаётся новый.

На OpenCart 4, если заказ оформления был закрыт магазином (например, отменён или возвращён) или уже оплачен, но корзина с тех пор изменилась, в том числе новым количеством, покупатель возвращается к оформлению с сообщением Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order., и следующее нажатие Confirm Order оплачивает новый заказ. На OpenCart 4 это сообщение, сообщение о незавершённом платеже и We could not match this payment to an order. If you were charged, please contact us. показываются над страницей оформления заказа.

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

Вебхук и возврат покупателя также работают, пока магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а на OpenCart 4 расширение добавляет для них стартовое действие.

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

Заказы

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

Нет статуса (отсутствующий заказ): покупатель был отправлен в Xendit и не оплатил, либо Xendit ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в Missing Orders.

Paid Order Status или Complete Order Status (по умолчанию Processing или Complete): платёж подтверждён. Статус соответствует Order Status After Payment. Примечание показывает идентификатор счёта, оплаченную сумму, платёжный канал и режим.

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

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

Примечания — это записи в History заказа, которых покупатель не видит. Они начинаются со слова Xendit.

Вкладка VibeFox Xendit Payment Gateway

В Sales > Orders откройте заказ, оплаченный через Xendit. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Xendit Payment Gateway показывает Xendit invoice, Mode (с пометкой Test для тестовых платежей), Status платежа, таблицу Invoices of this order and its cart (дата, заказ, идентификатор счёта, внешний идентификатор, режим, сумма, оплаченная сумма, статус, платёжный канал) и Payment notes заказа. Вкладка видна пользователям, у которых есть доступ к расширению.

Возвраты

Возвраты из магазина в Xendit не отправляются. Верните платёж в Xendit Dashboard (найдите идентификатор счёта, указанный на вкладке), а затем измените статус заказа в OpenCart. Возвраты товаров в Sales > Returns не возвращают деньги через Xendit.

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

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

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

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

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

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

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

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

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

Webhook answers Webhook verification token is not configured: не задан ни один токен верификации. Вставьте токен в настройки.

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

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

Webhook answers Ignored: not an invoice of this store: счёт создан не этим магазином, например другой интеграцией в том же аккаунте Xendit. Кнопка Test в Xendit Dashboard тоже получает этот ответ, что подтверждает работу URL и токена. Ignored: unknown order и Ignored: unknown invoice означают, что заказ или счёт этому магазину неизвестны.

Webhook answers 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 не принял данные запроса, например адрес электронной почты.

Покупатель видит 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 и в журнале.

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

Для разработчиков: расширение вызывает события OpenCart xendit_p_invoice_request, xendit_p_supported_currencies и xendit_p_currency_decimals, чтобы изменить запрос счёта, список валют и количество десятичных знаков для каждой валюты.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Xendit Payment Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Payment, которые при повторной установке возвращаются к значениям по умолчанию. На OpenCart 4 также удаляются событие расширения и его стартовое действие, которое в режиме обслуживания пропускает вебхук и возврат покупателя. Если Delete Data on Uninstall включено, удаляются остальные настройки шлюза (название, описание, тестовый режим, ключи, токены, описание счёта, статус заказа после оплаты, ведение журнала) и журнал. Если выключено, они сохраняются для последующей повторной установки. Данные счетов Xendit по заказам всегда сохраняются. Существующие заказы сохраняют свои примечания об оплате.

На OpenCart 4, чтобы удалить и файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Xendit Payment Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Xendit является товарным знаком его владельца. Это расширение не связано с Xendit и не одобрено Xendit.