VibeFox Pagar.me for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

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

Обліковий запис Pagar.me: вам потрібні секретні ключі вашого облікового запису Pagar.me: тестовий ключ (sk_test_...) і, щоб перейти в робочий режим, робочий ключ (sk_...). Вони є в панелі Pagar.me у розділі Development > Keys. Використовуються лише секретні ключі; публічний ключ (pk_...) не потрібен. Пропонуватися можуть лише ті способи оплати, які увімкнені у вашому обліковому записі Pagar.me.

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

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

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

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

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

4. Введіть тестовий секретний ключ, а коли перейдете в робочий режим, — робочий секретний ключ.

5. Створіть вебхук у панелі Pagar.me з URL, який показано в налаштуваннях (див. Конфігурація).

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

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

Конфігурація

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

Pagar.me

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

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

Description: текст, що відображається під способом оплати в оформленні замовлення. За замовчуванням: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

Ключі API

Скопіюйте секретні ключі з панелі Pagar.me: Development > Keys. Pagar.me використовує одну адресу API для тестових і робочих платежів; ключ визначає, є платіж тестовим чи реальним.

Test mode: використовує тестовий секретний ключ, реальних списань немає. Поки режим увімкнено, покупці бачать під способом оплати TEST MODE — Use test credentials. No real charges.. Перевірки статусу та повернення замовлення завжди використовують ключ того режиму, в якому створено його платіж. За замовчуванням: увімкнено.

Test secret key: тестовий секретний ключ Pagar.me (sk_test_...). Використовується, поки увімкнено тестовий режим.

Live secret key: робочий секретний ключ Pagar.me (sk_...). Використовується, коли тестовий режим вимкнено. Тримайте його в таємниці.

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

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

Сторінка оплати

Payment methods: способи оплати, які пропонуються на сторінці оплати Pagar.me. Обирайте лише способи, увімкнені у вашому обліковому записі Pagar.me. Якщо нічого не позначено, використовуються способи за замовчуванням. За замовчуванням: Credit card, PIX and Boleto.

Credit card: авторизується та списується одразу.

PIX: миттєва оплата через PIX.

Boleto: банківський платіжний документ; замовлення очікує в статусі Awaiting Pagar.me payment, доки його не буде оплачено.

Debit card: оплата дебетовою карткою.

Boleto due in (days): кількість днів до терміну оплати boleto, від 1 до 30. Замовлення залишається в статусі Awaiting Pagar.me payment, доки Pagar.me не підтвердить оплату. За замовчуванням: 3. Інше значення відхиляється під час збереження з повідомленням Boleto due in (days): enter a number from 1 to 30.

Повідомлення про платежі (вебхук)

У панелі Pagar.me відкрийте Settings > Webhooks і створіть вебхук з URL, який показано в полі Webhook URL у цьому розділі. З зручними URL він має такий вигляд: https://your-shop/module/wcp_pagarme_gateway/webhook, можливо, з кодом мови, наприклад /en/. Скопіюйте його точно так, як його показують налаштування.

Оберіть ці події (їх також наведено в цьому розділі):

order.paid: замовлення Pagar.me оплачено.

order.payment_failed: платіж не пройшов.

order.canceled: замовлення Pagar.me скасовано або воно прострочилося.

charge.paid: списання оплачено, наприклад PIX або boleto, оплачені пізніше.

charge.pending: списання очікує оплати, наприклад виставлений boleto.

charge.refunded: списання повернено.

charge.chargedback: власник картки оскаржив платіж.

Вебхук не потребує пароля чи підпису. Його вмісту ніколи не довіряють: магазин бере з нього лише ID замовлення Pagar.me і зчитує це замовлення через API Pagar.me з ключем того режиму, в якому його створено. Повідомлення про замовлення інших магазинів на тому самому обліковому записі Pagar.me ігноруються. Без вебхука PIX і boleto, оплачені пізніше, підтверджуються лише тоді, коли покупець повертається до магазину.

Додатково

Debug log: записує запити до API та повідомлення в logs/wc_pgm_debug.log.php у папці модуля. Файл не можна відкрити з веб-переглядача. Помилки та попередження записуються завжди. Ключі й дані покупців не записуються. За замовчуванням: вимкнено.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Pagar.me) і підтверджує вибір. Потрібна дійсна адреса електронної пошти. Модуль створює замовлення Pagar.me на суму кошика в BRL, з позиціями кошика, доставкою та подарунковим пакуванням (або однією позицією Order # з номером кошика, якщо в кошику є знижки), і надсилає покупця на сторінку оплати Pagar.me. На цьому етапі в вашому магазині замовлення ще немає.

Ім'я та електронна пошта покупця передаються в Pagar.me. CPF або CNPJ береться з поля Identification number адреси або з поля VAT number; також передається бразильський номер мобільного телефону. Адреса для рахунку передається лише для бразильської адреси з 8-значним CEP і штатом. PrestaShop за замовчуванням не містить бразильських штатів, тож покупець зазвичай вводить адресу на сторінці Pagar.me. Без CPF або CNPJ покупець вводить їх також там.

Після оплати покупець повертається до вашого магазину. Замовлення позначається як оплачене лише після підтвердження Pagar.me: магазин зчитує замовлення Pagar.me через API, і сплачена сума та валюта мають збігатися з кошиком. Оплачений платіж карткою, PIX або boleto створює замовлення в статусі Payment accepted, і покупець бачить стандартну сторінку підтвердження замовлення з написом Your payment with Pagar.me has been received. Виставлений, але ще не оплачений PIX або boleto створює замовлення в статусі Awaiting Pagar.me payment, а сторінка показує Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Кожне наступне повернення повторно зчитує замовлення Pagar.me, тож PIX або boleto, оплачені тим часом, зараховуються, навіть якщо вебхук не надійшов. Якщо оплата такого замовлення не пройшла або прострочилася, сторінка показує Your Pagar.me payment was not completed. Please contact us about this order.

Якщо покупець повертається, не сплативши, він опиняється в оформленні замовлення з повідомленням The Pagar.me payment was not completed. You can pay the order below. Якщо платіж відхилено або скасовано, з'являється повідомлення The Pagar.me payment was declined or canceled. You can try again below. Кошик зберігається. Якщо замовлення вже існує і його платіж не пройшов або прострочився, з'являється повідомлення The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Якщо зв'язатися з Pagar.me не вдалося, відкриється сторінка Payment confirmation, яка просить покупця не платити повторно і пропонує кнопки Check again та Back to checkout.

Коли покупець платить знову, відкрита сторінка оплати Pagar.me повторно використовується, якщо сума та режим ті самі; інакше вона закривається в Pagar.me, перш ніж буде створена нова. Якщо попередня спроба була оплачена тим часом або її PIX чи boleto ще очікує оплати, замовлення створюється без нового платежу. Якщо попередню сторінку не вдається закрити, вона залишається прив'язаною до кошика, тож платіж, зроблений на ній, все одно буде зафіксовано.

Якщо Pagar.me не може розпочати оплату, покупець залишається в оформленні замовлення з коротким повідомленням, наприклад Could not connect to Pagar.me. Please try again in a moment., або з повідомленням Pagar.me про неправильні платіжні дані. Технічна причина записується в журнал.

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

Модуль не має форми для введення картки в оформленні замовлення, збережених карток, підписок і регулярних платежів, правил розстрочки, розподілених платежів (маркетплейс), платежів картою лише з авторизацією та інтеграції з Pagar.me Hub.

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

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

No order yet: покупця надіслано в Pagar.me, і він ще не сплатив і не отримав PIX або boleto. Існує лише кошик.

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

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

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

Payment error: оплата замовлення в очікуванні чи на утриманні не пройшла, або його замовлення Pagar.me скасовано чи прострочено (наприклад, неоплачений boleto). Якщо Pagar.me пізніше повідомить про платіж, замовлення все одно перейде в Payment accepted.

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

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

Блок оплати Pagar.me

На сторінці замовлення відображається блок Pagar.me payment з ID замовлення Pagar.me та ID списань, способом оплати, статусом, сплаченою та поверненою сумами, позначкою Test mode для тестових платежів, історією повернень і Pagar.me notes замовлення.

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

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

Платежі boleto можна повернути лише на банківський рахунок покупця. Поверніть їх у панелі Pagar.me, а потім вручну зафіксуйте повернення в PrestaShop.

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

Повне повернення або скасування, зроблене в панелі Pagar.me, надходить вебхуком, переводить замовлення в статус Refunded і додає примітку. Оскарження додає примітку і переводить оплачене замовлення в статус Pagar.me payment on hold.

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

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

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

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

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

Pagar.me не відображається в оформленні замовлення: перевірте, що ліцензія активна, що Enable / Disable увімкнено, що секретний ключ поточного режиму вказано (Test secret key у тестовому режимі, Live secret key у робочому) і що валюта кошика — BRL. Сторінка налаштувань показує попередження, коли ключ відсутній. У розділі Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця і групи покупця.

Платіж пройшов, але замовлення не створено або воно залишається в статусі Awaiting Pagar.me payment: вебхук не працює. У панелі Pagar.me перевірте, що вебхук існує для облікового запису та режиму, які ви використовуєте, що його URL точно збігається з показаним у Webhook URL, і що вибрано перелічені вище події. Замовлення також перевіряється щоразу, коли покупець повертається до магазину.

Вебхук відповідає verification failed, retry later: магазин не зміг зчитати замовлення Pagar.me через API, наприклад тому що ключ цього режиму відсутній або API не відповів. Pagar.me повторює вебхук.

Вебхук відповідає busy: кошик у цей момент оновлювався іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Pagar.me повторює вебхук. Увімкніть Debug log, щоб побачити причину.

Вебхук відповідає unknown order: замовлення Pagar.me створено не цим магазином, наприклад замовлення іншого магазину на тому самому обліковому записі. Нічого не змінюється.

Покупець бачить Pagar.me payments are not available right now: секретний ключ неправильний або відсутній. Перевірте ключ поточного режиму.

Покупець бачить Pagar.me could not start the payment: Pagar.me відхилив платіжні дані, наприклад CPF у полі Identification number адреси. Повідомлення вказує на проблему; повна причина записана в журнал.

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

Покупець бачить This order already has a Pagar.me payment that the store has to review: попередній платіж за кошиком потребує вашої перевірки. Перевірте панель Pagar.me і журнал.

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

Повернення не працює для boleto: платежі boleto не можна повернути через API. Поверніть їх у панелі Pagar.me і зафіксуйте повернення вручну.

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

Розробники можуть змінити дані замовлення Pagar.me перед надсиланням за допомогою хука actionWcpPagarmeOrderData.

Видалення

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

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