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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта магазину: валюта країни вашого облікового запису MercadoPago: ARS (Аргентина), BRL (Бразилія), CLP (Чилі), COP (Колумбія), MXN (Мексика), PEN (Перу) або UYU (Уругвай). MercadoPago списує кошти у валюті облікового запису й не конвертує їх, тому спосіб оплати приховано для кошика в іншій валюті.

Обліковий запис MercadoPago: потрібен застосунок у панелі розробника MercadoPago (Your integrations > your application > Credentials) з тестовими обліковими даними (починаються з TEST-) та робочими (починаються з APP_USR-): Public Key і Access Token для кожних. Для необов'язкової перевірки підпису сповіщень також потрібен секретний ключ підпису з your application > Webhooks.

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

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

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

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

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

4. Оберіть Account country, введіть тестові та робочі облікові дані і, за бажання, налаштуйте сповіщення у своєму застосунку MercadoPago (див. Налаштування).

5. Увімкніть Enable / Disable і натисніть Save. Перевірте оплату в тестовому режимі тестовими картками MercadoPago, а потім вимкніть Test mode.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Test mode is on: the TEST- credentials are used and no real money is charged., доки ввімкнено тестовий режим. Вона також попереджає, якщо відсутній Public Key або Access Token поточного режиму, якщо валюта магазину не збігається з валютою вашого облікового запису MercadoPago (тоді спосіб оплати приховано на оформленні замовлення) і якщо облікові дані належать обліковому запису з іншої країни, ніж Account country.

Під час збереження облікові дані, які не починаються з очікуваного префікса (TEST- для тестових полів, APP_USR- для робочих), не зберігаються, і з'являється помилка must start with … — the previous value was kept.. Модуль також запитує в MercadoPago, до якої країни належить кожен Access Token. Якщо токен поточного режиму не вдалося перевірити, якщо обліковий запис не знаходиться в підтримуваній країні або якщо країна не збігається з Account country, з'являється помилка. Тоді модуль використовує країну облікового запису.

MercadoPago

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

Title: назва способу оплати, яку бачить покупець на оформленні замовлення. Вона також зберігається в замовленні. За замовчуванням: Credit or debit card (MercadoPago). Обов'язкове поле.

Description: текст над полями картки на оформленні замовлення. За замовчуванням: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

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

Отримайте облікові дані свого застосунку в панелі розробника MercadoPago: Your integrations > your application > Credentials. Тестові облікові дані починаються з TEST-, робочі — з APP_USR-.

Account country: країна вашого облікового запису MercadoPago. Вона визначає валюту списання, мову полів картки та те, чи запитується документ власника. Валюта магазину має збігатися з нею, наприклад ARS для Аргентини. Під час збереження облікових даних країна перевіряється за обліковим записом. За замовчуванням: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): підтримувані країни. Поле документа показується для всіх, крім Мексики.

Test mode: у тестовому режимі використовуються облікові дані TEST-, і ви платите тестовими картками MercadoPago; на оформленні замовлення показується позначка TEST MODE. Вимкніть режим, щоб списувати кошти з реальних карток робочими обліковими даними. За замовчуванням: on.

Test Public Key: починається з TEST-. Використовується в браузері для токенізації картки.

Test Access Token: починається з TEST-. Використовується лише на сервері. Тримайте в таємниці.

Production Public Key: починається з APP_USR-.

Production Access Token: починається з APP_USR-. Використовується лише на сервері. Тримайте в таємниці.

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

Параметри оплати

Maximum installments: найбільша кількість частин розстрочки, яку може вибрати покупець, від 1 до 24. 1 = лише одноразова оплата, поле розстрочки не показується. Обмеження також перевіряється на сервері. За замовчуванням: 1.

Сповіщення про платежі (вебхуки)

Платежі картками зазвичай отримують остаточну відповідь одразу. Платежі, які MercadoPago утримує на перевірці (в обробці або очікуванні), завершуються сповіщеннями MercadoPago. Модуль надсилає URL сповіщень із кожним платежем, якщо ваш магазин має публічну адресу (не localhost і не домен .local або .test). Його також можна додати в your application > Webhooks, подія Payments. URL показано в полі Notification URL у цьому розділі. З дружніми URL він виглядає так: https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Скопіюйте URL точно так, як він показаний у налаштуваннях.

Сповіщенню ніколи не довіряють самому по собі. Модуль повторно зчитує платіж через API MercadoPago з Access Token того режиму, в якому було проведено платіж, і прив'язує його до спроби оплати вашого магазину. Без сповіщень замовлення на перевірці залишаються в Awaiting MercadoPago payment, доки ви не оновите їх вручну.

Модуль обробляє такі статуси платежів MercadoPago:

approved: платіж схвалено. Замовлення позначається як оплачене, якщо сума та валюта збігаються.

in_process, pending, authorized: платіж на перевірці. Замовлення очікує в Awaiting MercadoPago payment і завершиться наступним сповіщенням.

rejected, cancelled: платіж відхилено або скасовано. Замовлення не створюється; замовлення, що очікувало, отримує статус Payment error.

refunded, charged_back, in_mediation: додається примітка; статус замовлення не змінюється.

Webhook secret signature: необов'язково. Секретний ключ підпису, показаний у your application > Webhooks. Якщо його задано, сповіщення без дійсної x-signature відхиляються (HTTP 401).

Clear saved secrets: позначте Test Access Token, Production Access Token або Webhook secret signature і натисніть Save, щоб видалити значення. Порожнє поле залишає збережене значення.

Додатково

Debug log: записує запити та сповіщення MercadoPago у logs/wc_mpg_debug.log.php у папці модуля. Файл не можна відкрити з веб. Помилки записуються завжди, навіть коли це налаштування вимкнено. Access Token, токени карток і дані платника не записуються. За замовчуванням: off.

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

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування шлюзу та журнали. Записи платежів MercadoPago, повернення та статуси замовлень модуля завжди зберігаються, тож замовлення, оплачені раніше, можна повернути навіть після повторного встановлення. За замовчуванням: off.

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

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Credit or debit card (MercadoPago)) і заповнює поля картки: Card number, Expiry (MM/YY), Security code і Cardholder name. Залежно від країни та картки покупець також обирає Document type і вводить Document number, вибирає Card issuer і кількість Installments. Варіанти розстрочки та відсотки надає MercadoPago для суми кошика. Форма картки працює з темами Classic і Hummingbird.

Коли покупець підтверджує оплату, MercadoPago перетворює картку на одноразовий токен, а ваш магазин створює платіж на сервері на суму кошика. E-mail і ім'я покупця, документ і номер кошика передаються в MercadoPago; платіж відображається як Cart #, номер кошика та назва вашого магазину. Суми в CLP і COP списуються без копійок. До відповіді MercadoPago замовлення не існує.

Схвалений платіж створює оплачене замовлення, і покупець бачить сторінку підтвердження замовлення з написом Your card payment has been received. Платіж на перевірці створює замовлення в статусі Awaiting MercadoPago payment, а сторінка показує MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. Якщо платіж на перевірці пізніше відхилять, сторінка покаже Your MercadoPago payment was not completed. Please contact us about this order. Замовлення на утриманні показує Your payment is being reviewed. We will update your order as soon as the review is complete.

Відхилена картка не створює замовлення. Покупець залишається на кроці оплати з коротким поясненням, наприклад Your card has insufficient funds. Please use another card or payment method. або Please check the security code of your card. Покупець може виправити дані або використати іншу картку; під час кожної спроби створюється новий токен картки.

Якщо MercadoPago не відповідає, покупець бачить We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. Наступна спроба спочатку перевіряє платіж, тож картку не буде списано двічі. Другий клік, поки кошик оплачується, показує This order is already being paid. Please wait a moment and check your e-mail before trying again. Кошик, для якого вже є замовлення, ніколи не списується повторно; покупця перенаправляють на сторінку підтвердження цього замовлення.

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

Модуль приймає лише кредитні та дебетові картки. Він не має переходу до Checkout Pro, гаманця або балансу MercadoPago, готівкових платежів (Rapipago, OXXO, boleto та інші), Pix, PSE чи Yape, збережених карток або підписок, окремих авторизації та списання, перевірки 3-D Secure та конвертації валют.

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

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

No order: картку відхилено або MercadoPago ще не відповів. Існує лише кошик.

Payment accepted: MercadoPago схвалив платіж, а сума та валюта збігаються з кошиком. Платіж записується з ID платежу MercadoPago як ID транзакції, а примітка показує ID платежу, середовище та кількість частин розстрочки.

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

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

Payment error: платіж на перевірці відхилено або скасовано. Примітка показує статус і його деталі.

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

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

Блок оплати MercadoPago

Сторінка замовлення показує блок MercadoPago payment з ID платежу, статусом платежу, середовищем (позначка Test для тестових платежів), кількістю частин розстрочки, сумою, яку списав MercadoPago, сумою замовлення, поверненою сумою, історією повернень і MercadoPago notes замовлення.

Повернення

У блоці MercadoPago payment введіть суму (підставляється сума, що ще не повернена), за бажанням причину, і натисніть Refund via MercadoPago. Підтвердьте питання Refund this amount through MercadoPago? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення. Повернення обмежені сумою, яку списав MercadoPago, тож після розбіжності сум можна повернути не більше того, що покупець фактично заплатив, а не суму замовлення. Повернення надсилається з обліковими даними середовища, в якому було проведено платіж (тестове або робоче), тому Access Token цього середовища має бути задано. Якщо MercadoPago відхиляє повернення, блок показує MercadoPago refused the refund з причиною, і повернення не записується. Схвалене або таке, що обробляється, повернення додається до історії повернень і приміток з ID повернення. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

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

Повернення, чарджбеки та медіації, виконані в панелі MercadoPago, надходять сповіщенням і додаються до приміток. Статус замовлення та кредитні ноти не змінюються автоматично. За потреби оновіть їх вручну.

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

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

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

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

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

MercadoPago не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, а в поточному режимі задано обидві облікові дані з правильним префіксом: ключі TEST- у тестовому режимі, ключі APP_USR- у робочому. Перевірте, що валюта кошика збігається з валютою вашого облікового запису MercadoPago. На сторінці налаштувань зазначено, чого бракує. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення залишається в Awaiting MercadoPago payment: сповіщення не надійшло. Модуль надсилає URL сповіщень лише тоді, коли ваш магазин має публічну адресу (не localhost і не домен .local або .test). Додайте URL з Notification URL у your application > Webhooks з подією Payments. Якщо задано Webhook secret signature, перевірте, що це секрет того самого застосунку. Панель MercadoPago показує відповідь вашого магазину на кожне сповіщення.

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

Сповіщення відповідає no credentials for test or no credentials for live: Access Token того режиму, в якому було проведено платіж, не задано. Введіть його; MercadoPago повторить сповіщення.

Сповіщення відповідає not for this store: платіж не належить до спроби оплати цього магазину. Замовлення не змінюється.

Сповіщення відповідає order busy or payment could not be read: замовлення в цей момент оновлювалося іншим запитом, або MercadoPago був недоступний. MercadoPago автоматично повторить сповіщення.

Облікові дані не зберігаються: помилка must start with означає, що значення має неправильний префікс для поля. Тестові поля приймають облікові дані TEST-, робочі поля — APP_USR-.

Покупець бачить This payment method is not configured correctly. Please choose another payment method or contact the store.: облікових даних поточного режиму бракує, вони мають неправильний префікс або їх відхилив MercadoPago. Перевірте їх на сторінці налаштувань.

Покупець бачить MercadoPago cannot process payments in: валюта кошика не збігається з валютою вашого облікового запису MercadoPago. MercadoPago не конвертує валюти.

Захищена форма картки не завантажується: покупець бачить The secure card form could not be loaded. Please reload the page or choose another payment method. Перевірте Public Key поточного режиму.

Покупець бачить Your payment was received, but the order could not be completed automatically: MercadoPago списав платіж, але PrestaShop не зміг створити замовлення (наприклад, модуль було вимкнено в цей момент). Перегляньте поле Log на сторінці модуля: помилки записуються завжди. Покупця просять не платити знову; наступна спроба оплати або наступне сповіщення для кошика створить замовлення без нового списання.

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

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

Повернення не проходить з повідомленням MercadoPago did not answer the refund request: перевірте платіж у панелі MercadoPago, перш ніж повторювати спробу.

Видалення

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

MercadoPago є товарним знаком його власника. Цей модуль не є афілійованим із MercadoPago і не схвалений MercadoPago.