iyzico integration

When iyzico is the right choice

iyzico is a payment institution used by businesses that take online payments in Türkiye. It lets you charge Turkish cards, offer instalments and manage recurring payments (subscriptions) through one API, without signing a separate virtual POS contract with each bank. Card details are entered into iyzico’s payment form, so the card number never touches your server.

Where iyzico fits well

You take card payments on the web from customers in Türkiye
You want to offer instalments
You sell monthly or yearly subscriptions and want renewals charged automatically
You do not want card details stored on your own server

Where we would suggest another route

You sell digital content or subscriptions inside a mobile app: Apple and Google require their own billing there
You already have a virtual POS contract with your bank on good terms; a direct bank integration may make more sense
Your company is registered outside Türkiye and sells mostly abroad; a provider operating in your country may suit you better

How iyzico works in Hippotenus

Hippotenus has two payment models, both on iyzico: subscriptions and prepaid plans. For subscriptions we use iyzico’s subscription API; products and pricing plans are defined in iyzico, iyzico charges the renewals, and cancellation, plan upgrades and card updates go through the same API. For prepaid plans we take a single payment or instalments through the payment form, and the number of instalments offered never exceeds the plan’s length.

	Subscription	Prepaid plan
On iyzico’s side	Subscription API and subscription payment form	Payment form (Checkout Form)
Charging	iyzico charges the stored card on renewal	Single payment or instalments
Afterwards	Cancellation, plan upgrade, card update	Refund through iyzico within the right of withdrawal
What reaches the server	Renewal, failed charge and cancellation notifications	The payment result, re-read from iyzico with a token

No plan opens until the payment is confirmed

The real work in online payments is everything outside the path where all goes well. This is how Hippotenus handles it:

When the user comes back to the site after paying, we do not trust what the browser says: the server re-reads the payment from iyzico with a token, and if the basket number, amount and currency do not match the order exactly, the plan does not open.
If the tab is closed during 3D Secure and the return never arrives, a scheduled job asks iyzico about unfinished orders. If the payment was taken, the plan opens through the same verification; unpaid orders are closed after a while.
Notifications from iyzico are recorded, and if the same notification arrives twice it is not processed again.
Every payment produces a PDF receipt showing the VAT breakdown, and refunds are written to the same transaction records.
Coupons, trial periods and a preview of the price difference before a plan change are part of the same payment layer.

What we use in an iyzico integration

NestJS

The Hippotenus API. Payment code lives in a separate billing module, and iyzico sits behind a payment provider interface.

iyzipay

iyzico’s Node.js library. Payment form, subscription, instalment info and refund calls go through it.

Prisma and PostgreSQL

Orders, transactions, subscription events and iyzico notifications are kept in separate tables, so a payment’s history can be traced later.

Scheduled jobs

With NestJS Schedule: checking unfinished payments, plan renewal reminders and applying plan changes on time.

React web dashboard

iyzico’s payment form opens embedded inside the web dashboard, which is built with React.

Payment test screen

The admin panel has a test screen that simulates iyzico notifications and moves time forward to try renewals without waiting.

How an iyzico integration runs

01
Free scoping call
30 min
We talk about what you sell (one-off, instalments, subscription), who you sell to and where your iyzico account stands.
02
Written scope and quote
We write down the payment model, the refund and cancellation rules, and your receipt and accounting needs.
03
Weekly releases
Every week you get a build to try in iyzico’s test environment (sandbox); with test cards you see successful, declined and abandoned payments for yourself.
04
Testing and going live
A senior QA tests the payment scenarios before release, and only then do we switch to live keys. In Hippotenus, if a test key is used with the live address (or the other way round), the server logs it as an error at startup.
05
The 30 days after launch
30 days
We fix the bugs that surface in this period free of charge; after that you can continue with monthly maintenance.

Timelines and budget ranges are on our web application development and pricing pages. The iyzico account and contract belong to your business, and you agree the commission and payout terms with iyzico.

Questions about iyzico integration

Do card details pass through your server?

No. The card number is entered into iyzico’s payment form; the Hippotenus server only sees the result of the payment and the references iyzico returns. The burden of storing and protecting card data stays with iyzico.

What happens when a subscription renewal fails?

iyzico sends renewal, failed-charge and cancellation notifications to the server, and the system updates the subscription’s status accordingly. The user can change their card through iyzico’s card update form.

Can I use iyzico in a mobile app too?

For digital content and subscriptions sold inside an app, Apple and Google require their own billing; there we work with RevenueCat. If you sell physical goods or a service delivered outside the app, iyzico can be used on mobile as well.

Can I move to another payment provider later?

We connect the payment code to a payment provider interface rather than to iyzico directly. Adding another provider means writing a new implementation of that interface, without touching the order, receipt and subscription logic. The provider in our live projects is iyzico.

iyzico integration

What we have built with it

Hippotenus