Pix и BolePix через Banco Inter для OpenCart — оплата в Бразилии

Banco Inter Pix & BolePix для OpenCart 4.x, 3.x и 2.3 принимает оплату Pix напрямую через API бизнес-счёта Banco Inter (Inter Empresas). Посредника нет: счёт на оплату создаётся в вашем аккаунте, деньги идут на ваш Pix-ключ, а доступы к интеграции ваши собственные. Магазин работает в бразильских реалах (BRL).

Что нужно от банка. Бизнес-счёт Inter Empresas (с бразильским CNPJ). Интеграцию создают в интернет-банкинге Inter: после её одобрения банк выдаёт Client ID и Client Secret, а также файлы сертификата (.crt) и ключа (.key), которые магазин загружает в настройки модуля. Сертификат действует один год.

Что видит покупатель

На чекауте покупатель выбирает «Pix» или, в Pro, «Boleto with Pix». После «Continue to payment» открывается страница оплаты: QR-код, код «Pix copia e cola» с кнопкой копирования, три коротких шага и таймер. Когда банк получает деньги, страница сама переходит на «заказ принят». Для BolePix покупатель видит строку boleto, кнопку PDF из банка, срок оплаты и тот же Pix-код; те же данные приходят письмом. Интерфейс для покупателя — português do Brasil и English.

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

Расширения → Модули → Banco Inter Pix & BolePix: вкладки «General», «Checkout», «Order statuses» и «Pro». На вкладке «General» вписываете Client ID и Client Secret, загружаете файлы .crt и .key (файлом или текстом) и Pix-ключ счёта. Client Secret, сертификат и ключ хранятся в базе зашифрованными и назад не показываются; модуль показывает дату окончания сертификата и напоминает письмом за 30 и за 7 дней. Кнопка «Check connection» показывает ответ банка простыми словами, «Register the webhook» регистрирует адрес вебхука для вашего Pix-ключа.

Вкладка «Checkout» задаёт название и описание метода по языкам, минимальную сумму и гео-зону. Для других валют магазина есть выбор: предлагать оплату в BRL по курсу магазина или скрыть метод. Время на оплату одного Pix-кода — от 10 до 1440 минут (по умолчанию 30); потом покупатель нажимает «Pay again» и получает новый код, а старый заряд закрывается в банке. CPF и CNPJ плательщика сверяются по контрольным цифрам; для Pix поле необязательное. На вкладке «Order statuses» выбираете статусы заказа для каждого события.

Оплаченным заказ становится только после того, как модуль прочитал заряд в банке своими ключами: вебхук банка лишь сообщает, что пора спросить. Страница оплаты сама ловит оплату, даже если вебхук опоздал. Pix на другую сумму не закрывает заказ, а ставит его «на рассмотрение» с заметкой. На странице заказа есть вкладка оплаты с состоянием заряда и кнопкой «Check at the bank».

BolePix (Pro): boleto с Pix-кодом, который банк выдаёт на заказ. Задаёте срок оплаты (1–30 дней), штраф в процентах, пеню в процентах в месяц и через сколько дней после срока банк сам отменит неоплаченный boleto (0–60). Заказ получает статус «BolePix issued», покупатель получает строку boleto, Pix-код и ссылку письмом. Оплаченный boleto переводит заказ в оплаченный, отменённый или просроченный — в «BolePix not paid». Нужны CPF или CNPJ покупателя и бразильский адрес со штатом и CEP; минимальная сумма boleto — R$ 2,50.

Возврат Pix (Pro) — полный и частичный из вкладки заказа и из журнала платежей. Скидка — отдельная строка в итогах заказа («Discount for paying with Pix») в процентах; модуль сам добавляет и включает этот итог. Скидка действует на метод оплаты целиком (Pix и BolePix, если включено), налоги после неё не пересчитываются. Сторож платежей раз в час находит открытые заряды, о которых банк не сообщил, закрывает заказы и отменяет boleto, отменённые банком; работает с планировщиком OpenCart 4 или с cron-адреса. Журналы — платежей и запросов к банку (метод, путь, код ответа, время; без тел запросов и данных покупателей).

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

1. Устанавливаете архив для своей версии OpenCart и включаете модуль.
2. В интернет-банкинге Inter Empresas создаёте интеграцию с нужными разрешениями, ждёте одобрения банка и скачиваете .crt и .key.
3. В настройках модуля вписываете Client ID, Client Secret, загружаете .crt и .key, указываете Pix-ключ, нажимаете «Check connection».
4. Нажимаете «Register the webhook»: банк будет сообщать магазину об оплате.
5. Покупатель выбирает Pix, видит QR-код и код, платит в приложении своего банка; заказ становится оплаченным сам.
6. В Pro включаете BolePix, скидку за Pix, сторож платежей и журналы.

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

• API Inter: OAuth (client credentials) с взаимной TLS-аутентификацией сертификатом интеграции; Pix cob и вебхук, Cobrança BolePix.
• Вебхук банка лишь подсказка: заказ становится оплаченным после чтения заряда из банка своими ключами, а не по содержимому вызова.
• QR-код рисуется в браузере покупателя встроенной библиотекой (MIT), код не передаётся сервисам генерации QR.
• У одного Pix-ключа один вебхук в банке: если его уже использует другая система, регистрация нового адреса заменит старый, о чём модуль предупреждает.
• Сертификат интеграции действует один год (30 дней в тестовой среде банка); новая загрузка файлов — в настройках модуля.
• Банк ограничивает вызовы (120 в минуту на метод): модуль не опрашивает банк без нужды.
• Возврат из админки — для оплат Pix; BolePix, оплаченный через Pix, возвращается в банке.
• События OpenCart без правок ядра; при обновлении модуля настройки сохраняются.
• Интерфейс português do Brasil и English; тестовая среда банка включается в настройках.

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

1. Расширения → Установка: загрузите архив для своей версии без переименования файла (OpenCart 4 — cc_bancointer.ocmod.zip, 3.x — cc_bancointer-oc3.ocmod.zip, 2.3 — cc_bancointer-oc2.ocmod.zip).
2. Для 3.x и 2.3: Расширения → Модификаторы → Обновить.
3. Расширения → Оплата → Banco Inter Pix & BolePix: установите и откройте.
4. Впишите Client ID, Client Secret, загрузите .crt и .key, укажите Pix-ключ.
5. Нажмите «Register the webhook». Для Pro: вставьте ключ или запустите пробный период на вкладке Pro.