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

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

Чесно про тестування. У нас немає мерчант-акаунта PayTR, тому справжніх платежів через PayTR ми не проводили: плагін перевірено на моку PayTR — тестовому сервері, який перевіряє підписи й поля запитів так, як описано в документації dev.paytr.com, і надсилає сповіщення в магазин так, як це робить PayTR. На ньому в чистих магазинах WordPress 7.1 + WooCommerce 11.2 (PHP 8.3 і 7.4, MariaDB і MySQL 8, HPOS і класичне сховище замовлень) пройдено справжні оформлення в браузері: класичний і блоковий чекаут, гість і покупець з акаунтом, купон, доставка, варіативні товари, розстрочка з відсотками, EUR, турецька мова сайту, відмова картки й повторна спроба, повернення в магазин раніше за сповіщення, повторні, підроблені й паралельні сповіщення, повернення коштів з адмінки — з перевіркою замовлень у базі. Перед запуском проведіть кілька платежів у тестовому режимі PayTR на своєму акаунті — для цього є 7-денний тріал Pro.

Для OpenCart є окремий модуль — PayTR для OpenCart.

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

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

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

Як це виглядає для покупця

• Спосіб оплати «Credit / debit card (PayTR)» на класичному і блоковому чекауті — у турецьких лірах і у валютах, які PayTR приймає (EUR, USD, GBP, RUB). В інших валютах спосіб не показується.
• Форму PayTR на сторінці магазину: після «Place order» відкривається сторінка оплати замовлення з формою PayTR усередині (iFrame), висота підлаштовується під форму, на телефоні форма вміщується в ширину екрана.
• Повернення в магазин: після оплати — сторінка «Дякуємо», після відмови картки — та сама сторінка оплати з повідомленням, новою формою для повторної спроби і кнопкою «Choose another payment method».
• Мову форми — турецьку на турецькому сайті, англійську на інших (або завжди tr / en).
• Таблицю розстрочки (Pro) на сторінці товару: вкладкою, під ціною й кнопкою або шорткодом; для варіативного товару суми перераховуються при виборі варіації.

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

• WooCommerce → Налаштування → Платежі → PayTR (CatCode): Mağaza No, Mağaza Parola (key) і Mağaza Gizli Anahtar (salt) — ключ і сіль зберігаються в базі зашифрованими; кнопка «Check keys» робить підписаний запит до PayTR і показує, чи прийняті дані.
• Готовий Notification URL для панелі PayTR (вигляду /?wc-api=ccpaytr_callback).
• Розстрочка: усі варіанти, до N платежів (2–12) або лише одноразово; тестовий режим; мова форми; статус після оплати (Processing або Completed); журнал налагодження WooCommerce без ключів.
• Нотатки в кожному замовленні: сума, кількість платежів, merchant_oid, test / live; при відмові — причина від PayTR; transaction ID = merchant_oid.

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

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

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

• Таблиця розстрочки (taksit tablosu): World, Bonus, Axess, Maximum, CardFinans, Paraf, Advantage, Combo — ставки вашого магазину з сервісу PayTR Installment Rates, оновлення раз на добу і кнопкою «Refresh rates now». Суми з відсотками (платить покупець) або без них (peşin fiyatına taksit). Працює в класичних і блокових темах.
• Повернення з картки замовлення через PayTR Refund API: повне або часткове, кілька разів, кожне з власним reference_no; більше за залишок платежу не пропускає.
• Лише одноразово для вибраних категорій (разом із підкатегоріями) і товарів: PayTR отримує no_installment=1, таблиця на таких товарах не показується.
• Відсотки розстрочки в замовленні: різниця між зібраною сумою і сумою замовлення додається рядком «Installment interest (N installments)» — підсумок дорівнює тому, що заплатив покупець.
• Журнал платежів (WooCommerce → PayTR journal): отримано, розстрочка, картка, test / live, merchant_oid, повернено і кнопка «Re-check» через Status Inquiry.
• Оновлення Pro приходять з catcode.com.ua у «Майстерня → Оновлення», поки діє ліцензія.

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

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

Що під капотом

• Notification URL — /?wc-api=ccpaytr_callback (штатний WC API, без REST і без окремих файлів): підпис HMAC-SHA256 з merchant_oid, salt, status і total_amount; відповідь — рівно OK навіть тоді, коли інший плагін у цей момент щось виводить.
• Спроби оплати зберігаються в замовленні списком merchant_oid із сумою кожної; сповіщення шукає замовлення за цим списком, а не за поточним способом оплати. Одночасні сповіщення й Status Inquiry проходять через блокування в базі, тож оплата, лист покупцю і списання складу відбуваються один раз — і в HPOS, і в класичному сховищі замовлень.
• Ключі merchant_key і merchant_salt у базі зашифровані (AES-256 + HMAC) і не потрапляють у HTML сторінки налаштувань і в журнал налагодження.
• Блоковий чекаут — штатна інтеграція WooCommerce Blocks; форма PayTR відкривається на сторінці оплати замовлення (order-pay), як радить iFrame API.
• Видалення плагіна прибирає його налаштування, кеш ставок і завдання крону; замовлення і їхні дані про оплату PayTR лишаються.

Як встановити

1. «Плагіни → Додати новий → Завантажити плагін» → zip → «Активувати».
2. WooCommerce → Налаштування → Платежі → PayTR (CatCode): введіть Mağaza No, Mağaza Parola і Mağaza Gizli Anahtar з панелі PayTR (Destek & Kurulum → Entegrasyon Bilgileri), збережіть і натисніть «Check keys».
3. Скопіюйте Notification URL з налаштувань у панель PayTR: Ayarlar → Bildirim URL.
4. Залиште тестовий режим, проведіть тестовий платіж, потім вимкніть тестовий режим.