VibeFox PayU LATAM for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: кошик має бути в ARS, BRL, CLP, COP, MXN, PEN або USD, тобто у валютах, які PayU Latam обробляє в Аргентині, Бразилії, Чилі, Колумбії, Мексиці, Панамі та Перу. Для інших валют спосіб оплати не показується під час оформлення замовлення.

Обліковий запис PayU Latam: потрібні три значення вашого комерційного акаунта PayU: ідентифікатор мерчанта, ідентифікатор рахунку країни, в якій ви продаєте, і ключ API. Вони містяться в модулі PayU (панелі мерчанта PayU) у розділах Settings > Technical configuration (merchant ID, API key) та Accounts (account ID). Для тестування PayU публікує загальнодоступні тестові облікові дані та тестові картки на сторінці "Test your solution" своєї документації для розробників. API Login та інші облікові дані API не потрібні, оскільки оплата відбувається на розміщеній сторінці PayU, а модуль ніколи не викликає API PayU.

Доступність вашого магазину з інтернету: PayU надсилає результат оплати до вашого магазину зі своїх серверів, тому магазин має бути доступним з інтернету (не локальний сайт і не сайт за паролем).

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

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

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

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

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

4. Введіть облікові дані тестового середовища та свої робочі облікові дані (див. Налаштування). У PayU не потрібно налаштовувати URL підтвердження.

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

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

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

Усі налаштування містяться на сторінці модуля: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Sandbox mode. Payments go to the PayU sandbox and no real money is charged., поки увімкнено тестове середовище; помилку, якщо не заповнені ідентифікатор мерчанта, ідентифікатор рахунку або ключ API поточного середовища; і попередження, якщо PayU LATAM не обробляє типову валюту магазину. Поки облікові дані не заповнені, PayU LATAM не показується під час оформлення замовлення. Пробіли на початку або в кінці облікових даних ігноруються. Сторінка не зберігає порожнє поле Title і показує Enter a title for the payment method.

PayU LATAM

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

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

Description: опис способу оплати, який бачить покупець під час оформлення замовлення. За замовчуванням: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Середовище

Sandbox: платежі надсилаються до тестового середовища PayU з тестовими обліковими даними, вказаними нижче, і реальні кошти не списуються. Коли опцію вимкнено, використовуються робочі облікові дані та робоча платіжна сторінка PayU. За замовчуванням: увімкнено. Поки вона увімкнена, покупці бачать під способом оплати Sandbox mode: no real money is charged.

Робочі облікові дані

Знайти їх можна в модулі PayU: Settings > Technical configuration (merchant ID, API key) та Accounts (account ID країни, в якій ви продаєте). У розділі є посилання на панель мерчанта PayU.

Merchant ID: числовий ідентифікатор вашого комерційного акаунта PayU.

Account ID: ідентифікатор рахунку PayU. Для кожної країни є окремий рахунок.

API Key: секретний ключ, яким підписуються платежі та перевіряються сповіщення PayU.

Тестові облікові дані

PayU публікує загальнодоступні тестові облікові дані та тестові картки для свого тестового середовища. У розділі є посилання на сторінку "Test your solution" документації PayU.

Sandbox merchant ID: ідентифікатор мерчанта для тестового середовища PayU.

Sandbox account ID: ідентифікатор рахунку для тестового середовища PayU.

Sandbox API key: ключ API для тестового середовища PayU.

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

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

Кожна спроба оплати запам'ятовує своє середовище. Підтвердження платежу в тестовому середовищі перевіряється ключем API та ідентифікатором мерчанта тестового середовища, підтвердження робочого платежу — робочими значеннями, тож очікувані платежі продовжують працювати після перемикання. Платіж у тестовому середовищі, підтверджений після перемикання, позначається в примітках замовлення як [sandbox].

URL підтвердження

Цей розділ показує URL, на який PayU повідомляє кожен результат оплати. За увімкнених зрозумілих URL він має такий вигляд: https://your-shop/module/wcp_payu_latam_payment/confirmation, можливо з кодом мови, наприклад /en/. Модуль передає його в PayU з кожним платежем, тож у PayU нічого налаштовувати не потрібно. URL має бути доступним з інтернету. Він працює й тоді, коли магазин переведено в режим обслуговування, і не блокується обмеженням за країнами магазину. PayU підписує підтвердження вашим ключем API. Підтвердження без коректного підпису, з іншим ідентифікатором мерчанта або з платіжним посиланням, яке цей магазин не видавав, відхиляються. Модуль обробляє такі статуси транзакцій PayU:

4 (approved): оплату проведено. Замовлення створюється оплаченим, якщо сума та валюта відповідають кошику.

6 (declined), 5 (expired), 104 (error): оплата не вдалася. Замовлення не створюється, кошик зберігається.

7, 10, 12, 14, 15, 18 (pending): платіж очікує, наприклад оплата готівкою або банківським переказом, яку покупець ще не завершив. Замовлення створюється в статусі Awaiting PayU LATAM payment.

Інші статуси додаються лише як примітка. Без підтвердження замовлення не створюється.

Додатково

Debug log: записує запити на оплату та сповіщення PayU у файл logs/payu_lp_debug.log.php у папці модуля. Файл не можна відкрити з браузера. Ключі та персональні дані не записуються. Помилки та відхилені сповіщення записуються завжди, навіть коли цей перемикач вимкнено. За замовчуванням: вимкнено.

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

Delete data: видаляє налаштування та журнали під час видалення модуля. Дані PayU щодо замовлень (спроби оплати) та статуси замовлень зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (типово PayU LATAM) і підтверджує вибір. Сторінка магазину показує You are being redirected to PayU LATAM to complete the payment... і автоматично надсилає підписану форму на сторінку PayU WebCheckout. Якщо цього не сталося, покупець натискає Pay with PayU LATAM або Back to checkout, щоб повернутися. На цьому етапі замовлення ще не існує.

Форма містить суму та валюту кошика, податок і базу оподаткування кошика (обидва значення 0 для кошиків без податку, щоб PayU не додавав ПДВ за замовчуванням), опис Cart # з номером кошика та назвою вашого магазину, а також електронну адресу, ім'я, телефон і платіжну адресу покупця. Сторінка PayU відкривається іспанською, португальською або англійською мовою залежно від мови кошика. На сторінці PayU покупець сплачує будь-яким способом, увімкненим у вашому обліковому записі PayU.

Кожне відкриття сторінки оплати створює нову спробу оплати зі своїм референсом (PS, номер кошика та позначка часу). Попередні спроби запам'ятовуються: якщо покупець заплатить у вкладці PayU, відкритій раніше, платіж однаково буде прийнято.

Замовлення позначається оплаченим лише після підписаного підтвердження PayU. Покупець, який повернувся з PayU, ніколи не позначає замовлення оплаченим. Коли покупець повертається:

Після підписаної відмови, закінчення терміну або помилки: покупець повертається до оформлення замовлення з повідомленням Your PayU LATAM payment was not approved, причиною від PayU, якщо вона є, і You can try again or choose another payment method. Кошик зберігається.

Без транзакції PayU (покупець покинув сторінку PayU): покупець повертається до оформлення замовлення з повідомленням Your PayU LATAM payment was not completed. You can try again or choose another payment method.

Замовлення вже існує: покупець бачить стандартну сторінку підтвердження замовлення. Для замовлення в статусі Awaiting PayU LATAM payment вона показує Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment. Для замовлення, що перебуває на утриманні, — We have received your PayU LATAM payment and are reviewing it. We will contact you if anything is needed. Для замовлення в статусі Payment error — Your PayU LATAM payment was not approved. Please contact us.

PayU ще не підтвердив платіж: сторінка показує We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. (або очікуваний текст вище для оплати готівкою чи банківським переказом) з кнопкою Check again. Підтвердження створює замовлення, щойно воно надходить.

Якщо облікові дані поточного середовища не заповнені, покупець бачить PayU LATAM is not available right now. Please choose another payment method. Для непідтримуваної валюти кошика повідомлення таке: PayU LATAM does not accept payments in і далі валюта. Кошик, для якого вже є замовлення, знову не оплачується: покупець переходить на сторінку підтвердження свого замовлення.

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

Замовлення

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

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

Payment accepted: PayU підтвердив платіж, сума та валюта збігаються. Платіж записується з ідентифікатором транзакції PayU, а примітка показує транзакцію, суму, спосіб оплати та [sandbox] для платежів у тестовому середовищі.

Awaiting PayU LATAM payment: PayU повідомляє про платіж як про очікуваний (оплата готівкою або банківським переказом). Замовлення переходить у Payment accepted, коли PayU підтверджує платіж.

PayU LATAM payment on hold: сплачена сума або валюта не збігаються із сумою кошика, або платіж було схвалено для скасованого замовлення. Платіж записується, якщо він у валюті замовлення. Примітка вказує, у чому справа: перевірте платіж у модулі PayU, потім обробіть замовлення, відновіть його або поверніть кошти.

Payment error: очікуваний платіж останньої спроби згодом було відхилено, він прострочився або завершився помилкою. Примітка показує повідомлення PayU. Цей кошик не можна оплатити знову: покупець оформлює нове замовлення. Відмова за старішою спробою або за замовленням, яке вже має схвалений платіж, додається лише як примітка.

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

Блок оплати PayU LATAM

На сторінці замовлення показано блок PayU LATAM payment з референсом, ідентифікатором транзакції, референсом PayU, статусом і станом PayU, запитаною сумою, сумою, яку повідомив PayU, способом оплати, повідомленням PayU, значком SANDBOX для платежів у тестовому середовищі, списком усіх спроб оплати кошика та PayU LATAM notes замовлення.

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

Повернення коштів не виконуються з PrestaShop. Поверніть кошти за транзакцією в модулі PayU, а потім вручну зафіксуйте повернення в PrestaShop.

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

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

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

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

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

PayU LATAM не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено та заповнені ідентифікатор мерчанта, ідентифікатор рахунку та ключ API поточного середовища: облікові дані тестового середовища, коли Sandbox увімкнено, робочі — коли вимкнено. Перевірте, що валюта кошика — ARS, BRL, CLP, COP, MXN, PEN або USD. У Payment > Preferences перевірте, чи дозволено модуль для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: підтвердження PayU не дійшло до магазину або було відхилено. Перевірте, що URL підтвердження, показаний у налаштуваннях, доступний з інтернету (не локальний сайт, немає брандмауера та захисту паролем). Перегляньте поле Log на сторінці модуля — там видно відхилені підтвердження. PayU надсилає підтвердження повторно після будь-якої відповіді з помилкою.

Підтвердження відповідає Invalid signature: підтвердження не було підписано ключем API того середовища, в якому пройшов платіж. Перевірте API Key для робочих платежів і Sandbox API key для платежів у тестовому середовищі.

Підтвердження відповідає Merchant mismatch: ідентифікатор мерчанта в підтвердженні не збігається з Merchant ID або Sandbox merchant ID середовища платежу. Введіть ідентифікатор мерчанта того облікового запису PayU, який обробляє платежі.

Підтвердження відповідає Gateway not configured: не заповнені ключ API або ідентифікатор мерчанта середовища платежу, наприклад тестові облікові дані були видалені, поки платіж у тестовому середовищі очікував обробки. Введіть їх знову; PayU повторить підтвердження.

Підтвердження відповідає Retry: кошик у ту саму мить обробляв інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Нічого не змінено, і PayU надішле підтвердження знову. Причину дивіться в Log.

Підтвердження відповідає Unknown reference: платіжне посилання не було видано цим магазином.

URL підтвердження в браузері показує Method not allowed: це нормально. URL приймає лише запити від PayU.

Покупець бачить This payment method is not available: модуль не дозволено для країни, валюти або групи покупця в Payment > Preferences, або Enable/Disable вимкнено.

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

Видалення

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

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