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.

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.

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

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