PayTR для OpenCart — оплата карткою і розстрочка (taksit) через PayTR iFrame API

PayTR для OpenCart підключає турецький платіжний сервіс PayTR через iFrame API: покупець оплачує карткою у формі PayTR прямо на сторінці магазину, з 3D Secure і розстрочкою (taksit), а замовлення стає оплаченим лише тоді, коли PayTR це підтвердив підписаним сповіщенням. Один модуль для OpenCart 4, 3 і 2.3, мови English і Türkçe.

Чесно про тестування. У нас немає мерчант-акаунта PayTR, тому справжніх платежів через PayTR ми не проводили. Модуль написано за офіційною документацією dev.paytr.com (формули підписів, поля запитів і відповідей) і перевірено в чистих магазинах на OpenCart 4.1.0.3, 4.0.2.3 (драйвер pdo), 3.0.5.0 і 2.3.0.2 на PHP 7.0 з тестовим сервером, який перевіряє підписи так, як описано в документації PayTR. Перевірені справжні оформлення на вітрині з купоном, доставкою, опціями товару, у другій валюті (EUR) і турецькою мовою, відмова картки, повторні й підроблені сповіщення, повернення до сповіщення, подвійна оплата, зміна кошика під час оплати, повернення коштів з адмінки — з перевіркою замовлення і рядків підсумків у базі. Перед запуском проведіть кілька платежів у тестовому режимі PayTR на своєму акаунті — для цього є 7-денний тріал Pro.

Магазин на WooCommerce? Для нього є окремий плагін PayTR для WooCommerce: та сама форма PayTR (iFrame API) на класичному й блоковому чекауті, підписані сповіщення й Status Inquiry, а в Pro — таблиця розстрочки на товарі й повернення з картки замовлення.

⚠ Один Notification URL на акаунт PayTR

PayTR надсилає результат кожної оплати на адресу, вказану в панелі: Mağaza Paneli → Ayarlar → Bildirim URL. Це одне поле на налаштування магазину. Якщо тим самим акаунтом PayTR уже користується інший сайт чи інший модуль PayTR, сповіщення будуть приходити лише на одну з адрес, і частина замовлень не отримає підтвердження автоматично.

• Найнадійніше — окремий акаунт PayTR на кожен магазин; якщо сумніваєтесь, уточніть у підтримці PayTR.
• Наш модуль на сповіщення з чужими merchant_oid відповідає «OK» і нічого не змінює, тож він не заважає іншому сайту, якщо адреса вказана на наш.
• Свої замовлення модуль додатково перевіряє через Status Inquiry, коли покупець повертається в магазин після оплати, а в журналі (Pro) є кнопка «Перевірити ще раз».

Що бачить покупець

• Спосіб оплати «Kredi / banka kartı (PayTR)» на чекауті — у турецьких лірах і у валютах, які PayTR увімкнув магазину (EUR, USD, GBP, RUB). В інших валютах спосіб не показується.
• Форму PayTR на сторінці магазину: після «Оплатити карткою» відкривається сторінка «Kartla ödeme» з формою PayTR усередині (iFrame), висота підлаштовується під форму. У тестовому режимі над формою — попередження, що гроші не списуються.
• Повернення в магазин: після оплати — сторінка «Дякуємо», після відмови — чекаут з тим самим кошиком, і можна одразу натиснути «Оплатити» ще раз.
• Таблицю розстрочки (Pro) на картці товару: вкладкою поруч з описом або під кнопкою «Купити», щомісячний платіж і сума для кожної програми карток.

Що отримує адмін

• Налаштування: Mağaza No, Mağaza Parola (key) і Mağaza Gizli Anahtar (salt) — ключ і сіль зберігаються зашифрованими і після збереження не показуються; кнопка «Перевірити дані» робить підписаний запит до PayTR з даними на екрані.
• Готовий Notification URL для панелі PayTR — з https, якщо вітрина на SSL.
• Розстрочка: усі варіанти, до N платежів (2–12) або лише одноразово; тестовий режим; мова форми; час на оплату; геозона; статуси для оплати, перевірки, відмови й повернення.
• Історію в кожному замовленні: сума, кількість платежів, merchant_oid і звідки прийшло підтвердження (сповіщення чи Status Inquiry); при відмові — причина від PayTR.
• Журнал налагодження cc_paytr.log без ключів, солі й підписів.

Захист від помилок оплати

• Оплачено — лише за PayTR. Переходи браузера нічого не позначають: статус змінює тільки сповіщення з правильним підписом HMAC-SHA256 або відповідь Status Inquiry.
• Звірка суми. Сума спроби, валюта, зібрана сума і поточна сума замовлення мають збігатися; інакше статус «на перевірку» з поясненням, що саме не так.
• Повтори без дублів. PayTR повторює сповіщення, доки не отримає «OK»: модуль враховує лише перше і відповідає рівно «OK», без жодного зайвого символу.
• Подвійна оплата не губиться. Якщо покупець оплатив те саме замовлення двічі (дві вкладки), статус не змінюється, а в історії з’являється запис про другий платіж — щоб ви повернули його в панелі PayTR.
• Кнопка «Назад» після оплати не відправить те саме замовлення в PayTR ще раз.

Pro: таблиця розстрочки, відсотки в замовленні, журнал і повернення

• Таблиця розстрочки (taksit tablosu) на картці товару: World, Bonus, Axess, Maximum, CardFinans, Paraf, Advantage, Combo — ставки з сервісу PayTR Installment Rates, оновлення раз на добу. Показувати суми з відсотками (платить покупець) або без них (peşin fiyatına).
• Лише одноразово для вибраних категорій (разом із підкатегоріями) і товарів: PayTR отримує no_installment=1, таблиця не показується.
• Відсотки розстрочки в замовленні: різниця між зібраною сумою і сумою товарів додається рядком «Installment interest (N installments)» один раз — підсумок замовлення дорівнює тому, що заплатив покупець.
• Журнал платежів: отримано, відсотки, розстрочка, test / live, merchant_oid, повернено.
• Повернення з адмінки: повне або часткове, кілька разів поспіль; від’ємні, нечислові й більші за залишок суми відхиляються, статус «Повернено» ставиться лише після повного повернення.

Як це працює крок за кроком

1. Покупець обирає «Kredi / banka kartı (PayTR)» і натискає «Оплатити карткою».
2. Модуль створює спробу оплати з власним merchant_oid і отримує в PayTR токен форми (iFrame API, крок 1) із сумою замовлення, кошиком, валютою й налаштуваннями розстрочки.
3. Покупець оплачує у формі PayTR на сторінці магазину; 3D Secure і вибір кількості платежів — у формі PayTR.
4. PayTR надсилає результат на Notification URL (крок 2). Модуль перевіряє підпис, звіряє суму й валюту, міняє статус замовлення і відповідає «OK».
5. Покупець повертається на сторінку «Дякуємо». Якщо сповіщення ще не прийшло, модуль один раз питає PayTR через Status Inquiry.

Під капотом

• iFrame API PayTR: get-token з підписом HMAC-SHA256 за документацією dev.paytr.com, сповіщення з перевіркою hash, Status Inquiry (durum-sorgu), Refund (iade), Installment Rates (taksit-oranlari).
• Окремі таблиці модуля для спроб оплати, платежів і ставок; запис налаштувань по ключу, без перезапису всієї групи.
• Без правок ядра і без OCMOD: штатне платіжне розширення OpenCart і подія на сторінку товару для таблиці розстрочки.
• Після видалення модуля таблиці платежів лишаються — журнал і повернення доступні після повторного встановлення.

Встановлення

1. OpenCart 4 і 3: «Розширення → Інсталятор» → завантажте zip для своєї версії. OpenCart 2.3: скопіюйте вміст папки upload/ з архіву в корінь магазину.
2. «Розширення → Оплата» → PayTR (CatCode) → встановити → редагувати.
3. Введіть Mağaza No, Mağaza Parola і Mağaza Gizli Anahtar з панелі PayTR (Destek & Kurulum → Entegrasyon Bilgileri), натисніть «Перевірити дані».
4. Скопіюйте Notification URL з налаштувань модуля в панель PayTR: Ayarlar → Bildirim URL → Değiştir.
5. Увімкніть тестовий режим, проведіть тестовий платіж, потім вимкніть його.

Версії

• 1.0.0 — перший випуск: iFrame API, Notification URL, Status Inquiry, звірка суми й валюти, таблиця розстрочки, «лише одноразово», відсотки розстрочки в замовленні, журнал і повернення; OpenCart 4, 3 і 2.3; English і Türkçe.