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. Оставьте тестовый режим, проведите тестовый платёж, затем выключите тестовый режим.