VibeFox PagSeguro for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

HTTPS: ваш магазин должен быть доступен из интернета по HTTPS, чтобы PagBank мог отправлять уведомления о платежах.

Учётная запись PagBank: рабочий токен для реальных платежей и тестовый токен sandbox для проверок. Рабочий токен: войдите в учётную запись PagBank, откройте Venda online > Integrações и нажмите Gerar token; PagBank пришлёт токен по e-mail. Sandbox: создайте учётную запись sandbox на портале разработчиков PagBank и скопируйте её токен. Токены sandbox и рабочий работают только в своей среде.

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

Установка

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

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

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

4. Введите токен sandbox и, для приёма реальных платежей, рабочий токен.

5. Включите Enable / Disable и нажмите Save. Делайте тестовые платежи при включённом Sandbox Mode, затем выключите его, чтобы принимать реальные платежи.

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

Настройка

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

PagSeguro / PagBank

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Учётная запись PagBank

Раздел объясняет, где получить токены, и содержит ссылки на вашу учётную запись PagBank и страницу PagBank о токенах.

Sandbox Mode: Enable sandbox/test mode (no real charges). Новые платежи уходят в sandbox PagBank с токеном sandbox, а покупатели видят под способом оплаты SANDBOX MODE — Using test environment. No real charges. Проверка статуса и возвраты заказа всегда используют среду и токен, с которыми был создан его платёж. По умолчанию: включено.

Sandbox token: токен sandbox PagBank. Используется, пока включён режим sandbox.

Production token: рабочий токен PagBank (Bearer). Используется, когда режим sandbox выключен. Храните его в секрете.

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

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

Уведомления о платежах

Notification URL: каждый платёж сообщает PagBank, куда отправлять изменения статуса, поэтому в PagBank ничего настраивать не нужно. Раздел показывает URL. При включённых понятных ссылках он выглядит так: https://your-shop/module/wcp_pagseguro_gateway/webhook. Адрес должен быть доступен из интернета по HTTPS.

Уведомления с заголовком x-authenticity-token проверяются токеном той среды, в которой был создан платёж; неверная подпись отклоняется. Само тело уведомления никогда не считается надёжным: модуль всегда читает платёж и заказ PagBank через API PagBank (статус, сумма, валюта) перед созданием или изменением заказа. Без уведомлений заказ создаётся, когда покупатель после оплаты возвращается в магазин.

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

Debug log: Log API requests and notifications записывает подробности в logs/wc_psg_debug.log.php в папке модуля. Файл нельзя открыть из веб-браузера. Журналы не содержат токенов и данных покупателей. Ошибки записываются всегда. По умолчанию: выключено.

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию PagSeguro / PagBank) и подтверждает. Модуль создаёт платёж в PagBank на сумму корзины в BRL как одну позицию, Order # с номером корзины и названием вашего магазина, и отправляет покупателя на страницу оплаты PagBank. Имя и e-mail покупателя, CPF или CNPJ из поля Identification number или VAT number адреса и бразильский номер телефона подставляются, если они есть у магазина; покупатель может дополнить или исправить их на странице PagBank. Покупатель платит способами, включёнными в вашей учётной записи PagBank, например кредитной картой, PIX или boleto. Страница оплаты истекает через 120 минут. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения PagBank: модуль читает платёж через API PagBank, когда приходит уведомление или когда покупатель возвращается, и одно лишь возвращение никогда не отмечает заказ оплаченным. Затем заказ создаётся, и покупатель видит страницу подтверждения заказа с сообщением Your payment with PagBank has been received. Для созданного boleto или PIX, а также платежа на проверке страница показывает Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Если такой платёж позже отклоняется или отменяется, страница показывает Your PagBank payment was not completed. Please contact us about this order. Если PagBank ещё не подтвердил платёж, когда покупатель возвращается, появляется страница Payment confirmation с сообщением We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. и кнопкой Check again.

Если платёж не был завершён, покупатель возвращается к оформлению заказа с сообщением The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. или The payment was declined by PagBank. Please try again with another card or payment method. Корзина сохраняется. Если заказ, ожидавший оплаты boleto или PIX, был отменён, покупатель видит The PagBank payment was cancelled, so the order was cancelled.

Когда покупатель платит снова, открытый платёж PagBank используется повторно, если сумма и среда те же и он не истекает в ближайшие 10 минут. В противном случае предыдущий платёж деактивируется, и его нельзя оплатить. Платёж, сделанный раньше на предыдущей странице, по-прежнему учитывается для корзины, и создаётся заказ вместо нового платежа.

Если PagBank не может начать платёж, покупатель остаётся на оформлении заказа с коротким сообщением, например PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. или Could not connect to PagBank. Please try again in a moment. Техническая причина записывается в журнал.

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

В модуле нет формы ввода карты на сайте, нет сохранённых карт, подписок и регулярных платежей, разделённых платежей и маркетплейсов. Способы оплаты и рассрочка настраиваются в вашей учётной записи PagBank.

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

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

Заказа пока нет: покупатель был отправлен в PagBank и не заплатил, карта была отклонена или страница оплаты истекла. Существует только корзина, и покупатель может оплатить снова.

Payment accepted: платёж подтверждён с ожидаемой суммой и валютой. Платёж записывается с идентификатором списания PagBank (charge ID) в качестве ID транзакции, а примечание показывает сумму, способ оплаты и charge ID.

Awaiting PagBank payment: boleto или PIX создан и ждёт оплаты, либо платёж находится на проверке. Заказ переходит в Payment accepted, когда PagBank сообщает об оплате.

PagBank payment on hold: PagBank сообщил сумму или валюту, отличные от корзины (например, корзину изменили после создания страницы оплаты), платёж поступил после отмены заказа (проверьте остатки, затем завершите заказ или верните платёж в PagBank), либо платёж картой был авторизован, но не списан (спишите его в PagBank). Примечание объясняет это. Фактически полученная сумма записывается в заказ.

Payment error: платёж, который ожидал оплаты или находился на проверке, был отклонён.

Canceled: ожидавший оплаты платёж, например истёкший boleto или PIX, был отменён.

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

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

Блок «PagBank payment»

На странице заказа показан блок PagBank payment с checkout PagBank, идентификаторами заказа и списания PagBank (charge ID), способом оплаты, статусом, оплаченной и возвращённой суммой, значком Sandbox для платежей sandbox, историей возвратов и PagBank notes заказа.

Возвраты

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

Модуль не создаёт кредитных нот. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через PagBank.

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

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

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

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

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

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

PagBank не появляется при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено, токен текущего режима заполнен (Sandbox token в режиме sandbox, Production token в режиме live) и валюта корзины — BRL. Страница настроек показывает предупреждение, если токен не заполнен или валюта магазина не BRL. В разделе Payment > Preferences проверьте, что модуль разрешён для BRL, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: PagBank ещё не сообщил о платеже, а покупатель не вернулся в магазин. Заказ создаётся сразу, как только приходит уведомление. Проверьте, что ваш магазин доступен из интернета по HTTPS по адресу Notification URL, и включите Debug log, чтобы видеть уведомления.

Уведомление отвечает Invalid signature: x-authenticity-token не совпадает с токеном той среды, в которой был произведён платёж, или этот токен не сохранён. Проверьте, что в настройках указан правильный токен.

Уведомление отвечает Verification failed, retry later: не удалось связаться с API PagBank, отсутствует токен среды платежа, или корзину в тот же момент обрабатывал другой запрос. PagBank повторит уведомление.

Уведомление отвечает Order not found: уведомление относится к корзине, которая не была оплачена этим модулем в этом магазине. Ничего не меняется.

Покупатель видит PagBank payments are temporarily unavailable. Please choose another payment method.: токен текущего режима не заполнен или PagBank его отклонил.

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

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

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

Удаление

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

PagSeguro и PagBank являются товарными знаками их соответствующих владельцев. Этот модуль не связан с PagSeguro или PagBank и не одобрен ими.