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.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице 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.