VibeFox dLocal for WooCommerce — Допомога

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 7.0 або новіша, встановлений і активний.

PHP: 8.0 або новіша. На старішій версії PHP або WordPress плагін не активується.

Доступність сайту: ваш сайт має бути доступним з інтернету і використовувати HTTPS у робочому середовищі, щоб dLocal Go міг доставляти сповіщення про платежі. Їх може блокувати файрвол, режим обслуговування або базова автентифікація.

Обліковий запис dLocal Go: потрібні API-ключ і API-секрет з панелі dLocal Go, розділ Payment integration: dashboard-sbx.dlocalgo.com для тестового середовища, dashboard.dlocalgo.com для робочого. Тестове та робоче середовище використовують різні облікові дані. Корпоративний API dLocal Payments (облікові дані X-Login / X-Trans-Key) — інший продукт, і він не підтримується.

Країни та валюти: плагін їх не обмежує. dLocal Go сам вирішує, які способи оплати пропонувати для країни покупця та валюти магазину.

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

Встановлення

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити теку wcp_dlocal_payment до /wp-content/plugins/ через FTP.

2. Натисніть Activate. WooCommerce має бути активним.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > dLocal Go > Manage або натисніть Settings під назвою плагіна на сторінці «Плагіни».

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки і натисніть Activate.

5. Виберіть Environment і вставте API-ключ та API-секрет цього середовища (див. «Налаштування»).

6. Увімкніть Enable/Disable і збережіть. Перевірте платіж у тестовому середовищі, потім перемкніть Environment на Production.

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

Усі налаштування розміщено на одній сторінці: WooCommerce > Settings > Payments > dLocal Go. У заголовку сторінки показано SANDBOX або PRODUCTION. Доки не введено API-ключ і секрет вибраного середовища, сторінка попереджає, що спосіб оплати приховано на сторінці оформлення замовлення. Поки вибрано тестове середовище і шлюз увімкнено, на ній показано Sandbox mode is active: payments are simulated, no money is charged. У списку способів оплати dLocal Go позначено як такий, що потребує налаштування, доки не задано облікові дані, а в тестовому середовищі показано Test mode.

Загальні

Enable/Disable: Enable dLocal Go вмикає або вимикає спосіб оплати. Типово: вимкнено.

Title: назва способу оплати, яку покупці бачать під час оформлення замовлення. Типово: dLocal Go.

Description: текст під способом оплати на сторінці оформлення замовлення. Типово: Pay with local cards, bank transfer or cash via dLocal Go.

Облікові дані API

Скопіюйте API-ключ і API-секрет з панелі dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (тестове середовище) або dashboard.dlocalgo.com (робоче середовище). Усі поля облікових даних — поля пароля.

Environment: які облікові дані та які сервери dLocal Go використовуються.

Sandbox (test): тестові платежі з обліковими даними тестового середовища (типово).

Production: реальні платежі з обліковими даними робочого середовища.

Sandbox API Key: ваш API-ключ dLocal Go для тестового середовища.

Sandbox API Secret: ваш API-секрет dLocal Go для тестового середовища.

Production API Key: ваш API-ключ dLocal Go для робочого середовища.

Production API Secret: ваш API-секрет dLocal Go для робочого середовища.

Оплата

Default country: dLocal Go показує способи оплати країни покупця, взятої з платіжної адреси, а потім з адреси доставки. Ця країна використовується, коли в замовленні немає жодної з них. Типово: Uruguay.

Auto-complete orders: Set paid orders to "Completed" instead of "Processing". Статус встановлюється одразу, з одним набором листів. Типово: вимкнено.

Сповіщення (IPN)

Сповіщення повідомляють магазину, що платіж або повернення коштів змінилися. Плагін передає URL сповіщень до dLocal Go з кожним платежем і поверненням, тому в панелі dLocal Go нічого налаштовувати не потрібно. У цьому розділі налаштувань показано обидва URL:

Payment IPN: має вигляд https://your-site/wc-api/dlocal_p_ipn/ (на сайтах без людинозрозумілих постійних посилань — /?wc-api=dlocal_p_ipn).

Refund IPN: має вигляд https://your-site/wc-api/dlocal_p_refund_ipn/.

Сповіщення перевіряються вашим API-секретом (HMAC-SHA256). Сповіщення без дійсного підпису відхиляються. Після цього статус, сума та валюта платежу завжди повторно зчитуються з API dLocal Go; вмісту сповіщення плагін не довіряє. Без сповіщень замовлення оновлюється лише тоді, коли покупець повертається до магазину.

Додатково

Debug log: Log API requests and notifications записує подробиці до WooCommerce > Status > Logs, джерело wcp_dlocal_payment, без облікових даних API та персональних даних. Помилки записуються завжди. Типово: вимкнено.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Типово: вимкнено.

Оформлення замовлення

Покупець вибирає спосіб оплати (типово dLocal Go) і оформлює замовлення. Плагін створює платіж dLocal Go на загальну суму замовлення у валюті замовлення, з країною, іменем, e-mail і телефоном покупця, та надсилає покупця на платіжну сторінку dLocal Go. Там покупець платить способом своєї країни. На сторінці dLocal Go платіж відображається як Order # і номер замовлення. У тестовому режимі на сторінці оформлення замовлення під способом оплати показано Sandbox mode: no real payment is made.

Після оплати покупець повертається на сторінку «Замовлення отримано» вашого магазину. Замовлення позначається оплаченим лише після підтвердження від dLocal Go: за підписаним сповіщенням або за серверним запитом до API dLocal Go, коли покупець потрапляє на цю сторінку.

Якщо покупець залишив сторінку dLocal Go без оплати, він повертається на сторінку оформлення замовлення (або на сторінку Pay for order) і бачить The payment at dLocal Go was not completed. You can try again or choose another payment method. Якщо платіж відхилено або його термін минув, повідомлення таке: Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. Якщо виявиться, що оплата вже пройшла, покупця перенаправляють на сторінку «Замовлення отримано». Старіше платіжне посилання того самого замовлення можна оплатити і після повторної спроби.

Якщо dLocal Go не може розпочати платіж, покупець бачить коротке повідомлення без технічних подробиць, наприклад dLocal could not start the payment: з причиною від dLocal, і може вибрати інший спосіб. Так буває й тоді, коли країну покупця та валюту магазину не ввімкнено у вашому обліковому записі dLocal Go. Технічна причина записується до журналу.

Спосіб оплати працює в класичному оформленні замовлення, у блоці «Оформлення замовлення» і на сторінці Pay for order. Він сумісний з високопродуктивним сховищем замовлень WooCommerce (HPOS).

Плагін приймає лише разові платежі на сторінці dLocal Go. У ньому немає форми картки на вашому сайті, збережених карток, підписок і окремих авторизації та списання коштів.

Замовлення та повернення коштів

Статуси замовлення

Pending payment: покупця надіслано до dLocal Go, і він ще не заплатив, або платіж очікує в dLocal Go (наприклад, ваучер для оплати готівкою ще не оплачено). Кожна нова спроба оплати записується в замовлення з її ID платежу dLocal, сумою та середовищем.

Processing or Completed: платіж підтверджено. Замовлення має статус «Обробляється» (типово у WooCommerce) або «Виконано», якщо увімкнено Auto-complete orders. ID транзакції — це ID платежу dLocal.

On hold: dLocal Go повідомив суму або валюту, що відрізняється від загальної суми замовлення, або платіж надійшов після скасування замовлення. Нотатка до замовлення пояснює причину. Звірте з панеллю dLocal Go і виконайте замовлення або поверніть платіж.

Failed: останню спробу оплати відхилено або її термін минув. Покупець може спробувати знову.

Cancelled: dLocal Go повідомив, що останню спробу оплати скасовано.

Лише остання спроба оплати може перевести неоплачене замовлення в статус «Невдалий» або «Скасовано». Оплачене замовлення ніколи не відкривається знову через старе сповіщення. Якщо за вже оплаченим замовленням надходить другий платіж, замовлення не змінюється. Нотатка просить вас повернути дубльований платіж у панелі dLocal Go.

Повернення коштів

Відкрийте замовлення, натисніть Refund, введіть суму і натисніть Refund via dLocal Go. Повні та часткові повернення підтримуються для замовлень, оплачених через dLocal Go. Повернення надсилається до того середовища, в якому було здійснено платіж, з обліковими даними цього середовища. Якщо dLocal Go не приймає повернення, WooCommerce показує помилку, і повернення не записується. Прийняте повернення додається до нотаток замовлення з ID та статусом повернення.

Потім dLocal Go повідомляє остаточний статус повернення сповіщенням про повернення, і він додається до нотаток замовлення. Якщо пізніше dLocal Go відхилить або скасує повернення, яке раніше прийняв, нотатка попередить, що гроші не повернулися покупцю. Перевірте записане для нього повернення WooCommerce: видаліть його і зробіть повернення знову або поверніть кошти покупцю іншим способом.

Повернення, зроблені в панелі dLocal Go, не записуються як повернення WooCommerce і зазвичай не додають нотатку до замовлення. За потреби створіть ручне повернення у WooCommerce без Refund via dLocal Go.

Ліцензійний ключ

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розміщено вгорі сторінки WooCommerce > Settings > Payments > dLocal Go. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Check now — перевірити статус знову, Change key — ввести інший ключ, Remove key — видалити ключ з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

Один ключ працює на одному домені. Видалення ключа із сайту не звільняє слот його домену. Звільніть слот в обліковому записі vibefox.net.

Без активного ключа dLocal Go не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Менеджери магазину, які увійшли в систему, і далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), тож ви можете налаштувати й перевірити плагін до купівлі ключа. Нагадування з'являється на сторінці «Плагіни» та на сторінках WooCommerce. Наявних замовлень це не стосується: уже розпочаті платежі й далі підтверджуються, а повернення коштів працюють.

Коли ліцензія спливає, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично повторно перевіряється у фоновому режимі.

Усунення несправностей

dLocal Go не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а API-ключ і API-секрет вибраного Environment задано. Якщо їх немає, сторінка налаштувань показує попередження.

Платіж пройшов, але замовлення залишається «Очікує оплати»: dLocal Go не зміг звернутися до URL сповіщень (файрвол, режим обслуговування, базова автентифікація), а покупець не повернувся на сторінку «Замовлення отримано». Перевірте WooCommerce > Status > Logs, джерело wcp_dlocal_payment, і платіж у панелі dLocal Go. Щойно надійде сповіщення або покупець відкриє сторінку «Замовлення отримано», замовлення оновиться.

Сповіщення відповідає Missing signature або Invalid signature: API-ключ і секрет у налаштуваннях не належать обліковому запису, який надіслав сповіщення. Сповіщення перевіряються обліковими даними обох середовищ, тому платежі, розпочаті до перемикання Environment, і далі підтверджуються, доки облікові дані їхнього середовища залишаються в налаштуваннях.

Сповіщення відповідає Gateway not configured: немає облікових даних вибраного середовища. dLocal Go повторить сповіщення.

Сповіщення відповідає API verification failed: не вдалося звернутися до API dLocal Go, щоб прочитати платіж. dLocal Go повторить сповіщення.

Сповіщення відповідає Order not found: платіж не належить до замовлення цього магазину, наприклад його створив інший сайт з тим самим обліковим записом dLocal Go.

Покупець бачить This payment method is temporarily unavailable: dLocal Go відхилив API-ключ або секрет. Перевірте облікові дані вибраного середовища.

Замовлення «На утриманні» після оплати: прочитайте нотатку до замовлення. Сплачена сума або валюта відрізнялися від замовлення, або платіж надійшов після скасування замовлення. Виконайте замовлення або поверніть платіж.

Повернення не вдається з повідомленням про відсутні облікові дані: платіж було здійснено в іншому середовищі, і його облікові дані не задано. Введіть їх і спробуйте знову.

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Для розробників: у документації плагіна перелічено фільтри dlocal_p_payment_data, dlocal_p_currency_decimals і dlocal_p_icon.

Видалення

Під час деактивації плагіна всі дані зберігаються. Щоб видалити його, деактивуйте та видаліть його на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна видаляються завжди. Налаштування шлюзу та журнали видаляються, лише якщо було увімкнено Delete data on uninstall. Інакше вони залишаються для подальшого перевстановлення. Наявні замовлення зберігають свої нотатки про оплату та ID транзакцій.

dLocal — торговельна марка відповідного власника. Цей плагін не пов'язаний з dLocal і не схвалений нею.