Appmax для OpenCart — Pix, карта в рассрочку и boleto на чекауте (Бразилия)

Appmax Pix, Card & Boleto для OpenCart 4.x, 3.x и 2.3 принимает платежи магазина через бразильский платёжный сервис Appmax: Pix с QR-кодом, кредитную карту с рассрочкой до 12 платежей и boleto bancário. Покупатель платит на странице магазина, заказ подтверждается, когда Appmax получает деньги, а админ видит все попытки, суммы и возвраты в заказе.

Что нужно от Appmax. Свой аккаунт мерчанта Appmax с доступом к экрану API в панели (Client ID и Client Secret) и, для оплаты картой, External ID магазина. Валюта магазина — реал (BRL); в других валютах метод либо ведёт оплату в BRL по курсу магазина, либо скрывается, как вы выберете. Appmax берёт свои комиссии за платежи по вашему тарифу.

Что получает покупатель

На шаге оплаты покупатель видит метод Appmax. В бесплатной версии это Pix: после «Continue to payment» открывается страница с QR-кодом, кодом «copia e cola» с кнопкой копирования и таймером до конца действия кода. Когда деньги приходят, страница сама переходит на успешный заказ, без клика «Вернуться в магазин».

В Pro на чекауте есть ещё два способа. Карта: форма с полями Appmax JS, так что номер карты идёт прямо в Appmax и не проходит через магазин; рассрочка до 12 платежей по тарифам Appmax с показом процентов и итога, либо без процентов за счёт магазина. Boleto: линия для оплаты, дата, кнопки «Скопировать линию» и «Открыть boleto», те же данные приходят в письме.

CPF или CNPJ плательщика проверяется (поддержаны и новые буквенно-цифровые CNPJ); для Pix он необязателен, для карты и boleto нужен. Телефон с DDD модуль спрашивает, только если его нет в заказе. Поля CPF, номер дома и район берутся из нашего модуля бразильских полей. Если карту отклонили, покупатель видит понятное сообщение, корзина остаётся, и можно попробовать другую карту или другой способ.

Что получает админ

Extensions → Extensions → Payments → Appmax Pix, Card & Boleto: вкладки «General», «Checkout», «Order statuses» и «Pro». Вы вставляете Client ID, Client Secret и External ID из панели Appmax, выбираете sandbox или боевой режим и нажимаете «Check connection»: модуль получает токен и проверяет соединение. Секрет хранится зашифрованным и никогда не показывается обратно.

Здесь же адрес вебхука с секретным ключом: его вставляют в панели Appmax → API → Webhooks. Appmax ничего не подписывает, поэтому каждое уведомление лишь подсказка: модуль перечитывает заказ в Appmax и только тогда меняет статус. Есть время на оплату Pix (10–1440 минут), гео-зона, минимальная сумма, название и описание метода для каждого языка и статусы заказа.

На странице заказа появляется блок Appmax: статус, сумма, способ (например «card (2x)»), номер заказа в Appmax, референс и таблица попыток оплаты с ответом Appmax. Кнопки «Check at Appmax» и (Pro) «Refund» работают прямо отсюда; для возврата можно указать часть суммы или оставить поле пустым, чтобы вернуть всё.

В Pro возврат идёт полностью или частично для карты и Pix. Возвраты и chargeback, сделанные в панели Appmax, меняют заказ в магазине: через вебхук и сторожа. Сторож (планировщик OpenCart 4 или cron-адрес) закрывает платежи, которые покупатель бросил, и доводит до конца карты на антифроде. Восстановление продаж Appmax (в самом Appmax это beta) по вашему выбору передаёт покупателя и корзину на шаге оплаты; оно выключено по умолчанию.

Журнал платежей показывает каждую попытку: заказ, сумму, способ, статус модуля, номер в Appmax, возвращённую сумму и кнопки действий; отдельный журнал запросов к Appmax содержит последние вызовы с ответом и временем.

Как это работает, шаг за шагом

1. Установите архив для вашей версии OpenCart и включите модуль в Payments.
2. В панели Appmax создайте учётные данные (API → Credenciais) и вставьте Client ID и Client Secret в настройки модуля.
3. Нажмите «Check connection» и сохраните.
4. Вставьте адрес вебхука в Appmax → API → Webhooks (события Pedidos и Pagamentos).
5. Оформите тестовый заказ в sandbox: Pix, QR-код и автопереход после оплаты.
6. В Pro включите карту и boleto, настройте рассрочку и возвраты.

Что под капотом

• Appmax API (docs.appmax.com.br): токен OAuth2, клиент, заказ, платежи Pix, boleto и карта, рассрочка, возвраты. Секрет шифруется, имена, документы, телефоны и токены карт маскируются в журнале.
• Номер карты не попадает в магазин: его принимает Appmax JS в браузере покупателя и возвращает токен. Скрипт Appmax загружается с его CDN, как того требует Appmax.
• Сумма платежа сверяется с суммой заказа; вторая оплата уже оплаченного заказа переводит его в статус «на проверку» (Needs review).
• Каждая попытка (новый код Pix, вторая карта) создаёт в Appmax отдельный заказ, поэтому в панели мерчанта на один заказ магазина может быть несколько «pendente». Отменить выданный Pix через API нельзя: если Pix просрочен, покупатель получает новый код, а поздняя оплата старого показывается как двойная и попадает на проверку.
• Вебхуки Appmax не подписаны: от сторонних вызовов защищает секретный ключ в адресе, а статус всегда берётся перечитыванием заказа в Appmax.
• Проценты рассрочки входят в сумму, которую списывает Appmax, и записываются в заметку истории заказа; отдельной строкой в итогах заказа OpenCart они не добавляются.
• Подписки OpenCart (периодические платежи) метод не поддерживает: корзины с подписками его не видят. Apple Pay и Google Pay в модуль не входят.
• Восстановление продаж передаёт данные покупателя и корзины в Appmax до оплаты: вопрос согласия по LGPD решает магазин.
• Интерфейс на английском и португальском (Brasil).

Как установить

1. Extensions → Installer: загрузите архив для вашей версии, не переименовывая файл (OpenCart 4 — cc_appmax.ocmod.zip, 3.x — cc_appmax-oc3.ocmod.zip, 2.3 — cc_appmax-oc23.ocmod.zip).
2. Для 3.x и 2.3: Extensions → Modifications → Refresh.
3. Extensions → Payments → Appmax Pix, Card & Boleto: установите и откройте настройки.
4. Вставьте Client ID, Client Secret и External ID, нажмите «Check connection» и сохраните.
5. Вставьте адрес вебхука в панели Appmax.
6. Для Pro: введите ключ или запустите пробный период на вкладке «Pro».