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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: бразильський реал (BRL). Спосіб оплати показується лише для кошиків у BRL.

HTTPS: ваш магазин має бути доступний з інтернету через HTTPS, щоб PagBank міг надсилати сповіщення про платежі.

Обліковий запис PagBank: токен продуктивного режиму для реальних платежів і токен sandbox для тестів. Продуктивний режим: увійдіть в обліковий запис PagBank, відкрийте Venda online > Integrações і натисніть Gerar token; PagBank надішле токен електронною поштою. Sandbox: створіть обліковий запис sandbox на порталі розробників PagBank і скопіюйте його токен. Токени sandbox і продуктивного режиму працюють лише у своєму середовищі.

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

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

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

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

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

4. Введіть токен sandbox і, щоб приймати реальні платежі, токен продуктивного режиму.

5. Увімкніть Enable / Disable і натисніть Save. Робіть тестові платежі з увімкненим Sandbox Mode, а потім вимкніть його, щоб приймати реальні платежі.

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

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує поточний режим: SANDBOX MODE (платежі створюються в sandbox PagBank, без реальних списань) або LIVE (платежі створюються з токеном продуктивного режиму). Сторінка попереджає, коли токен поточного режиму відсутній (тоді спосіб оплати прихований на оформленні замовлення), і коли основна валюта магазину не BRL (тоді спосіб оплати не пропонується для кошиків в інших валютах).

PagSeguro / PagBank

Enable / Disable: Enable PagSeguro/PagBank payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачать покупці під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: PagSeguro / PagBank. Обов'язково.

Description: текст під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Обліковий запис PagBank

Розділ пояснює, де отримати токени, і містить посилання на ваш обліковий запис PagBank та сторінку PagBank про токени.

Sandbox Mode: Enable sandbox/test mode (no real charges). Нові платежі надсилаються в sandbox PagBank з токеном sandbox, а покупці бачать під способом оплати SANDBOX MODE — Using test environment. No real charges. Перевірки статусу та повернення коштів за замовленням завжди використовують середовище й токен, з якими було створено його платіж. За замовчуванням: увімкнено.

Sandbox token: токен sandbox PagBank. Використовується, поки увімкнено режим sandbox.

Production token: токен продуктивного режиму PagBank (Bearer). Використовується, коли режим sandbox вимкнено. Тримайте його в таємниці.

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

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

Сповіщення про платежі

Notification URL: кожен платіж повідомляє PagBank, куди надсилати зміни статусу, тому в PagBank нічого налаштовувати не потрібно. Розділ показує URL. З увімкненими зрозумілими посиланнями він має такий вигляд: https://your-shop/module/wcp_pagseguro_gateway/webhook. Адреса має бути доступна з інтернету через HTTPS.

Сповіщення з заголовком x-authenticity-token перевіряються токеном того середовища, в якому було створено платіж; недійсний підпис відхиляється. Саме тіло сповіщення ніколи не вважається надійним: модуль завжди зчитує платіж і замовлення PagBank через API PagBank (статус, сума, валюта) перед створенням або зміною замовлення. Без сповіщень замовлення створюється, коли покупець після оплати повертається до магазину.

Додатково

Debug log: Log API requests and notifications записує деталі у logs/wc_psg_debug.log.php у папці модуля. Файл не можна відкрити з веб. Журнали не містять токенів і даних покупців. Помилки завжди записуються. За замовчуванням: вимкнено.

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

Delete Data on Uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування шлюзу та журнал. Замовлення, їхні посилання PagBank (потрібні для повернень) і статуси замовлень завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням PagSeguro / PagBank) і підтверджує. Модуль створює в PagBank платіж на суму кошика в BRL як одну позицію, Order # з номером кошика та назвою вашого магазину, і надсилає покупця на сторінку оплати PagBank. Ім'я та e-mail покупця, CPF або CNPJ з поля Identification number або VAT number адреси та бразильський номер телефону заповнюються, якщо вони є в магазині; покупець може доповнити або виправити їх на сторінці PagBank. Покупець платить способами, увімкненими у вашому обліковому записі PagBank, наприклад кредитною карткою, PIX або boleto. Сторінка оплати спливає через 120 хвилин. На цьому етапі замовлення ще немає.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження PagBank: модуль зчитує платіж через API PagBank, коли надходить сповіщення або коли покупець повертається, і саме лише повернення ніколи не позначає замовлення оплаченим. Далі замовлення створюється, і покупець бачить сторінку підтвердження замовлення з написом Your payment with PagBank has been received. Для створеного boleto або PIX чи платежу на перевірці сторінка показує Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Якщо такий платіж пізніше відхиляється або скасовується, сторінка показує Your PagBank payment was not completed. Please contact us about this order. Якщо PagBank ще не підтвердив платіж, коли покупець повертається, з'являється сторінка Payment confirmation з текстом We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. та кнопкою Check again.

Якщо платіж не було завершено, покупець повертається до оформлення замовлення з повідомленням The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. або The payment was declined by PagBank. Please try again with another card or payment method. Кошик зберігається. Якщо замовлення, що очікувало оплати boleto або PIX, було скасовано, покупець бачить The PagBank payment was cancelled, so the order was cancelled.

Коли покупець платить знову, відкритий платіж PagBank використовується повторно, якщо сума та середовище ті самі і він не спливає протягом наступних 10 хвилин. Інакше попередній платіж деактивується, і його не можна оплатити. Платіж, зроблений раніше на попередній сторінці, усе одно зараховується до кошика, і створюється замовлення замість нового платежу.

Якщо PagBank не може розпочати платіж, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. або Could not connect to PagBank. Please try again in a moment. Технічна причина записується в журнал.

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

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

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

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

Замовлення ще немає: покупця було перенаправлено до PagBank, і він не заплатив, картку відхилено або сторінка оплати спливла. Існує лише кошик, і покупець може оплатити знову.

Payment accepted: платіж підтверджено з очікуваними сумою та валютою. Платіж фіксується з ідентифікатором списання PagBank (charge ID) як ID транзакції, а примітка показує суму, спосіб оплати та charge ID.

Awaiting PagBank payment: boleto або PIX створено і очікує оплати, або платіж на перевірці. Замовлення переходить у Payment accepted, коли PagBank повідомляє про оплату.

PagBank payment on hold: PagBank повідомив суму або валюту, які відрізняються від кошика (наприклад, кошик було змінено після створення сторінки оплати), платіж надійшов після скасування замовлення (перевірте залишки, потім завершіть замовлення або поверніть платіж у PagBank), або платіж карткою авторизовано, але не списано (списати його в PagBank). Примітка пояснює це. Фактично отримані кошти фіксуються в замовленні.

Payment error: платіж, що очікував оплати або перебував на перевірці, було відхилено.

Canceled: платіж, що очікував оплати, наприклад прострочений boleto або PIX, було скасовано.

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

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

Блок «PagBank payment»

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

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

У блоці PagBank payment введіть суму (неповернена сума підставляється автоматично), за бажанням причину, і натисніть Refund via PagBank. Підтвердьте запитання Refund this amount through PagBank? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Ліміт — сума, яку списала PagBank, тож після розбіжності суми можна повернути до тієї суми, яку покупець фактично сплатив, а не до суми замовлення. Повернення надсилається в тому середовищі та з тим токеном, з якими було зроблено платіж. Повернення фіксується, лише коли PagBank його підтверджує; інакше блок показує помилку, наприклад PagBank refund failed: ... або PagBank did not confirm the refund, і нічого не фіксується. Повернення платежів boleto та часткові повернення PIX виконуються за правилами PagBank. Успішне повернення додається до історії повернень і приміток разом із charge ID. Повне повернення переводить замовлення у статус Refunded; часткове повернення статус не змінює. Повернення доступні після того, як PagBank повідомив, що платіж оплачено.

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через PagBank.

Повернення, зроблені в кабінеті PagBank, стають видимими з наступним сповіщенням: повне повернення переводить замовлення у статус Refunded, часткове повернення додає примітку з поверненою сумою, а повернення можна внести в замовлення вручну.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox PagSeguro Gateway є першим блоком на сторінці Modules > Module Manager > VibeFox PagSeguro Gateway > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розміщено рядок Product: presta-payment-pagseguro і посилання 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.

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

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

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

PagBank не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, токен поточного режиму заповнено (Sandbox token у режимі sandbox, Production token у режимі live) і валюта кошика — BRL. Сторінка налаштувань показує попередження, коли токен відсутній або валюта магазину не BRL. У Payment > Preferences перевірте, що модуль дозволений для BRL, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: PagBank ще не повідомив про платіж, а покупець не повернувся до магазину. Замовлення створюється одразу, як надходить сповіщення. Перевірте, що ваш магазин доступний з інтернету через HTTPS за адресою Notification URL, і увімкніть Debug log, щоб бачити сповіщення.

Сповіщення відповідає Invalid signature: x-authenticity-token не збігається з токеном того середовища, в якому було зроблено платіж, або цей токен не збережено. Перевірте, що в налаштуваннях є правильний токен.

Сповіщення відповідає Verification failed, retry later: не вдалося звернутися до API PagBank, бракує токена середовища платежу, або кошик у той самий момент оброблявся іншим запитом. PagBank повторить сповіщення.

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

Покупець бачить PagBank payments are temporarily unavailable. Please choose another payment method.: токен поточного режиму відсутній або PagBank його відхилив.

Покупець бачить PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: кошик у іншій валюті.

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

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

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox PagSeguro Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування шлюзу та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Платежі та повернення PagBank за замовленнями, а також статуси замовлень Awaiting PagBank payment і PagBank payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ID транзакцій.

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