Usage

At checkout

The customer selects the iyzico payment method. Under it, a short note says that card details are entered on the secure iyzico form. If Show installment table is on, an Installment options link opens a table for the current cart total:

Card	Single payment	2 installments	3 installments	…
Bonus (Garanti Bankası)	180.00 TRY	2 × 93.15 TRY / 186.30 TRY	3 × 63.15 TRY / 189.45 TRY	…

The table reloads when the cart total changes, for example after the shipping method changes. If iyzico can’t be reached, a short note is shown instead and checkout continues.

After Place order, the order is created with the status Incomplete and the customer pays:

Embedded / popup: on a Secure payment page of your store, which shows the order number and amount, the iyzico form and a Cancel and return to the store link;
iframe: on the same page, with iyzico’s hosted page in a frame;
Redirect / Pay with iyzico: on iyzico’s own page.

After paying, the customer returns to the normal order confirmation page. A declined card returns the customer to the store with iyzico’s message, for example “Kart limiti yetersiz”. The order then has the Failed status and can be paid again with Pay again on the order page (CS-Cart’s repay feature). Every attempt gets a new iyzico token, and older pending attempts are closed.

The method is hidden at checkout when:

the payment method has no API keys for its current mode;
no currency is available that iyzico accepts;
in marketplace mode, a vendor in the cart has no iyzico sub-merchant yet.

Basket mapping

iyzico requires every payment to carry a basket. The sum of the item prices must equal the amount charged, and every item price must be above zero. The add-on sends:

Basket item	Item type	Category
Each order product (name, ID)	PHYSICAL, or VIRTUAL for downloadable products without shipping	The product’s main category and its parent
Shipping, one item per vendor/product group	PHYSICAL	Shipping
Gift certificates bought in the order	VIRTUAL	Gift certificate
Payment surcharge	VIRTUAL	Payment surcharge

Each line starts with its own amount: product subtotals after product discounts, the shipping rate, the certificate amount, the surcharge. The order total is converted to the charge currency and rounded to the cent. It is then split across the lines in proportion to those amounts, using the largest remainder method. This spreads everything that changes the total but has no line of its own: order discounts and coupons, applied gift certificates, reward points, taxes added on top of prices, and the currency rounding. The sum always matches to the cent. Free items (0.00) are left out, because iyzico rejects zero-priced items.

Order page (admin)

Orders paid with iyzico get an iyzico tab on the order page.

Payment summary: status, iyzico payment ID, amount and currency, the amount charged including installment interest, the number of installments, refunded / paid totals and the last error.
Basket items at iyzico: each item with its iyzico transaction ID, paid and refunded amounts. In marketplace mode, the vendor share and payout approval are shown too.
Refund: enter an amount (up to the remaining paid amount, in the payment currency) and an optional note, then click Refund via iyzico. A partial refund is split across this order’s basket items in proportion to their remaining amounts, because iyzico refunds per basket item. A full refund sets the status from Order status after a full refund if you configured one.
Cancel payment: voids the whole payment. iyzico allows this only on the day of the payment and before any refund. After that, use refunds. The order gets Order status after a cancel.
Approve vendor items (marketplace mode): releases the vendor share of this order’s items to the vendor.
Check payment status at iyzico: shown while a payment is still pending. It fetches the result and applies it.
Refunds and cancels: the history with date, amount, result and note.

The Payment information block of the order also shows the iyzico payment ID, the number of installments, the amount charged, the card (brand, family and last four digits only), the mode, and the refunded amount.

Vendors see the iyzico tab of their orders read-only. Refunds, cancels and approvals are admin actions.

Sandbox testing

Set the payment method Mode to Sandbox and enter your sandbox keys. Click Test connection.

Place an order on the storefront and pay with one of iyzico’s test cards. Any future expiry date and any CVC work. For example:

Card	Result
5528 7900 0000 0008 (Halkbank, Mastercard credit)	Success; installments available
5400 3600 0000 0003 (Garanti, Mastercard credit, Bonus)	Success
4766 6200 0000 0001 (Denizbank, Visa debit)	Success, no installments
4111 1111 1111 1129	Declined: not sufficient funds
4129 1111 1111 1111	Declined: do not honour
4151 1111 1111 1112	3D Secure initialization fails

The complete list is on the Test Cards page of the iyzico developer documentation.

Complete the 3D Secure step on the sandbox bank page.
Check the result: the order status, the iyzico tab, and the payment in the sandbox merchant panel.
Test a partial refund, a full refund and a same-day cancel from the iyzico tab.
Switch Mode to Live only after these checks pass. Live keys are stored separately.

A sandbox payment page shows a yellow Test mode note to the customer.

Multi-Vendor marketplace mode

With an iyzico Marketplace account, iyzico splits each payment. Each vendor’s share goes to the vendor’s bank account (a sub-merchant), and the rest goes to you.

Setup

Create an iyzico payment method as described in Configuration. Use the keys of your Marketplace account.
Add-ons → iyzico Payments → Settings → Marketplace: turn on Enable iyzico Marketplace mode. Choose which payment method’s keys are used for sub-merchants, and decide how items are approved.

Each vendor fills in the iyzico sub-merchant tab on their profile (vendor panel: the vendor profile page, iyzico sub-merchant tab; admin: Vendors → Vendors → vendor → iyzico sub-merchant):

Business type	Required fields
Individual	IBAN, identity number (TCKN), contact first and last name
Sole proprietorship	IBAN, identity number, tax office, legal company title
Limited or joint-stock company	IBAN, tax office, tax number, legal company title

The vendor’s name, e-mail, address and phone come from the vendor profile. A mobile number can be entered separately.

When you save the tab as an administrator, the add-on checks the data and creates the iyzico sub-merchant, or updates it if it already exists. The tab shows Registered at iyzico or the error from iyzico. Send to iyzico now retries. If the sub-merchant already exists at iyzico (for example after a reinstall), its key is recovered by the external ID. When a vendor saves new data, it first waits for your approval (see Payout detail changes), unless you turned that off.

Settings → Marketplace → Status shows how many active vendors are ready.

Payout detail changes

The IBAN decides where iyzico sends a vendor’s money. If a vendor account is taken over, an attacker could enter their own IBAN. That’s why, by default, a vendor’s own change of the payout details needs your approval (setting Require admin approval for vendor payout detail changes).

The iyzico payout changes list shows the license status at the top: a small License: Valid chip, or a banner with the status and the actions when the add-on is switched off (see License).

What needs approval: every field of the iyzico sub-merchant tab: business type, IBAN, identity number, tax office, tax number, legal company title, contact name and mobile number. All of them are sent to iyzico. A vendor’s first registration needs approval too, so no sub-merchant is created at iyzico before you have checked the data.

What the vendor sees: after saving, Your payout details change was sent to the marketplace administrator for approval. The tab shows a Pending admin approval box with the changed fields, old and new. The IBAN, identity number, tax number and mobile number are masked (for example TR32 **** **** 7890). The form keeps showing the current (live) details. The vendor can withdraw the request with Cancel the change request. Saving the profile again without changes does not create a new request. A new change replaces the waiting one. Invalid data (for example an IBAN that is not TR + 24 digits) is refused right away with the errors, so it never reaches you.

What you see:

A Notifications center entry (N vendor payout detail change(s) wait for approval) and an e-mail to the site administrator address.
Vendors → iyzico payout changes lists the requests with the masked old and new values. Show full values shows them in full so you can check a new IBAN with the vendor through a contact you already know. Filter by status to see approved, rejected, cancelled and replaced requests, with who decided and when.
The vendor’s iyzico sub-merchant tab shows the same box with Approve and Reject.

Approve sends the new data to iyzico (creates or updates the sub-merchant) and makes it live. If iyzico refuses it, the request stays pending with iyzico’s message and the current details stay active. If Marketplace mode or Send vendor data to iyzico on save is off, approving only saves the data. Reject (optionally with a reason) discards the request. The vendor gets a Notifications center entry and an e-mail with the decision and the reason.

Every request, approval, rejection and cancellation is stored with the user and the time, and written to Administration → Logs (type iyzico, masked).

The vendor status never changes because of the iyzico data, with or without Vendor data premoderation. Your own changes as an administrator apply immediately, as before.

How the split is calculated

When a customer pays a multi-vendor order, the add-on sends basket items for every vendor’s products and shipping, each with the vendor’s subMerchantKey and a subMerchantPrice:

The vendor share of a vendor order is that order’s total minus the commission CS-Cart calculated for it. The commission is read from the vendor payout record, so it follows the vendor plan (percentage and fixed fee), Commissions by category, and the collect taxes from vendors and include shipping options.
The charged amount is first split across vendors in proportion to their vendor order totals, so each vendor’s basket items add up to exactly that vendor’s order. The vendor share is then split across the vendor’s items in proportion to the item prices. Each item gets at least 0.01, and no item gets more than its own price. Both are iyzico rules.
The payment surcharge and the installment interest stay with the marketplace.

Example: vendor A sells a 100.00 item and 10.00 shipping on a plan with 10% commission and shipping included. The vendor order is 110.00, CS-Cart’s commission is 11.00, and vendor A’s items carry subMerchantPrice values that add up to 99.00. iyzico deducts its own fees from the marketplace’s part.

Payout approval

iyzico keeps the vendor share until each basket item is approved. Usually this happens after delivery, which protects the marketplace against returns.

Automatic: turn on Approve vendor items automatically and choose the statuses, for example Complete. When a vendor order reaches one of them, its items are approved.
Manual: on the order page, iyzico tab, click Approve vendor items.

Refunded items are not approved. Items that are already approved are skipped.

Refunds in marketplace mode

The customer sees one payment, but CS-Cart keeps one order per vendor. When you refund from a vendor order, only that vendor’s items are refunded. A cancel voids the whole payment, so it is offered only when the payment covers a single vendor order.

Limitations

Marketplace mode needs the vendor of every cart item to have a sub-merchant. Otherwise iyzico is hidden for that cart.
With Direct Customer-to-Vendor Payments, vendors own their payment methods, and each vendor can create an iyzico payment method with their own keys. Marketplace mode is then ignored.
Vendor data premoderation: the iyzico data is stored by the add-on, not in the vendor profile, so saving it never sends the vendor to Pending (whether the vendor or you save it). Vendor changes go through the add-on’s own approval instead (see Payout detail changes). With that approval turned off, if the vendor is already Pending for other profile changes, a vendor’s iyzico data is saved but sent to iyzico only after you approve the vendor: then open the vendor’s iyzico sub-merchant tab and click Send to iyzico now (or save the vendor).