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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія.

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

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

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

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

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

Архів для завантаження — один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на комп'ютері. Він містить README.txt, пакет для OpenCart 3 wcp_payu_latam_payment-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_payu_latam_payment.ocmod.zip. Встановлюйте лише пакет для своєї версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_payu_latam_payment-oc3-(version).ocmod.zip. Розширення не має змін OCMOD, тому Extensions > Modifications оновлювати не потрібно. Замість установника можна скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox PayU LATAM Payment і натисніть Install (зелена кнопка +). Вашому адміністратору потрібне право змінювати список платіжних розширень.

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

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

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

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_payu_latam_payment.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox PayU LATAM Payment, натисніть Install (зелена кнопка +), потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і облікові дані PayU так само, як у кроках 3–5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL підтвердження (див. URL підтвердження).

Нове встановлення починає роботу з вимкненим способом оплати та увімкненим sandbox.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit. Розділи переліку ліворуч; кнопка Save під переліком зберігає всю сторінку. Над налаштуваннями сторінка показує Sandbox mode. Payments go to the PayU sandbox and no real money is charged., поки sandbox увімкнено; помилку, якщо не заповнено merchant ID, account ID або ключ API поточного середовища (тоді PayU Latam не пропонується на оформленні замовлення); і попередження, якщо PayU Latam не обробляє валюту магазину за замовчуванням. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження поле Title не може бути порожнім або довшим за 128 символів (сторінка показує Enter a title for the payment method (at most 128 characters).), Sort Order має бути цілим числом (від’ємні числа дозволені), Total має бути числом 0 або більше, а геозона та статуси замовлення мають існувати. Інакше нічого не зберігається. Пробіли на початку або в кінці облікових даних ігноруються.

PayU LATAM

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

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

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

Sort Order: позиція PayU LATAM серед способів оплати на оформленні замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати PayU LATAM лише для платіжних адрес у вибраній геозоні. За замовчуванням: All zones. Геозони налаштовуються в System > Localisation > Geo Zones.

Total: сума оформлення замовлення у валюті магазину за замовчуванням, яку замовлення має досягти, щоб пропонувався PayU LATAM. Залиште порожнім, щоб пропонувати PayU LATAM за будь-якою сумою.

Середовище

Sandbox: платежі надсилаються до sandbox PayU з обліковими даними sandbox, і реальні кошти не списуються. Коли опція вимкнена, використовуються облікові дані робочого середовища та робоча сторінка оплати PayU. За замовчуванням: увімкнено. Поки вона увімкнена, покупець на кроці Confirm Order бачить 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.

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

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

Sandbox merchant ID: merchant ID для sandbox PayU.

Sandbox account ID: account ID для sandbox PayU.

Sandbox API key: ключ API для sandbox PayU.

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

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

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

Цей розділ показує URL, на який PayU повідомляє кожен результат оплати. В OpenCart 3 він має вигляд https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation і формується з адреси вітрини вашого встановлення OpenCart. Розширення надсилає його до PayU з кожним платежем, тож у PayU нічого налаштовувати не потрібно. URL має бути доступним з інтернету. Він працює й тоді, коли магазин у режимі обслуговування (на OpenCart 4 через дію запуску розширення, яка також пропускає повернення покупця з PayU). PayU підписує підтвердження вашим ключем API. Підтвердження без дійсного підпису, з іншим merchant ID або з посиланням на платіж, який цей магазин не видавав, відхиляються. Розширення обробляє такі статуси транзакцій PayU:

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

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після підписаного підтвердження PayU. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: підтверджений платіж (статус PayU 4) з очікуваною сумою та валютою. За замовчуванням: В обробці.

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

On Hold (Review) Status: PayU схвалив платіж, але з іншою сумою чи валютою, ніж у замовленні, або для замовлення, яке було скасовано. Нотатка показує деталі; замовлення не позначається оплаченим. За замовчуванням: Очікування, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Failed Payment Status: платіж в очікуванні останньої спроби, який PayU згодом повідомив як відхилений, прострочений або невдалий. За замовчуванням: Невдалий.

Cancelled Order Status: статус, який ваш магазин використовує для скасованих замовлень. Схвалений платіж за таке замовлення переводить його в On Hold (Review) Status замість позначення оплаченим. Розширення ніколи не встановлює цей статус. За замовчуванням: Скасовано.

Додатково

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

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

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

Імпорт / експорт

Export: Download JSON зберігає налаштування у файл JSON. Ключі API не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені ключі API зберігаються.

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

На кроці Payment Method покупець вибирає спосіб оплати (за замовчуванням PayU LATAM). На кроці Confirm Order покупець бачить ваш опис; OpenCart створює замовлення на цьому кроці, ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. Коли покупець натискає Confirm Order, розширення готує підписану платіжну форму, сторінка показує You are being redirected to PayU LATAM to complete the payment... і автоматично надсилає форму на сторінку PayU WebCheckout. Якщо цього не відбувається, покупець натискає Pay with PayU LATAM.

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

Кожне натискання Confirm Order запускає нову спробу оплати з власним посиланням (OC, номер замовлення та позначка часу). На OpenCart 4 нова спроба оплачує те саме замовлення оформлення. Попередні спроби запам’ятовуються: якщо покупець платить у старій вкладці PayU, платіж усе одно розпізнається.

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

На OpenCart 4 повідомлення оформлення показуються над сторінкою оформлення.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, OpenCart 4 оновлює замовлення оформлення, але кошик оплачується лише один раз: якщо інше замовлення з цього самого кошика вже оплачено, очікує оплати або перевіряється, Confirm Order одразу веде на сторінку успіху. Якщо облікових даних поточного середовища немає, покупець бачить PayU LATAM is not available right now. Please choose another payment method. Зміна кошика, зокрема нова кількість, вважається новим кошиком, якому потрібна власна оплата.

OpenCart 4 зберігає замовлення на оформленні доти, доки не буде показано сторінку успіху. Якщо це замовлення було закрито без оплати (наприклад, його платіж готівкою не вдався або ви його скасували), покупця повертають на оформлення з повідомленням Your PayU LATAM payment was not approved і причиною PayU, якщо вона є. Якщо його було оплачено, а потім закрито магазином, або оплачено за попередній кошик, який змінився, повідомлення: Ваше попереднє замовлення вже закрито. Будь ласка, підтвердьте замовлення ще раз: кошик буде оплачено новим замовленням. Наступне Confirm Order оплачує нове замовлення. Закрите замовлення ніколи не показується як оплачене.

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

Замовлення

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

Без статусу (відсутнє замовлення): покупця було перенаправлено до PayU, і він не сплатив, платіж відхилено або PayU ще не надіслав підтвердження. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

Order Status After Payment (default Processing): PayU підтвердив платіж, сума та валюта збігаються. Нотатка показує транзакцію, суму, спосіб оплати та те, чи це був платіж sandbox.

Awaiting Payment Status (default Pending): PayU повідомляє про платіж як про такий, що очікує (оплата готівкою або банківський переказ). Замовлення переходить до Order Status After Payment, коли PayU підтверджує платіж, або до Failed Payment Status, якщо платіж не вдався. OpenCart повідомляє покупця про ці зміни.

On Hold (Review) Status (default Pending): сплачена сума або валюта не збігаються із сумою замовлення, або платіж схвалено для замовлення, яке було скасовано. Нотатка вказує причину: перевірте платіж у панелі PayU, а потім опрацюйте замовлення, відновіть його або поверніть кошти.

Failed Payment Status (default Failed): платіж в очікуванні останньої спроби згодом було відхилено, він прострочився або завершився помилкою. Нотатка показує повідомлення PayU. Відмова попередньої спроби або замовлення, яке вже має схвалений платіж, лише додається до нотатки.

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

Нотатки є записами в History замовлення, які покупець не бачить.

Вкладка VibeFox PayU LATAM Payment

У Sales > Orders відкрийте замовлення, оплачене через PayU LATAM. Унизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox PayU LATAM Payment показує Reference, Transaction ID, PayU reference, Status і статус PayU, суму Requested, Amount reported by PayU, Payment method, PayU message, позначку SANDBOX для платежів sandbox, список усіх Payment attempts кошика та PayU LATAM notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

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

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

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox PayU LATAM Payment — перший блок на сторінці Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен), а також кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: opencart-payment-payu-latam і посилання Керування ліцензіями та доменами у вашому обліковому записі, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify для розширення. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

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

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

Без активного ключа PayU LATAM не показується покупцям на оформленні замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратор, який увійшов в адмін-панель у тому самому браузері, усе ще бачить спосіб оплати в магазині, позначений (unlicensed — visible to admins only), щоб ви могли налаштувати та протестувати розширення до купівлі ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тож без активного ключа спосіб оплати приховано для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard адмін-панелі з’являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Існуючі замовлення не змінюються: платежі, які вже розпочато, як і раніше підтверджуються підтвердженням PayU та поверненням покупця.

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

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

PayU LATAM не з’являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а merchant ID, account ID і ключ API поточного середовища заповнені: облікові дані sandbox, коли Sandbox увімкнено, робочі — коли вимкнено. Перевірте, що валюта покупця — ARS, BRL, CLP, COP, MXN, PEN або USD, що платіжна адреса входить до вибраної Geo Zone і що сума замовлення досягає Total, заданого в налаштуваннях.

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

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

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

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

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

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

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

Покупець бачить This payment method is not available. Please reload the checkout page.: сеанс оформлення замовлення більше не відповідає замовленню, або Enable/Disable тим часом вимкнули. Покупець має перезавантажити оформлення замовлення.

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

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox PayU LATAM Payment. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень із розділу Orders, які повертаються до значень за замовчуванням під час повторного встановлення. Подія OpenCart розширення також видаляється (на OpenCart 4 видаляються також його події та дія запуску, яка пропускає підтвердження та повернення покупця в режимі обслуговування). Якщо Delete data увімкнено, видаляються решта налаштувань шлюзу (назва, опис, sandbox, облікові дані, перемикач журналу налагодження) та журнал. Якщо вимкнено, вони зберігаються для майбутнього повторного встановлення. Спроби оплати завжди зберігаються, тож пізнє підтвердження PayU за старою спробою і після повторного встановлення розпізнається. Існуючі замовлення зберігають свої нотатки про оплату.

На OpenCart 4, щоб також видалити файли розширення, після видалення перейдіть до Extensions > Installer і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox PayU LATAM Payment у списку встановлених розширень, потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

PayU є торговельною маркою її власника. Це розширення не афілійоване з PayU і не схвалене PayU.