iyzico

What you need

iyzico Merchant Panel → Settings → API keys:

• api_key
• secret_key

In your panel choose Settings → Payments → Add method → iyzico and enter both.

Sandbox: for iyzico's test environment enter the keys that start with sandbox-… and tick sandbox (test) mode; the panel then talks to sandbox-api.iyzipay.com. Going live, enter the live keys and untick the box.

The callback URL is attached to every payment automatically; nothing has to be configured in the iyzico panel. Its shape:

https://<your-panel-domain>/payments/iyzico/callback

Flow

1. The customer enters an amount and a phone number and picks iyzico. (The phone is a required iyzico field.)
2. They are sent to iyzico's hosted payment page; card entry and 3D Secure happen there, card data never touches your server.
3. When the payment finishes, iyzico sends the customer's browser back to your panel. That return carries only a token, which on its own proves nothing.
4. The panel asks iyzico about the token with a signed server-to-server call (retrieve). If iyzico says SUCCESS and the basket id is our payment, the balance is credited and the customer lands on "Add funds" with a success banner.
5. On FAILURE the payment is recorded as failed with iyzico's error message in its memo.

A second return for the same token is ignored; balance is never credited twice.

Fraud review

iyzico holds some payments for review (fraudStatus = 0). Such a payment shows as pending in the panel and credits nothing; once iyzico approves it (in its panel or by webhook) complete it from Admin → Payments. A rejected payment (-1) counts as failed.

Currencies

iyzico accepts TRY, USD, EUR, GBP, NOK and CHF. Your panel's currency must be one of these; a payment cannot be started in a currency iyzico does not take.

Pages the site must publish (iyzico requirements)

An iyzico virtual POS application is assessed per URL: certain pages must be live on the domain you apply with. Ticking "Add the iyzico requirements to the site" while adding the method publishes them for you:

Page	Path
About Us	/about
Contact	/contact
Delivery and Refunds	/delivery-refund
Distance Sales Agreement	/distance-sales
Terms of Service	/terms (published with the tick off too)
Privacy Policy	/privacy (published with the tick off too)

iyzico's own footer band is added at the bottom of the site as well: the "pay with iyzico" logo plus the Troy, American Express, Visa and Mastercard marks. It shows even if you have edited your theme's footer.html, because it is rendered outside the theme file so an application requirement never depends on a template edit.

SSL needs nothing from you: panel domains are served over HTTPS only, with certificates issued automatically.

Fill in the company details

The default text of those four documents comes from your seller identity. Under Appearance → Legal, fill the Company details block: registered name, address, phone, tax office and number, and MERSIS where you have one. A field you leave empty is never printed; if the name, address or phone is missing you will see a warning, because iyzico looks for those three.

The texts arrive filled in and are editable as Markdown. Save an empty box and the generated text is published again. These templates are not legal advice; review them against your own situation before publishing.

Clear the tick and the four pages go away (404) and the band disappears; anything you wrote is kept.

Infrastructure tag (payment source)

Every payment request carries paymentSource set to HUGOSOFTWARE. That is the tag registered for this infrastructure under the iyzico partnership so iyzico can see which e-commerce platform started the payment; there is nothing for you to configure. If the value is used live before iyzico has registered it on their side the request can fail, so run the first attempt in the sandbox.

Common problems

• "callbackUrl is required" / SSL error: iyzico insists the callback URL has a valid TLS certificate; while your domain is not yet pointed at us, a payment cannot start. Finish the DNS change first.
• Card declined in sandbox: use iyzico's test cards (the "Test Cards" list in its docs); real cards do not work in the sandbox.
• Payment succeeded but no balance: look at the payment's memo under Admin → Payments. If the retrieve call failed (wrong key, sandbox/live mixed up) the reason is there.