# 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 %}

### 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](#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** ](https://docs.iyzico.com/urunler/fiziksel-pos/login-islemleri#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** ](https://docs.iyzico.com/urunler/fiziksel-pos/login-islemleri#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](https://docs.iyzico.com/urunler/fiziksel-pos/odeme-ve-islem-servisleri#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](https://docs.iyzico.com/urunler/fiziksel-pos/odeme-ve-islem-servisleri#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](https://docs.iyzico.com/urunler/fiziksel-pos/odeme-ve-islem-servisleri#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](https://docs.iyzico.com/urunler/fiziksel-pos/gun-sonu-alma-servisi#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"
}
```