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 и не одобрен им.