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

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.

Genel Akış ve Entegrasyon Modeli

Terminal API entegrasyonu iki farklı mali model üzerinden çalışır:

• VUK 507 Modu (Ö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 (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.

Ö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.

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

2. Erişim Yetkisi Alma

3. Satış İşleminin Tamamlanması

4. İşlem Durumu Sorgulama

5. İptal/İade (Opsiyonel)

6. Gün Sonu

---

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 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 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 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 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:

• 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:

• 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 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

{
"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

{
"access_token": "eyJraWQiOiI....ZEA",
"refresh_token": "eiHg.....BBp",
"scope": "iyzipayApiGateway",
"token_type": "Bearer",
"expires_in": 7199
}

---

3. Satış İşleminin Tamamlanması

Request

{
    "conversationId": "conversation1",
    "locale": "TR",
    "deviceUniqueId": "PAV860047264",
    "transactionReferenceId": "string30",
    "price": 100.0,
    "currency": "TRY",
    "installment": 0
}

Response

{
  "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

{
"conversationId": "string",
 "locale": "TR-EN",
 "deviceUniqueId": "string",
  "useSummary": true
}

Response

{
  "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"
}