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.