PayTR for WooCommerce — card payments and installments (taksit) through the PayTR iFrame API

PayTR for WooCommerce connects the Turkish payment service PayTR through its iFrame API: the buyer places the order at the usual WooCommerce checkout (classic or block) and pays by card in the PayTR form right on a store page — with 3D Secure and installments (taksit). The order becomes paid only when PayTR has confirmed it with a signed notification or a Status Inquiry answer. Plugin languages: English and Türkçe.

Honestly about testing. We do not have a PayTR merchant account, so we have not made real payments through PayTR: the plugin is tested against a PayTR mock — a test server that checks signatures and request fields the way the dev.paytr.com documentation describes and sends notifications to the store the way PayTR does. On it, in clean WordPress 7.1 + WooCommerce 11.2 stores (PHP 8.3 and 7.4, MariaDB and MySQL 8, HPOS and the classic order storage), we ran real checkouts in a browser: classic and block checkout, guest and registered buyer, a coupon, shipping, variable products, installments with interest, EUR, a Turkish-language site, a declined card and a new attempt, a return to the store before the notification, repeated, forged and parallel notifications, refunds from the admin — checking the orders in the database. Before going live, make a few payments in PayTR test mode on your own account — the 7-day Pro trial is there for that.

There is a separate module for OpenCart — PayTR for OpenCart.

⚠ One Notification URL per PayTR account

PayTR sends the result of every payment to one address set in the panel: Mağaza Paneli → Ayarlar → Bildirim URL. It is a single field per PayTR store. If another site or another PayTR plugin already uses the same account, notifications will arrive at only one of the addresses, and some orders will not be confirmed automatically.

• The most reliable way is a separate PayTR account for each store; if in doubt, ask PayTR support.
• Switching from the official PayTR plugin. Once the Bildirim URL points to our plugin, notifications for the official plugin’s old orders (merchant_oid like PAYTRWOO…) come to us: the plugin answers PayTR “OK” and changes nothing, so if such orders were still waiting for payment, close them by hand using the PayTR panel. It is best to change the address when there are no unfinished payments through the old plugin.
• The plugin checks its own orders once more through Status Inquiry when the buyer returns to the “Thank you” page, and the journal (Pro) has a “Re-check” button.

What the buyer sees

• The “Credit / debit card (PayTR)” payment method at the classic and block checkout — in Turkish lira and in the currencies PayTR accepts (EUR, USD, GBP, RUB). In other currencies the method is not shown.
• The PayTR form on a store page: after “Place order” the order payment page opens with the PayTR form inside (iFrame), its height follows the form, and on a phone the form fits the screen width.
• Return to the store: after payment — the “Thank you” page, after a declined card — the same payment page with a message, a fresh form for a new attempt and a “Choose another payment method” button.
• The form language — Turkish on a Turkish site, English on others (or always tr / en).
• The installment table (Pro) on the product page: as a tab, under the price and button or as a shortcode; for a variable product the amounts are recalculated when a variation is chosen.

What the admin gets

• WooCommerce → Settings → Payments → PayTR (CatCode): Mağaza No, Mağaza Parola (key) and Mağaza Gizli Anahtar (salt) — the key and salt are stored encrypted in the database; the “Check keys” button makes a signed request to PayTR and shows whether the details are accepted.
• A ready Notification URL for the PayTR panel (like /?wc-api=ccpaytr_callback).
• Installments: all options, up to N payments (2–12) or single payment only; test mode; form language; status after payment (Processing or Completed); a WooCommerce debug log without keys.
• Notes in every order: amount, number of payments, merchant_oid, test / live; on a decline — the reason from PayTR; transaction ID = merchant_oid.

Protection against payment errors

• Paid — only by PayTR. Browser redirects mark nothing: the status changes only on a notification with a valid HMAC-SHA256 signature or a Status Inquiry answer.
• Amount and currency check. The attempt amount, the collected amount, the order total and the currency must match; otherwise the order goes “On hold” with an explanation of what exactly is wrong.
• Retries without duplicates. PayTR repeats a notification until it gets “OK”: the plugin counts only the first one and answers exactly “OK”, even if another plugin on the site prints a warning at that moment. Ten simultaneous notifications — one payment, one e-mail to the buyer, stock reduced once.
• Every attempt has its own merchant_oid. After a decline the buyer gets a fresh form right away; a late notification of an old attempt is checked against that attempt’s own amount. A payment page open in two tabs shows the same form, so a payment from either of them finds its order.
• A double payment is not lost. If an order was paid twice or a payment arrived for an order that is already cancelled, the status does not change, and the notes get an entry about the extra payment — so you can refund it.
• The buyer switched the payment method (for example, to bank transfer) after already paying in the PayTR form — the order still becomes paid through PayTR.

Pro: installment table, refunds, journal

• Installment table (taksit tablosu): World, Bonus, Axess, Maximum, CardFinans, Paraf, Advantage, Combo — your store’s rates from the PayTR Installment Rates service, refreshed once a day and with the “Refresh rates now” button. Amounts with interest (the buyer pays) or without it (peşin fiyatına taksit). Works in classic and block themes.
• Refunds from the order screen through the PayTR Refund API: full or partial, several times, each with its own reference_no; nothing above the remaining payment amount goes through.
• Single payment only for selected categories (with their subcategories) and products: PayTR receives no_installment=1, the table is not shown on such products.
• Installment interest in the order: the difference between the collected amount and the order total is added as an “Installment interest (N installments)” line — the total equals what the buyer paid.
• Payment journal (WooCommerce → PayTR journal): received, installments, card, test / live, merchant_oid, refunded and a “Re-check” button through Status Inquiry.
• Updates of Pro come from catcode.com.ua in “Dashboard → Updates” while the licence is active.

How it works step by step

1. The buyer picks “Credit / debit card (PayTR)” and presses “Place order”.
2. On the payment page the plugin creates an attempt with its own merchant_oid and gets a form token from PayTR (iFrame API, step 1) with the order amount, the cart with shipping, the currency, the buyer’s IP and the installment settings.
3. The buyer pays in the PayTR form; 3D Secure and the number of payments are chosen in the PayTR form.
4. PayTR sends the result to the Notification URL (step 2). The plugin checks the signature, compares the amount and currency, updates the order and answers “OK”.
5. The buyer returns to the “Thank you” page. If the notification has not arrived yet, the plugin asks PayTR itself through Status Inquiry.

Under the hood

• Notification URL — /?wc-api=ccpaytr_callback (the standard WC API, no REST route and no separate files): an HMAC-SHA256 signature over merchant_oid, salt, status and total_amount; the answer is exactly OK even when another plugin prints something at that moment.
• Payment attempts are stored in the order as a list of merchant_oid values with the amount of each; a notification looks the order up by this list, not by the current payment method. Simultaneous notifications and Status Inquiry go through a lock in the database, so the payment, the buyer e-mail and the stock reduction happen once — both with HPOS and with the classic order storage.
• The keys merchant_key and merchant_salt are encrypted in the database (AES-256 + HMAC) and never reach the HTML of the settings page or the debug log.
• Block checkout — the standard WooCommerce Blocks integration; the PayTR form opens on the order payment page (order-pay), as the iFrame API recommends.
• Deleting the plugin removes its settings, the rates cache and its cron jobs; orders and their PayTR payment data stay.

Installation

1. “Plugins → Add New → Upload Plugin” → zip → “Activate”.
2. WooCommerce → Settings → Payments → PayTR (CatCode): enter Mağaza No, Mağaza Parola and Mağaza Gizli Anahtar from the PayTR panel (Destek & Kurulum → Entegrasyon Bilgileri), save and press “Check keys”.
3. Copy the Notification URL from the settings to the PayTR panel: Ayarlar → Bildirim URL.
4. Keep test mode on, make a test payment, then turn test mode off.