Take card payments with PayTR in installments, refund from the order page and send payment links for phone orders.
Available Updated Oct 13, 2026Version 1.1.1CS-Cart, Multi-Vendor 4.17.2 – 4.21.x No core file edits
Built for
PayTR Payments (iFrame, Installments, Link): overview1 of 13
What it does
Accept cards, installments and 3-D Secure through PayTR with your PayTR merchant account. Customers pay on PayTR's secure page embedded in your store, choose installments and pass 3D Secure; card data never touches your server.
Stores that need their own card form can use the PayTR Direct API instead, with installment plans picked from the card number.
In Multi-Vendor, PayTR's marketplace solution sends each vendor's share to the vendor's IBAN, or the marketplace collects all payments as usual.
What it changes for your store
Installment table on product pages, from your own PayTR rates.
No lost orders. Every notification is verified and applied once, with a status inquiry fallback.
Refunds in two clicks from the order page, full or partial.
Payment links for phone and WhatsApp orders, sent by e-mail or SMS.
Vendor payouts through PayTR instead of manual bank transfers.
A PayTR transactions log under Orders.
How it works
Admin
Create a payment method with the PayTR iFrame or Direct API processor, enter the merchant ID, key and salt, copy the notification URL into the PayTR panel and choose installments, currency, test mode and order statuses.
Shopper
Places the order and pays on the payment page of your store. PayTR confirms the payment in the background, the order becomes Paid and the shopper sees the confirmation.
Order page
Refund, create a payment link or send a vendor transfer. Multi-Vendor vendors enter their IBAN in their profile.
Features
PayTR iFrame API checkout with installments, 3D Secure and test mode
Optional Direct API card form that posts straight to PayTR, with installment plans by card program
Signed notifications, processed exactly once, mapped to your order statuses
Status inquiry fallback when the shopper returns before PayTR confirms
Full and partial refunds from the admin order page
Pay-by-link for phone and manual orders, sent by e-mail or SMS
Installment table on product pages and an installment hint at checkout
Payments in TL, USD, EUR and GBP
Multi-Vendor: PayTR Marketplace transfers to vendor IBANs, recorded in vendor accounting
PayTR transactions and transfers log
What you get
Package
kv_paytr_payments-1.1.0.zip, installed through Add-ons → Manage add-ons
Updates & support
12 months included. Download new versions from your account and install them in Add-ons → Manage add-ons or the Upgrade Center.
License
1 production installation. Staging, dev and localhost are free and unlimited. The add-on keeps working after the update period ends. How licensing works
For developers
Uses 5 CS-Cart PHP hooks. No core files are changed.
Compatibility
We list only the builds we install and test on. “Tested” means the full test plan was run on that build; “Supported” means the build is inside the supported range and uses the same hooks.
CS-Cart version and edition compatibility
CS-Cart version
CS-Cart
CS-Cart Ultimate
Multi-Vendor
Multi-Vendor Ultimate
4.22 and later
Testing next
Testing next
Testing next
Testing next
4.21.2
Supported
Supported
Tested
Supported
4.20.x
Supported
Supported
Supported
Supported
4.19.x
Supported
Supported
Supported
Supported
4.18.3
Supported
Supported
Tested
Supported
4.17.2
Tested
Supported
Tested
Supported
Before 4.17.2
Not supported
Not supported
Not supported
Not supported
Last tested build: Multi-Vendor 4.21.2, Oct 13, 2026Tested on: Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3
Requirements
PHP
CS-Cart and Multi-Vendor 4.17.2 – 4.21.x (tested on CS-Cart 4.17.2, Multi-Vendor 4.17.2 and Multi-Vendor 4.21.2 with PHP 8.3)
PHP
PHP 7.4 – 8.3, as supported by your CS-Cart version
Requirement
A PayTR merchant account. You need the Merchant ID (Mağaza no), Merchant key (Mağaza parola) and Merchant salt (Mağaza gizli anahtar) from PayTR Merchant Panel > Information (Bilgi)
PHP
The PHP cURL extension (used by CS-Cart for all outgoing HTTP calls)
Requirement
HTTPS on the storefront is strongly recommended; it is required for the Direct API
Requirement
The store must be reachable from the internet so PayTR can call the notification URL. A store on localhost cannot receive PayTR notifications
Core changes
None. Hooks and template overrides only
1.1.0
Oct 13, 2026
Latest
Added 3
License check. Enter your license key (or CS-Cart Marketplace license number) on the new License tab of the settings. The add-on verifies it with cs-cart.kaviolabs.com when the key is saved and then once a day, only from the admin panel or cron, never on storefront requests. The license covers the domain entered at purchase and all its subdomains; local development hosts are always allowed.
License card at the top of the add-on page (status in color, licensed domain, result per storefront, last and next check, end of the updates period, what switches off) with Check now, a license badge in Add-ons → Manage add-ons, a status bar on the add-on's own admin pages, and a cron entry point.
Without a valid license for the store's domain, the PayTR payment methods are no longer offered at checkout and the product page installment table is hidden and the admin panel shows a notice. Payments that have already started still complete, and notifications (callbacks), refunds, payment links and marketplace transfers of existing orders keep working. New installations and upgrades from 1.0.x work for 14 days before a key is required, and if the license server cannot be reached the add-on keeps working for 14 days.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. No breaking changes.
1.0.5
Oct 12, 2026
Fixed 2
The installment rate cache no longer writes to CS-Cart storage data while the full page cache of CS-Cart 4.21 is on, which would have cleared the whole page cache.
Compatible with CS-Cart and Multi-Vendor 4.21 and PHP 8.3: tested on Multi-Vendor 4.21.2 with PHP 8.3 and the new Nova theme. The add-on now declares the supported range 4.17.2 – 4.21.x.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. No breaking changes.
1.0.4
Oct 12, 2026
Added 1
In-place upgrades now complete themselves. After the add-on files are replaced (uploading the new zip over the installed add-on in Add-ons → Manage add-ons, copying the files by FTP, or installing an Upgrade Center package), the next admin page view adds any missing tables, columns, settings, language variables and e-mail templates, and updates the stored add-on version and icon flag. Existing data and setting values are kept. A hidden schema_version setting records the last applied version.
Fixed 1
While the add-on was disabled, saving or refreshing its settings, or uploading a new version over it, stopped with a "Class not found" error. That could leave the settings only partly rebuilt. CS-Cart loads the add-on functions for a disabled add-on without its classes; the add-on now registers them itself.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. No breaking changes.
1.0.3
Oct 12, 2026
Fixed 1
The add-on icon was not shown in the admin panel: addon.xml now declares has_icon.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. No breaking changes.
1.0.2
Oct 12, 2026
Removed 1
Unused language files from the package.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. No breaking changes.
1.0.1
Oct 12, 2026
Fixed 1
Guest checkout could end on a "page not found" instead of the Direct API card form (and, less often, the iFrame payment page). The page was authorised only by data written to the session at checkout, and a checkout request of the same visitor still running (e.g. an address update fired while typing) could overwrite it. The checkout redirect now carries a key bound to the visitor's session (HMAC with the merchant credentials), the card form fields are rebuilt from the order when the session lost them, and a valid key restores the guest's access to the order for the return to the store. The key is useless in another session, and it never opens another order.
Added 1
Add-on icon in the admin add-on list.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. No breaking changes.
1.0.0
Oct 12, 2026
Added 10
Payment processor "PayTR iFrame": iFrame API checkout with paytr_token signing, base64 JSON basket, no_installment / max_installment, TL / USD / EUR / GBP / RUB with conversion from the store currencies, test mode, debug_on, payment time limit, payment page language and an order reference prefix.
Payment processor "PayTR Direct API (card form)": card form posted straight to PayTR, BIN lookup and installment plans per card program, installment fee paid by the customer or the store, client-side card validation.
Payment notification (Bildirim URL) handler shared by both processors: HMAC hash verification, exactly-once processing of repeated notifications, configurable statuses for successful, failed, pending and refunded payments, protection against late failures overriding a paid order, clean OK answer.
Customer return handling with iframe break-out, a short wait for the notification and a status inquiry fallback.
Full and partial refunds from the admin order page through the Refund API, with history.
Pay-by-link (Link API) for admin-created and phone orders: create, send by e-mail or SMS, delete; link payments mark the order paid and can be refunded.
Installment table on product pages and an installment hint at checkout, from the installment rates service, cached for 24 hours.
Multi-Vendor: PayTR Marketplace platform transfers of the vendor share (order total minus commission) to the vendor IBAN, queued at a configurable status, sent by cron or manually, completed by the transfer result notification and recorded as a vendor withdrawal; vendor bank account with IBAN validation and masking.
Orders → PayTR transactions log with a vendor transfers tab.
Setup overview in the add-on settings (notification URL, credentials check, rates refresh) and a development endpoint override (KV_PAYTR_API_BASE_URL) with an admin warning.
Tested on Multi-Vendor 4.17.2, CS-Cart 4.17.2, Multi-Vendor 4.21.2, Multi-Vendor 4.18.3. First release.
The PayTR panel shows my test payment as "In progress" (Devam Ediyor)
PayTR did not get OK from the notification URL. Open the transaction's Detail in the PayTR merchant panel to see the answer:
PAYTR notification failed: bad hash: the Merchant key or salt in the payment method does not match the PayTR account.
unknown merchant_oid: the notification URL points to another store, or the order was deleted.
An HTML page, a 403/404 or a timeout: the URL is wrong or blocked (maintenance mode, HTTP authentication, firewall, WAF). The notification URL must be reachable from the internet without a session. Check the protocol (https:// only if the store has SSL).
PayTR retries every minute, so a fixed URL completes the order automatically.
PayTR says "paytr_token gecersiz" (invalid token) before the payment page
The merchant key or salt is wrong, or something changes the request on its way (for example a proxy). Turn on Show PayTR error details while testing. The token also contains the customer's IP address: on a local machine PayTR sees your public IP, not 127.0.0.1, so test on a public server.
The order stays "Open" after the payment
The customer came back before PayTR confirmed the payment, and PayTR's status inquiry did not confirm it either. The order moves to Paid as soon as the notification arrives. If it never does, check the notification URL (above), or click Check status at PayTR in the PayTR panel of the order.
Can I use USD or EUR?
Yes, if your PayTR account allows foreign currencies (ask PayTR) and the currency exists in your store. Choose Customer currency or a fixed currency in the payment method. PayTR does not support other currencies; the add-on falls back to the primary currency or TRY.
Why is the installment table empty?
The table needs an active PayTR payment method with credentials, installments allowed, and rates from PayTR. Check the PayTR payment methods overview in the add-on settings (rates date and error) and click Refresh installment rates.
Do I need PCI DSS compliance?
With the iFrame, card data is entered on PayTR's page, so your PCI DSS scope is minimal (typically SAQ A). With the Direct API the card form is on your site: the data goes straight to PayTR, but your site is in scope (typically SAQ A-EP) and PayTR must approve the Direct API for your account.
Can vendors receive their money directly?
Yes, with the PayTR Marketplace (Pazaryeri) solution: see Usage. Without it, the marketplace receives all payments and pays vendors through CS-Cart's accounting, or each vendor can use their own PayTR account with the Direct Customer-to-Vendor Payments add-on.
Can I refund more than once?
Yes. Partial refunds can be repeated until the paid amount has been refunded. Refunds are processed by PayTR immediately; the money reaches the card according to the bank's schedule.
A payment link notification never arrives on my test server
PayTR rejects callback URLs that contain localhost or a port number (like :8080). Use a public domain on the standard port.
Two stores use the same PayTR account
PayTR supports one notification URL per account, so each store needs its own PayTR account (or a single store with several storefronts). The Order reference prefix keeps the references unique.
What happens if I uninstall the add-on?
The PayTR payment methods are disabled and the PayTR tables (attempts, refunds, links, transfers, vendor accounts) are deleted. Orders and their payment details stay. See Installation.
PayTR disappeared from checkout and the admin panel shows a license notice
Open Add-ons → Manage add-ons → PayTR Payments. The License card at the top of the add-on page says what is wrong: no key, a key for another add-on, a revoked license, or a domain that the license does not cover. Enter or change the key on the License tab and click Check now. See License.
Does the add-on work on my staging copy?
Yes. Subdomains of your licensed domain (for example staging.example.com) and local development hosts (localhost, private IP addresses, .local, .test) are covered by the same license.
What happens if your license server is down?
Nothing visible: the add-on keeps the last verified result and keeps working for 14 days while it retries. The admin panel shows a notice from the first failed check.
Does the license check slow down my storefront?
No. The check runs in the admin panel or from cron, once a day. The storefront only reads the stored result.
