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

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 8.0 або новіша, встановлений і активний. Без WooCommerce плагін не активується.

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

Валюта магазину: валюта країни вашого облікового запису 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. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_mercadopago_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > MercadoPago > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки та натисніть Activate.

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

6. Увімкніть Enable / Disable і збережіть. Перевірте роботу тестовими картками MercadoPago (ім'я власника APRO = схвалено, CONT = очікує, OTHE = відхилено), а потім зніміть позначку з Test mode.

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

Усі параметри розташовані на одній сторінці: WooCommerce > Settings > Payments > MercadoPago. Над полями сторінка показує Test mode is on: the TEST- credentials are used and no real money is charged., поки ввімкнено тестовий режим. Вона попереджає, якщо не вказано облікові дані поточного режиму, якщо валюта магазину не збігається з валютою облікового запису MercadoPago (тоді спосіб оплати прихований на сторінці оформлення замовлення), і якщо облікові дані належать обліковому запису з іншої країни, ніж Account country. У списку способів оплати MercadoPago позначено як такий, що потребує налаштування, доки в поточному режимі немає облікових даних.

Під час збереження облікові дані, що не починаються з очікуваного префікса (TEST- для тестових полів, APP_USR- для робочих), не зберігаються: з'являється помилка, а попереднє значення залишається. Плагін також запитує в MercadoPago, до якої країни належить Access Token. Якщо токен не вдається перевірити, обліковий запис не розташований у підтримуваній країні або країна не збігається з Account country, з'являється помилка. Тоді плагін використовує країну облікового запису.

Загальні

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

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: Use the test credentials (no real charges). У тестовому режимі використовуються облікові дані TEST-, і ви платите тестовими картками MercadoPago; на сторінці оформлення замовлення відображається значок TEST MODE. Зніміть позначку, щоб списувати кошти з реальних карток робочими обліковими даними. За замовчуванням: увімкнено. Щоб тестувати з тестовим користувачем MercadoPago (облікові дані APP_USR-), введіть облікові дані цього облікового запису в робочі поля та вимкніть тестовий режим.

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

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

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

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

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

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

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

Платежі картками зазвичай одразу отримують остаточну відповідь. Платежі, які MercadoPago утримує на перевірці (в обробці або очікують), завершуються сповіщеннями від MercadoPago. Плагін передає URL сповіщень з кожним платежем, якщо у вашого сайту є публічна адреса. Його також можна додати в your application > Webhooks, подія Payments. URL показано в цьому розділі налаштувань і має такий вигляд: https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

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

Плагін обробляє такі статуси платежів MercadoPago:

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

in_process, pending, authorized: платіж на перевірці. Замовлення переводиться в «На утриманні» і завершується наступним сповіщенням.

rejected, cancelled: платіж відхилено або скасовано. Неоплачене замовлення позначається як «Невдалий».

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

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

Додаткові

Debug log: Log API requests and notifications записує в WooCommerce > Status > Logs, джерело wcp_mercadopago_gateway. Access Token, токени карток і дані платника в журнал не записуються. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. ID платежів MercadoPago, збережені в замовленнях, є історією платежів і завжди зберігаються. За замовчуванням: вимкнено.

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

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

Після оформлення замовлення MercadoPago перетворює картку на одноразовий токен, а ваш магазин створює платіж на сервері на суму замовлення. Адреса електронної пошти та ім'я для рахунку, документ і номер замовлення передаються в MercadoPago. Суми в CLP і COP списуються без десяткових знаків і округлюються до цілого числа, тому для цих валют встановіть у WooCommerce кількість десяткових знаків 0.

Схвалений платіж одразу позначається оплаченим, і покупець переходить на сторінку «Замовлення отримано». Платіж на перевірці переводить замовлення в «На утриманні»; покупець також переходить на сторінку «Замовлення отримано», а замовлення завершується за сповіщенням. Відхилена картка показує на сторінці оформлення замовлення коротку причину, наприклад 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.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Pending payment: замовлення створено, і результату платежу ще немає, наприклад після тайм-ауту.

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

On hold: платіж на перевірці (в обробці або очікує) і чекає сповіщення від MercadoPago. Статус «На утриманні» також встановлюється, якщо схвалена сума або валюта не збігаються із замовленням або MercadoPago повертає неочікуваний статус. Примітка до замовлення пояснює причину.

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

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Credit or debit card (MercadoPago) (кнопка показує ваше значення Title). Підтримуються повні та часткові повернення. Повернення надсилається з обліковими даними середовища, в якому було проведено платіж (тестового або робочого), тому Access Token цього середовища має бути заданий. Якщо MercadoPago відмовляє в поверненні, WooCommerce показує MercadoPago refused the refund з причиною, і повернення не реєструється. Схвалене або таке, що перебуває в обробці, повернення додається до приміток замовлення з ID повернення.

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований у верхній частині сторінки WooCommerce > Settings > Payments > MercadoPago. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис на vibefox.net.

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

Без активного ключа MercadoPago не показується покупцям на сторінці оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Авторизовані адміністратори магазину й далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати та протестувати плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: вже розпочаті платежі й далі підтверджуються, а повернення працюють.

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

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

MercadoPago does not appear at checkout: перевірте, що ліцензія активна, Enable / Disable увімкнено і в поточному режимі є обидва облікові дані з правильним префіксом: ключі TEST- у тестовому режимі, ключі APP_USR- у робочому. Перевірте, що валюта магазину (або валюта замовлення на сторінці Pay for order) збігається з валютою облікового запису MercadoPago. На сторінці налаштувань зазначено, чого бракує.

The payment went through, but the order stays On hold or Pending payment: платіж пройшов, але замовлення залишається «На утриманні» або «Очікує оплати»: сповіщення не надійшло. Плагін передає URL сповіщень лише тоді, коли у вашого сайту є публічна адреса (не localhost і не домен .local або .test). Додайте URL з налаштувань у your application > Webhooks з подією Payments. Якщо задано Webhook secret signature, перевірте, що це секрет того самого застосунку. Панель MercadoPago показує відповідь вашого магазину на кожне сповіщення.

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

Notification answers not for this store: платіж не належить до замовлення цього магазину, оплаченого через MercadoPago. Замовлення не змінюється.

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

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

The customer sees MercadoPago cannot process payments in: валюта замовлення не збігається з валютою облікового запису MercadoPago. MercadoPago не конвертує валюти.

The secure card form does not load: покупець бачить The secure card form could not be loaded. Please reload the page or choose another payment method. Перевірте Public Key поточного режиму. Для детальнішої інформації увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_mercadopago_gateway.

Refund fails with a message about the mode: платіж було проведено в тестовому або робочому режимі, а Access Token цього режиму не задано. Введіть його й повторіть спробу.

Refund fails with MercadoPago did not answer the refund request: перевірте платіж у панелі MercadoPago, перш ніж повторювати спробу.

The license block shows an error: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі на vibefox.net і натисніть Check now. Якщо адресу сайту змінено, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати з останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть його на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу, збережена перевірка облікового запису та журнали видаляються, лише якщо була ввімкнена опція Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої примітки про оплату, ID платежів MercadoPago та ID транзакцій.

MercadoPago — торговельна марка її власника. Цей плагін не пов'язаний з MercadoPago і не схвалений MercadoPago.