VibeFox Pagar.me for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль отказывается устанавливаться на более старых версиях PHP.

Валюта: бразильский реал (BRL). Способ оплаты скрывается для корзин в любой другой валюте.

Учётная запись Pagar.me: вам нужны секретные ключи вашей учётной записи Pagar.me: тестовый ключ (sk_test_...) и, чтобы перейти в боевой режим, боевой ключ (sk_...). Они находятся в панели Pagar.me в разделе Development > Keys. Используются только секретные ключи; публичный ключ (pk_...) не нужен. Предлагаться могут только те способы оплаты, которые включены в вашей учётной записи Pagar.me.

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Pagar.me Gateway в списке модулей и нажмите Configure.

3. Введите ваш лицензионный ключ VibeFox в License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Введите тестовый секретный ключ, а при переходе в боевой режим — боевой секретный ключ.

5. Создайте вебхук в панели Pagar.me с URL, который показан в настройках (см. Конфигурация).

6. Включите Enable / Disable и нажмите Save. Проводите тестовые платежи при включённом Test mode, затем выключите его, чтобы принимать реальные платежи.

При установке модуль создаёт два статуса заказа: Awaiting Pagar.me payment и Pagar.me payment on hold. PrestaShop предлагает новый модуль оплаты для всех валют, стран и групп покупателей. Их можно ограничить в разделе Payment > Preferences.

Конфигурация

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Pagar.me Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает текущий режим: TEST MODE (платежи создаются с тестовым секретным ключом, реальных списаний нет) или LIVE. Она предупреждает, если отсутствует секретный ключ текущего режима (тогда способ оплаты скрыт в оформлении заказа), если тестовый ключ не начинается с sk_test_, если боевой ключ не начинается с sk_ или является тестовым, а также если валюта магазина по умолчанию не BRL.

Pagar.me

Enable / Disable: Enable Pagar.me payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель в оформлении заказа. Оно также сохраняется как название способа оплаты в заказе. По умолчанию: Pagar.me. Обязательное поле.

Description: текст, который показывается под способом оплаты в оформлении заказа. По умолчанию: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

Ключи API

Скопируйте секретные ключи из панели Pagar.me: Development > Keys. Pagar.me использует один адрес API для тестовых и боевых платежей; ключ определяет, является ли платёж тестовым или реальным.

Test mode: использует тестовый секретный ключ, реальных списаний нет. Пока режим включён, покупатели видят под способом оплаты надпись TEST MODE — Use test credentials. No real charges.. Проверки статуса и возвраты заказа всегда используют ключ того режима, в котором был создан его платёж. По умолчанию: включено.

Test secret key: тестовый секретный ключ Pagar.me (sk_test_...). Используется, пока включён тестовый режим.

Live secret key: боевой секретный ключ Pagar.me (sk_...). Используется, когда тестовый режим выключен. Храните его в секрете.

Сохранённые ключи больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved secret keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Страница оплаты

Payment methods: способы оплаты, которые предлагаются на странице оплаты Pagar.me. Выбирайте только способы, включённые в вашей учётной записи Pagar.me. Если ничего не отмечено, используются способы по умолчанию. По умолчанию: Credit card, PIX and Boleto.

Boleto due in (days): количество дней до срока оплаты boleto, от 1 до 30. Заказ остаётся в статусе Awaiting Pagar.me payment, пока Pagar.me не подтвердит оплату. По умолчанию: 3. Другое значение отклоняется при сохранении с сообщением Boleto due in (days): enter a number from 1 to 30.

Уведомления об оплате (вебхук)

В панели Pagar.me откройте Settings > Webhooks и создайте вебхук с URL, который показан в поле Webhook URL в этом разделе. При ЧПУ он выглядит так: https://your-shop/module/wcp_pagarme_gateway/webhook, возможно, с кодом языка, например /en/. Скопируйте его точно в том виде, в каком он показан в настройках.

Выберите эти события (они также перечислены в этом разделе):

Вебхуку не нужны пароль или подпись. Его содержимому никогда не доверяют: магазин берёт из него только ID заказа Pagar.me и читает этот заказ через API Pagar.me с ключом того режима, в котором он был создан. Уведомления о заказах других магазинов на той же учётной записи Pagar.me игнорируются. Без вебхука PIX и boleto, оплаченные позже, подтверждаются только тогда, когда покупатель возвращается в магазин.

Дополнительно

Debug log: записывает запросы к API и уведомления в logs/wc_pgm_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки и предупреждения записываются всегда. Ключи и данные покупателей не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Заказы, их платёжные данные Pagar.me (необходимые для возвратов) и статусы заказов сохраняются. По умолчанию: выключено.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Pagar.me) и подтверждает выбор. Требуется действительный адрес электронной почты. Модуль создаёт заказ Pagar.me на сумму корзины в BRL, с позициями корзины, доставкой и подарочной упаковкой (или одной позицией Order # с номером корзины, если в корзине есть скидки), и отправляет покупателя на страницу оплаты Pagar.me. На этом этапе в вашем магазине заказа ещё нет.

Имя и адрес электронной почты покупателя передаются в Pagar.me. CPF или CNPJ берётся из поля Identification number адреса или из поля VAT number; также передаётся бразильский номер мобильного телефона. Адрес для выставления счёта передаётся только для бразильского адреса с 8-значным CEP и штатом. В PrestaShop бразильские штаты по умолчанию не предусмотрены, поэтому покупатель обычно вводит адрес на странице Pagar.me. Если у покупателя нет CPF или CNPJ, он вводит их там же.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается как оплаченный только после подтверждения Pagar.me: магазин читает заказ Pagar.me через API, и оплаченная сумма и валюта должны совпадать с корзиной. Оплаченный платёж картой, PIX или boleto создаёт заказ в статусе Payment accepted, и покупатель видит стандартную страницу подтверждения заказа с надписью Your payment with Pagar.me has been received. Выставленный PIX или boleto, которые ещё не оплачены, создают заказ в статусе Awaiting Pagar.me payment, а страница показывает Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Каждый последующий возврат снова читает заказ Pagar.me, поэтому PIX или boleto, оплаченные в это время, учитываются, даже если вебхук не пришёл. Если оплата такого заказа не прошла или истекла, страница показывает Your Pagar.me payment was not completed. Please contact us about this order.

Если покупатель возвращается, не заплатив, он оказывается в оформлении заказа с сообщением The Pagar.me payment was not completed. You can pay the order below. Если платёж был отклонён или отменён, появляется сообщение The Pagar.me payment was declined or canceled. You can try again below. Корзина сохраняется. Если заказ уже существует и его платёж не прошёл или истёк, появляется сообщение The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Если связаться с Pagar.me не удалось, открывается страница Payment confirmation, которая просит покупателя не платить повторно и предлагает кнопки Check again и Back to checkout.

Когда покупатель платит повторно, открытая страница оплаты Pagar.me используется снова, если сумма и режим те же; в противном случае она закрывается в Pagar.me, прежде чем будет создана новая. Если предыдущая попытка была оплачена в это время или её PIX либо boleto всё ещё ожидает оплаты, заказ создаётся без нового платежа. Если предыдущую страницу не удаётся закрыть, она остаётся связанной с корзиной, поэтому платёж, сделанный на ней, всё равно будет записан.

Если Pagar.me не может начать оплату, покупатель остаётся в оформлении заказа с кратким сообщением, например Could not connect to Pagar.me. Please try again in a moment., или с сообщением Pagar.me о неверных платёжных данных. Техническая причина записывается в журнал.

Вебхук работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

В модуле нет формы для ввода карты в оформлении заказа, сохранённых карт, подписок и регулярных платежей, правил рассрочки, разделённых платежей (маркетплейс), платежей картой с только авторизацией и интеграции с Pagar.me Hub.

Заказы и возвраты

Статусы заказов

No order yet: покупатель отправлен в Pagar.me и ещё не оплатил и не получил PIX или boleto. Существует только корзина.

Payment accepted: оплата подтверждена. Платёж записывается с ID заказа Pagar.me (or_...) в качестве ID транзакции, а примечание показывает заказ Pagar.me и способ оплаты.

Awaiting Pagar.me payment: выставлен PIX или boleto (или платёж картой находится на проверке) и ожидает оплаты. Заказ переходит в статус Payment accepted, когда Pagar.me подтверждает оплату.

Pagar.me payment on hold: boleto оплачено только частично; либо оплаченная сумма или валюта не совпадают с заказом (например, корзину изменили после начала оплаты); либо платёж поступил после отмены заказа; либо по оплаченному заказу открыт чарджбэк. Примечание объясняет причину. Проверьте заказ и выполните его или верните платёж.

Payment error: платёж по заказу в ожидании или на удержании не прошёл, либо его заказ Pagar.me был отменён или истёк (например, неоплаченное boleto). Если Pagar.me сообщит о платеже позже, заказ всё равно перейдёт в статус Payment accepted.

Refunded: платёж полностью возвращён через модуль или возвращён либо отменён в Pagar.me.

Каждый статус Pagar.me применяется однократно, поэтому повторные вебхуки или возвраты покупателя не добавляют примечаний и платежей. Если оплачен второй заказ Pagar.me из той же корзины, примечание просит вас вернуть дубликат в панели Pagar.me.

Блок оплаты Pagar.me

На странице заказа отображается блок Pagar.me payment с ID заказа Pagar.me и ID списаний, способом оплаты, статусом, оплаченной и возвращённой суммами, значком Test mode для тестовых платежей, историей возвратов и Pagar.me notes заказа.

Возвраты

В блоке Pagar.me payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Pagar.me. Подтвердите вопрос Refund this amount through Pagar.me? This cannot be undone. Поддерживаются полные и частичные возвраты платежей картой и PIX. Вам нужно право на редактирование заказов. Можно вернуть не больше суммы, которую Pagar.me фактически списал, поэтому после расхождения суммы лимитом является то, что заплатил покупатель, а не сумма заказа. Возврат отправляется с ключом того режима, в котором был произведён платёж, поэтому секретный ключ этого режима должен быть задан. Возврат записывается только после подтверждения Pagar.me; в противном случае блок показывает ошибку, например Pagar.me refused the refund: ... или Pagar.me did not confirm the refund, и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания с ID списания. Полный возврат переводит заказ в статус Refunded. Частичный возврат не меняет статус. Возвраты доступны, когда Pagar.me сообщил об оплате.

Возврат платежей boleto возможен только на банковский счёт покупателя. Выполните возврат в панели Pagar.me, а затем вручную зафиксируйте его в PrestaShop.

Модуль не создаёт кредит-ноты (credit slips). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Pagar.me.

Полный возврат или отмена, выполненные в панели Pagar.me, поступают через вебхук, переводят заказ в статус Refunded и добавляют примечание. Чарджбэк добавляет примечание и переводит оплаченный заказ в статус Pagar.me payment on hold.

Лицензионный ключ

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

Без действующего ключа Pagar.me не показывается покупателям в оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его в оформлении заказа нельзя. Напоминание появляется в разделе Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется снова во время работы в бэк-офисе: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Pagar.me не отображается в оформлении заказа: проверьте, что лицензия активна, что Enable / Disable включено, что задан секретный ключ текущего режима (Test secret key в тестовом режиме, Live secret key в боевом) и что валюта корзины — BRL. Страница настроек показывает предупреждение, если ключ отсутствует. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан или остаётся в статусе Awaiting Pagar.me payment: вебхук не работает. В панели Pagar.me проверьте, что вебхук существует для используемой учётной записи и режима, что его URL в точности совпадает с указанным в Webhook URL, и что выбраны перечисленные выше события. Заказ также проверяется при каждом возврате покупателя в магазин.

Вебхук отвечает verification failed, retry later: магазин не смог прочитать заказ Pagar.me через API, например потому что ключ этого режима отсутствует или API не ответил. Pagar.me повторяет вебхук.

Вебхук отвечает busy: корзина в этот момент обновлялась другим запросом, или заказ не удалось создать (например, модуль отключён). Pagar.me повторяет вебхук. Включите Debug log, чтобы увидеть причину.

Вебхук отвечает unknown order: заказ Pagar.me создан не этим магазином, например заказ другого магазина на той же учётной записи. Ничего не меняется.

Покупатель видит Pagar.me payments are not available right now: секретный ключ неверный или отсутствует. Проверьте ключ текущего режима.

Покупатель видит Pagar.me could not start the payment: Pagar.me отклонил платёжные данные, например CPF в поле Identification number адреса. Сообщение указывает проблему; полная причина записана в журнал.

Покупатель видит Pagar.me only supports payments in Brazilian Real (BRL): корзина в другой валюте.

Покупатель видит This order already has a Pagar.me payment that the store has to review: более ранний платёж по корзине требует вашей проверки. Проверьте панель Pagar.me и журнал.

Заказ в статусе Pagar.me payment on hold после оплаты: прочитайте примечания в блоке Pagar.me payment (см. Статусы заказов), затем выполните заказ или верните платёж.

Возврат не работает для boleto: платежи boleto нельзя вернуть через API. Выполните возврат в панели Pagar.me и зафиксируйте его вручную.

Возврат не работает с сообщением о режиме: платёж был произведён в тестовом или боевом режиме, а секретный ключ этого режима не задан. Введите его и повторите попытку.

Разработчики могут изменить данные заказа Pagar.me перед отправкой с помощью хука actionWcpPagarmeOrderData.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Pagar.me Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для будущей переустановки. Платёжные данные Pagar.me заказов и статусы заказов Awaiting Pagar.me payment и Pagar.me payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после переустановки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Pagar.me является товарным знаком его правообладателя. Этот модуль не аффилирован с Pagar.me и не одобрен Pagar.me.