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

Вимоги

PrestaShop: від 8.0 до 9.x.

PHP: 8.0 або новіша. Модуль відмовляється встановлюватися на старіших версіях PHP.

Доступ до магазину: ваш магазин має бути доступний з інтернету та використовувати 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 сам визначає, які способи оплати пропонувати для країни покупця та валюти кошика. Діють лише обмеження оплати PrestaShop.

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

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

1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox dLocal Payment у списку модулів і натисніть Configure.

3. Вставте ліцензійний ключ VibeFox у License key у блоці ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

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

5. Увімкніть Enable/Disable і натисніть Save. Перевірте платіж у sandbox, потім переключіть Environment на Production.

Під час встановлення модуль створює статус замовлення dLocal payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Обмежити їх можна в Payment > Preferences.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox dLocal Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. У заголовку першого розділу відображається SANDBOX або PRODUCTION. Поки не введено API-ключ і секрет обраного середовища, сторінка попереджає, що спосіб оплати прихований під час оформлення замовлення, наприклад Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Коли обрано sandbox і спосіб оплати увімкнено, відображається Sandbox mode is active: payments are simulated, no money is charged.

dLocal Go

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 (sandbox) або dashboard.dlocalgo.com (production). У розділі є посилання на обидві панелі.

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

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

Sandbox API Key: ваш API-ключ sandbox dLocal Go.

Sandbox API Secret: ваш API-секрет sandbox dLocal Go.

Production API Key: ваш API-ключ production dLocal Go.

Production API Secret: ваш API-секрет production dLocal Go.

Збережені ключі та секрети більше не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved credentials: позначте ключ або секрет і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

Оплата

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

Auto-complete orders: переводить оплачені замовлення в статус Delivered замість Payment accepted. Статус встановлюється одразу, однією зміною. За замовчуванням: вимкнено.

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

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

Додатково

Debug log: записує запити та сповіщення dLocal Go у файл logs/dlocal_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. API-облікові дані та персональні дані не записуються. Помилки та попередження записуються завжди; решта записів — лише поки цю опцію увімкнено. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування шлюзу та журнал. Платіжні дані замовлень (платежі та повернення dLocal) і статус замовлення dLocal payment on hold завжди зберігаються, тож наявні замовлення продовжують працювати. За замовчуванням: вимкнено.

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

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

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження dLocal Go: за підписаним сповіщенням або серверним запитом до API dLocal Go, коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з Your payment with dLocal Go has been received. Якщо замовлення було переведено на утримання, сторінка показує Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Якщо dLocal Go ще не підтвердив платіж (наприклад, ваучер для оплати готівкою ще не оплачено або dLocal Go був недоступний), сторінка Payment confirmation просить покупця не платити повторно й пропонує Check again і Back to checkout. Замовлення створюється, щойно dLocal Go підтверджує платіж.

Якщо покупець залишає сторінку dLocal Go без оплати, він повертається до оформлення замовлення і бачить 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 Go не може розпочати платіж, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад dLocal could not start the payment:, після якого вказано причину від dLocal. Так буває й тоді, коли країна покупця та валюта кошика не увімкнені у вашому обліковому записі dLocal Go. Якщо dLocal Go відхиляє ваші облікові дані, покупець бачить This payment method is temporarily unavailable. Please choose another payment method or contact us. Технічна причина записується в журнал.

Сповіщення працюють, поки магазин перебуває в режимі обслуговування, і не блокуються обмеженням за країною вашого магазину.

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

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

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

Замовлення ще немає: покупця перенаправлено на dLocal Go, і він не оплатив, або платіж ще очікує в dLocal Go. Існує лише кошик.

Payment accepted або Delivered: платіж підтверджено. Замовлення отримує статус «Оплату прийнято» або, якщо увімкнено Auto-complete orders, статус «Доставлено». Платіж записується з ID платежу dLocal як ID транзакції, а нотатка показує середовище та ID платежу.

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

Refunded: платіж повністю повернено через модуль.

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

Блок оплати dLocal Go

На сторінці замовлення є блок dLocal Go payment з ID платежу dLocal, середовищем (зі значком Sandbox для тестових платежів), статусом платежу, сумою, списаною dLocal Go, і поверненою сумою, формою повернення, історією повернень і dLocal Go notes замовлення.

Повернення

У блоці dLocal Go payment введіть суму (неповернена сума підставляється автоматично), за потреби причину, і натисніть Refund via dLocal Go. Підтвердіть питання Refund this amount through dLocal Go? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок Modules не потрібен. Повернення здійснюються в сумі та валюті, які списав dLocal Go, тож після розбіжності суми чи валюти можна повернути до тієї суми, яку покупець фактично сплатив, а не до загальної суми замовлення. Повернення надсилається в середовище, де було здійснено платіж, з обліковими даними цього середовища. Якщо dLocal Go не приймає повернення, блок показує помилку, і повернення не записується. Прийняте повернення додається до історії повернень і нотаток з ID повернення, статусом і причиною. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

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

Модуль не створює кредитових накладних (credit slip). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через dLocal Go. Повернення, зроблені в панелі dLocal Go, не реєструються в PrestaShop як повернення і зазвичай не додають нотатку. За потреби оновіть замовлення вручну.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox dLocal Payment є першим блоком на сторінці Modules > Module Manager > VibeFox dLocal Payment > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовано рядок Product: presta-payment-dlocal і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

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

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

Без активного ключа dLocal Go не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви ввійшли в back office, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але перевірити його під час оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, все одно підтверджуються, а повернення працюють.

Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, поки ви працюєте в back office: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

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

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

Платіж пройшов, але замовлення не створено: dLocal Go не зміг звернутися до адреси сповіщення (брандмауер, базова автентифікація, немає публічної адреси), а покупець не повернувся до магазину. Увімкніть Debug log, перегляньте поле Log і перевірте платіж у панелі dLocal Go. Щойно надійде сповіщення або покупець натисне Check again, замовлення буде створено.

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

Сповіщення відповідає Gateway not configured: облікові дані середовища платежу не заповнені. Введіть їх; dLocal Go повторить сповіщення.

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

Сповіщення відповідає Temporarily unavailable: замовлення в цей самий момент підтверджувалося іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). dLocal Go повторить сповіщення. Причина вказана в журналі.

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

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

Покупець бачить Payment gateway is not properly configured: облікові дані обраного середовища не заповнені.

Замовлення має статус dLocal payment on hold після оплати: прочитайте нотатки в блоці dLocal Go payment. Сплачена сума або валюта відрізнялися від кошика, або платіж надійшов після скасування замовлення. Виконайте замовлення або поверніть платіж.

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

Для розробників: документація модуля перелічує хуки actionWcpDlocalPaymentData та actionWcpDlocalCurrencyDecimals.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox dLocal Payment і виберіть Uninstall. Ключ ліцензії та статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування шлюзу та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Платежі та повернення dLocal за замовленнями та статус замовлення dLocal payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої платіжні нотатки та ID транзакцій.

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