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 не приймає десяткових значень для цих валют. Електронна адреса покупця передається в 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 не прийняв дані запиту, наприклад електронну адресу.

Покупець бачить 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.