# Terminal API Entegrasyonu ### Genel Bakış **Terminal API**, **Yazar Kasa** ile **Fiziksel POS cihazları** arasında ödeme işlemleri sırasında güvenli ve kontrollü bir haberleşme sağlamak amacıyla geliştirilmiş **özel bir iletişim protokolüdür**. Bu API, ödeme sürecinin başlatılmasından sonucun tekrar yazar kasaya iletilmesine kadar olan tüm akışı standart ve deterministik bir yapı ile tanımlar. ### Dokümantasyon Kapsamı Bu doküman kapsamında aşağıdaki başlıklar ele alınmaktadır: * Terminal API temel kavramları * Ödeme yaşam döngüsü ve durumları * İstek / yanıt mesaj formatlar {% hint style="info" %} Servislere iletilecek tüm istekler **iyzico OAuth2 kimlik doğrulama yapısı** kullanılarak gönderilmelidir. Ödeme ve günsonu servislerine erişim için **Bearer access\_token** zorunludur. {% endhint %} ### Genel Akış ve Entegrasyon Modeli Terminal API entegrasyonu iki farklı mali model üzerinden çalışır: * [**VUK 507 Modu** ](/urunler/fiziksel-pos/terminal-api-entegrasyonu/vuk-507-servisleri.md)**(ÖKC Entegre / Hibrit Kullanım – GİB Onaylı Yapı)** Bu modda cihaz, **ÖKC (Ödeme Kaydedici Cihaz)** gibi davranır ve **GMU (Güvenli Mali Uygulama)** yapısı ile çalışır. **Özellikler:** * Cihaz, mali hafızaya kayıt yapan bir ÖKC gibi çalışır * **Tüm ödeme türleri desteklenir:** * Nakit * Kredi Kartı * Diğer ödeme yöntemleri (QR, yemek kartı vb.) * Satış işlemi doğrudan mali kayda dönüşür (fiş üretimi) * GİB mevzuatına uygun klasik perakende satış senaryosu **Kullanım Senaryosu:** * Fiziksel mağaza / perakende satış noktaları * ÖKC zorunluluğu olan mükellefler * [**VUK 509 Modu** ](/urunler/fiziksel-pos/terminal-api-entegrasyonu/vuk-509-servisleri.md)**(e-Dönüşüm Entegre / ÖKC Muafiyetli Yapı)** Bu modda cihaz, mali cihaz (ÖKC) gibi çalışmaz; ödeme alma fonksiyonu ile sınırlıdır ve mali belge üretimi harici sistemler üzerinden yürütülür. **Özellikler:** * **Sadece kredi kartı ile ödeme alınır** * Nakit ve diğer alternatif ödeme türleri desteklenmez * Cihaz üzerinde mali fiş üretimi yoktur * İşlemler, **e-Fatura** / **e-Arşiv** süreçleri ile ilişkilidir * Mali kayıtlar, ÖKC yerine e-Belge sistemleri üzerinden oluşturulur **Kullanım Senaryosu:** * **ÖKC muafiyeti bulunan işletmeler** * e-Ticaret / uzaktan satış / saha satış senaryoları * Fatura bazlı çalışan işletmeler\ \ VUK 507 modunda cihaz mali cihaz (ÖKC) rolünü üstlenirken, VUK 509 modunda yalnızca ödeme terminali olarak konumlanır ve mali belge üretimi e-Belge sistemleri üzerinden gerçekleştirilir. Her iki modelde de entegrasyon aşağıdaki adımlarla ilerler: 1. Login işlemleri gerçekleştirilir 2. Access token alınır 3. Seçilen modele göre ilgili servisler kullanılır Login ve token alma adımları her iki model için ortaktır. Servis çağrıları ise VUK 507 ve VUK 509’a göre ayrışmaktadır. {% hint style="warning" %} Önemli:\ VUK 507 ve VUK 509 servisleri aynı entegrasyon içerisinde birlikte kullanılmamalıdır. Kullanılacak model, iş modeline ve mali yükümlülüklere göre entegrasyon öncesinde belirlenmelidir. {% endhint %} ### Entegrasyon Adımları iyzico Fiziksel POS entegrasyonu, güvenli kimlik doğrulama ve kontrollü işlem adımlarından oluşan bir akış üzerinden çalışır.\ Bu bölüm, entegrasyonun **hangi sırayla** ve **hangi amaçla** ilerlediğini genel hatlarıyla açıklar. Örnek uygulama, VUK 509 modeli ile örneklendirilmiştir. 1. [Kullanıcı Doğrulama ve Yetkilendirme Başlatma](#id-1.-kullanici-dogrulama-ve-yetkilendirme-baslatma) 2. [Erişim Yetkisi Alma](#id-2.-erisim-yetkisi-access-token-alma) 3. [Satış İşleminin Tamamlanması](#id-3.-satis-isleminin-tamamlanmasi) 4. [İşlem Durumu Sorgulama](#id-4.-islem-durumu-sorgulama) 5. [İptal/İade (Opsiyonel)](#id-5.-satis-iptali-void) 6. [Gün Sonu](#id-7.-gunsonu-end-of-day-eod) *** ### 1. Kullanıcı Doğrulama ve Yetkilendirme Başlatma Entegrasyonun ilk adımında, üye işyeri sisteminde tanımlı kullanıcı bilgileri ile bir [**yetkilendirme süreci** ](/urunler/fiziksel-pos/terminal-api-entegrasyonu/login-islemleri.md#kullanici-dogrulama-ve-yetkilendirme-authorize-baslatma)başlatılır. Bu adımda: * Kullanıcı doğrulanır * Yetkilendirme sürecini temsil eden **Authorization Code** üretilir Bu kod: * Kısa süreli ve tek kullanımlıktır * Bir sonraki adımda erişim yetkisi almak için kullanılır *** ### 2. Erişim Yetkisi (Access Token) Alma Üretilen Authorization Code kullanılarak sistem tarafından bir [**access token** ](/urunler/fiziksel-pos/terminal-api-entegrasyonu/login-islemleri.md#get-token-with-auth-code-refresh-token)oluşturulur. Bu token: * Ödeme, iptal, iade ve günsonu işlemleri dahil tüm servis çağrılarında kullanılır * Süreli olarak geçerlidir * Süresi dolduğunda yenilenmesi gerekir Bu aşamadan sonra sistem, **yetkili bir terminal** olarak işlem yapabilir duruma gelir. *** ### 3. Satış İşleminin Tamamlanması Yetkilendirme tamamlandıktan sonra, [satış işlemi başlatılır](/urunler/fiziksel-pos/terminal-api-entegrasyonu/vuk-509-servisleri/odeme-ve-islem-servisleri.md#complete-payment) ve ödeme süreci tamamlanır. Bu adımda: * Satışa ait benzersiz bir referans oluşturulur * Terminal ve yazar kasa bazlı kimliklendirme yapılır * Ödeme sonucu sistem tarafından kayıt altına alınır İşlem sonunda dönen **paymentId**, sonraki tüm işlemler (iptal, iade, sorgu) için temel referans olarak kullanılır. *** ### 4. İşlem Durumu Sorgulama Gerçekleşen [işlemlerin durumu](/urunler/fiziksel-pos/terminal-api-entegrasyonu/vuk-509-servisleri/odeme-ve-islem-servisleri.md#query-transaction-status) bu adımda sorgulanabilir. Bu sorgulama ile: * Satışın başarılı olup olmadığı * İptal veya iade işlemlerinin durumu * İlgili işleme ait detaylar tek bir servis üzerinden görüntülenebilir. *** ### 5. Satış İptali (Void) Aynı gün içerisinde yapılan bir satışın iptali gerektiğinde bu adım kullanılır. [İptal işlemi](#id-5.-satis-iptali-void): * Orijinal satış işlemi ile ilişkilendirilir * Başarılı olması durumunda işlem sonucu sisteme iletilir Bu adım yalnızca **gün kapanışı yapılmamış** işlemler için geçerlidir. *** ### 6. İade (Refund) Satış sonrası, tam veya kısmi iade işlemleri bu adım üzerinden gerçekleştirilir. [İade işlemi](/urunler/fiziksel-pos/terminal-api-entegrasyonu/vuk-509-servisleri/odeme-ve-islem-servisleri.md#refund-payment): * Satıştan bağımsız, kendine ait bir referans ile yapılır * Başarılı olduğunda iade bilgileri sistem tarafından döndürülür *** ### 7. Günsonu (End of Day – EOD) Gün içerisinde yapılan işlemlerin bankaya kapatılması için [günsonu](/urunler/fiziksel-pos/terminal-api-entegrasyonu/vuk-509-servisleri/gun-sonu-alma-servisi.md#gun-sonu-alma) işlemi gerçekleştirilir. Bu adımda: * Günlük işlemler toplu olarak kapatılır * Özet ve toplam bilgiler alınabilir * Banka tarafındaki batch süreci tamamlanır *** ### Mimari Akış Terminal API kapsamında ödeme akışı aşağıdaki şekilde ilerler: ``` Yazar Kasa ↓ POS ↓ Kullanıcı Ödeme ↓ POS ↓ Yazar Kasa ``` * **Yazar Kasa**, ödeme başlatma isteğini oluşturur. * **POS cihazı**, kullanıcı ile etkileşimi (kart okuma, şifre girişi, temassız vb.) yönetir. * Ödeme sonucu, tanımlı protokol mesajları ile tekrar yazar kasaya iletilir. *** ### Protokol Tasarımı * Terminal API, **tarafımızca tasarlanmış ve geliştirilen özel bir protokoldür**. * Mesaj formatları, durum geçişleri ve hata senaryoları açık şekilde tanımlanmıştır. * Protokol aşağıdaki hedefler gözetilerek tasarlanmıştır: * Düşük gecikme süresi * Net ve öngörülebilir yanıtlar * Standartlaştırılmış hata yönetimi * POS üreticilerine özel genişletilebilir yapı *** ### Desteklenen Poslar Şu anda Terminal API aşağıdaki POS üreticisi ile uyumludur: * **Pavo** (EFT Pos) > İlerleyen aşamalarda, aynı protokol yapısı korunarak farklı POS üreticileri için destek eklenebilir. *** ### **Örnek Uygulama** #### 1. Kullanıcı Doğrulama ve Yetkilendirme Başlatma **Response** ```json { "code": "FYEff_koHQnoX9vIMo5icTrqmSsbIOvD6xz8KAEEjnvj652-WHt9HKRL1IngeOAZU6z8Z5BL3Nr_vQTcAv91nQmuOpJCUQ9qyWtoviNPLjLd5QY_ynLx0OtA5Xj8ZlMS", "issuedAt": "2025-12-25T14:05:49.379055098+03:00", "expiredAt": "2025-12-25T14:15:49.379055098+03:00" } ``` *** #### 2 .Erişim Yetkisi (Access Token) Alma **Reponse** ```json { "access_token": "eyJraWQiOiI....ZEA", "refresh_token": "eiHg.....BBp", "scope": "iyzipayApiGateway", "token_type": "Bearer", "expires_in": 7199 } ``` *** #### 3. Satış İşleminin Tamamlanması **Request** ```json { "conversationId": "conversation1", "locale": "TR", "deviceUniqueId": "PAV860047264", "transactionReferenceId": "string30", "price": 100.0, "currency": "TRY", "installment": 0 } ``` **Response** ```json { "conversationId": "string", "locale": "string", "deviceUniqueId": "string", "transactionReferenceId": "string", "status": "string", "errorCode": "string", "errorMessage": "string", "errorGroup": "string", "systemTime": 0, "transactionDateTime": "2025-11-20T12:03:05.096Z", "authCode": "string", "paymentId": "string", "paymentDate": "20251120", "price": 0.0, "installment": 0, "currency": "TRY", "binNumber": "552879", "lastFourDigits": "0008", "hostReference": "string", "cardType": "CREDIT_CARD", "acquirerId": "string", "issuerId": "string", "bankMerchantId": "string", "bankTerminalId": "string", "batchNo": "string", "stanNo": "string", "posEntryModeCode": "string" } ``` *** #### 4. Gün Sonu **Request** ```json { "conversationId": "string", "locale": "TR-EN", "deviceUniqueId": "string", "useSummary": true } ``` **Response** ```json { "status": "string", "errorCode": "string", "errorMessage": "string", "errorGroup": "string", "locale": "string", "systemTime": 0, "conversationId": "string", "tails": [ { "acquirerId": "string", "terminalId": "string", "bankMerchantId": "string", "totalTransactionAmount": "string", "totalTransactionCount": "string", "acquirerName": "string", "batchNo": "string", "responseCode": "string", "internalErrorCode": "string" } ], "batchNo": "string", "resultMessage": "string" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.iyzico.com/urunler/fiziksel-pos/terminal-api-entegrasyonu.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.