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».