PayTR for OpenCart — card payments and installments (taksit) via the PayTR iFrame API

PayTR for OpenCart connects the Turkish payment service PayTR through its iFrame API: the buyer pays by card in the PayTR form right on a store page, with 3D Secure and installments (taksit), and the order becomes paid only when PayTR has confirmed it with a signed notification. One module for OpenCart 4, 3 and 2.3, 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 module is written from the official dev.paytr.com documentation (signature formulas, request and response fields) and tested in clean stores on OpenCart 4.1.0.3, 4.0.2.3 (pdo driver), 3.0.5.0 and 2.3.0.2 on PHP 7.0 against a test server that checks signatures the way the PayTR documentation describes. We ran real storefront checkouts with a coupon, shipping, product options, in a second currency (EUR) and in Turkish, a declined card, repeated and forged notifications, a return before the notification, a double payment, a cart change during payment and refunds from the admin — checking the order and its total lines 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.

Running WooCommerce? There is a separate PayTR for WooCommerce plugin: the same PayTR form (iFrame API) at the classic and block checkout, signed notifications and Status Inquiry, and in Pro an installment table on the product page and refunds from the order screen.

⚠ One Notification URL per PayTR account

PayTR sends the result of every payment to the address set in the panel: Mağaza Paneli → Ayarlar → Bildirim URL. It is a single field in the store settings. If another site or another PayTR module already uses the same PayTR 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.
• Our module answers “OK” to notifications with foreign merchant_oid values and changes nothing, so it does not get in the way of another site if the address points to ours.
• The module checks its own orders once more through Status Inquiry when the buyer returns to the store after paying, and the journal (Pro) has a “Re-check” button.

What the buyer sees

• The “Kredi / banka kartı (PayTR)” payment method at the checkout — in Turkish lira and in the currencies PayTR has enabled for the store (EUR, USD, GBP, RUB). In other currencies the method is not shown.
• The PayTR form on a store page: after “Pay by card” the “Kartla ödeme” page opens with the PayTR form inside (iFrame), its height follows the form. In test mode a warning above the form says no money is charged.
• Return to the store: after payment — the “Thank you” page, after a decline — the checkout with the same cart, and “Pay” can be pressed again right away.
• The installment table (Pro) on the product page: as a tab next to the description or under the “Add to cart” button, the monthly payment and total for every card programme.

What the admin gets

• Settings: Mağaza No, Mağaza Parola (key) and Mağaza Gizli Anahtar (salt) — the key and salt are stored encrypted and not shown after saving; the “Check credentials” button makes a signed request to PayTR with the details on screen.
• A ready Notification URL for the PayTR panel — with https if the storefront is on SSL.
• Installments: all options, up to N payments (2–12) or single payment only; test mode; form language; payment time limit; geo zone; statuses for paid, review, declined and refunded.
• History in every order: amount, number of payments, merchant_oid and where the confirmation came from (notification or Status Inquiry); on a decline — the reason from PayTR.
• Debug log cc_paytr.log without keys, salt or signatures.

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 check. The attempt amount, currency, collected amount and current order total must match; otherwise a “review” status with an explanation of what exactly is wrong.
• Retries without duplicates. PayTR repeats a notification until it gets “OK”: the module counts only the first one and answers exactly “OK”, without a single extra character.
• A double payment is not lost. If the buyer paid the same order twice (two tabs), the status does not change, and the history gets an entry about the second payment — so you can refund it in the PayTR panel.
• The “Back” button after payment will not send the same order to PayTR again.

Pro: installment table, interest in the order, journal and refunds

• Installment table (taksit tablosu) on the product page: World, Bonus, Axess, Maximum, CardFinans, Paraf, Advantage, Combo — rates from the PayTR Installment Rates service, refreshed once a day. Show amounts with interest (the buyer pays) or without it (peşin fiyatına).
• Single payment only for selected categories (with their subcategories) and products: PayTR receives no_installment=1, the table is not shown.
• Installment interest in the order: the difference between the collected amount and the goods total is added once as an “Installment interest (N installments)” line — the order total equals what the buyer paid.
• Payment journal: received, interest, installments, test / live, merchant_oid, refunded.
• Refunds from the admin: full or partial, several times in a row; negative, non-numeric and above-remaining amounts are rejected, the “Refunded” status is set only after a full refund.

How it works step by step

1. The buyer picks “Kredi / banka kartı (PayTR)” and presses “Pay by card”.
2. The module creates a payment attempt with its own merchant_oid and gets a form token from PayTR (iFrame API, step 1) with the order amount, cart, currency and installment settings.
3. The buyer pays in the PayTR form on a store page; 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 module checks the signature, compares the amount and currency, changes the order status and answers “OK”.
5. The buyer returns to the “Thank you” page. If the notification has not arrived yet, the module asks PayTR once through Status Inquiry.

Under the hood

• PayTR iFrame API: get-token with an HMAC-SHA256 signature per the dev.paytr.com documentation, notifications with a hash check, Status Inquiry (durum-sorgu), Refund (iade), Installment Rates (taksit-oranlari).
• The module’s own tables for payment attempts, payments and rates; settings are written key by key, without overwriting the whole group.
• No core edits and no OCMOD: a standard OpenCart payment extension and an event on the product page for the installment table.
• After the module is uninstalled the payment tables stay — the journal and refunds are available after reinstalling.

Installation

1. OpenCart 4 and 3: “Extensions → Installer” → upload the zip for your version. OpenCart 2.3: copy the contents of the upload/ folder from the archive to the store root.
2. “Extensions → Payments” → PayTR (CatCode) → install → edit.
3. Enter Mağaza No, Mağaza Parola and Mağaza Gizli Anahtar from the PayTR panel (Destek & Kurulum → Entegrasyon Bilgileri), press “Check credentials”.
4. Copy the Notification URL from the module settings to the PayTR panel: Ayarlar → Bildirim URL → Değiştir.
5. Turn on test mode, make a test payment, then turn it off.

Versions

• 1.0.0 — first release: iFrame API, Notification URL, Status Inquiry, amount and currency checks, installment table, “single payment only”, installment interest in the order, journal and refunds; OpenCart 4, 3 and 2.3; English and Türkçe.