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 вебхука (див. Вебхуки).

Нове встановлення починається з вимкненим способом оплати і увімкненим тестовим режимом.

Налаштування

Усі налаштування розташовані на сторінці розширення: 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. Вимкніть його, щоб приймати реальні платежі з робочим секретним ключем. Поки його увімкнено, покупці бачать Test mode: no real money is charged. на кроці Confirm Order.

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.