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.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. У тестовому режимі блок Checkout показує під способом оплати 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 і не схвалений Xendit.