Ödeme ve İşlem Servisleri

Complete Payment

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/complete

Bu servis, terminal üzerinde ödeme işlemini başlatır. Pos cihazı üzerinde kart okutularak ödeme işlemi tamamlanır. Örnek: "Satış uygulamasının başlattığı işlemi complete ederek ödemeId/authCode vb. alanları alırsınız."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

Yanıt dili.

Possible values:

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringRequired

Satış uygulaması tarafından üretilen, bu satış işlemine ait uniqueId değeri.

pricenumber · doubleRequired

Fiyat Değeri

currencystringRequired

Para birimi

installmentinteger · enumRequired

Taksit Sayısı

Possible values:

Responses

200Success

application/json

conversationIdstringOptional

İstek–cevap eşleştirmesi ve işlem takibi için üye işyeri tarafından gönderilen benzersiz değer.

localestring · enumOptional

Yanıt dili

Possible values:

deviceUniqueIdstringOptional

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringOptional

Satış uygulaması tarafından üretilen, işlem bazında benzersiz referans numarası.

statusstringOptional

İşlem sonucu. (SUCCESS, FAILURE vb.)

errorCodestringOptional

İşlem başarısız ise dönen hata kodu. Başarılı işlemlerde boş döner.

errorMessagestringOptional

Hata oluşması durumunda açıklayıcı hata mesajı.

errorGroupstringOptional

Hatanın ait olduğu grup / kategori bilgisi.

systemTimeinteger · int64Optional

İşlemin iyzico sistemlerinde işlendiği zamanın Unix timestamp değeri.

transactionDateTimestringOptional

İşlemin terminal/host üzerinde gerçekleştiği tarih ve saat bilgisi (ISO-8601).

authCodestringOptional

Banka/host tarafından üretilen onay (authorization) kodu.

paymentIdstringOptional

iyzico tarafından üretilen, işlem bazında benzersiz ödeme kimliği.

paymentDatestringOptional

İşlemin muhasebeleştirildiği tarih (YYYYMMDD).

pricenumber · doubleOptional

İşlem tutarı.

installmentinteger · int32Optional

Taksit sayısı. Tek çekim işlemlerde 0 veya 1 olarak döner.

currencystringOptional

İşlem para birimi (örn. TRY).

binNumberstringOptional

Kartın ilk 6 hanesi (BIN).

lastFourDigitsstringOptional

Kart numarasının son 4 hanesi.

hostReferencestringOptional

Banka/host sistemi tarafından üretilen işlem referans numarası.

cardTypestringOptional

Kart tipi. (CREDIT_CARD, DEBIT_CARD vb.)

acquirerIdstringOptional

İşlemi gerçekleştiren banka (acquirer) kurum kimliği.

issuerIdstringOptional

Kartı çıkaran banka (issuer) kurum kimliği.

bankMerchantIdstringOptional

Banka nezdinde üye işyerine tanımlı merchant numarası.

bankTerminalIdstringOptional

Banka nezdinde terminal için tanımlı terminal numarası.

batchNostringOptional

İşlemin dahil olduğu batch (günsonu) numarası.

stanNostringOptional

Sistem Takip Numarası (STAN – System Trace Audit Number).

posEntryModeCodestringOptional

Kart bilgilerinin POS’a giriş yöntemini belirten kod (örn. chip, manyetik, contactless).

cancelHostReferencestringOptional

İptal işlemi referans numarası

refundHostReferencestringOptional

İade işlemi referans numarası

400Error

application/json

post

/v2/terminal-host/payment/complete

HTTPcURLJavaScriptPython

POST /v2/terminal-host/payment/complete HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 161

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

{
  "conversationId": "conversation1",
  "locale": "tr",
  "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,
  "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"
}

Örnek Collection

Postman

Query Transaction Status

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/query-transaction-status

Bu servis, daha önce gerçekleşen bir işlemin durumunu sorgular. Örnek: "paymentId ile ödeme durumunu ve varsa hata bilgilerini öğrenirsiniz."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

İşlemin Durumunu Sorgulayan Servis.

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

Yanıt dili.

Possible values:

paymentIdstringRequired

Sorgulanacak Ödeme Numarası

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdone of · nullableRequired

Sorgulanmak istenen payment/ void/refund işlemi için işlem sırasında üretilmiş eşsiz referans numarasıdır.

stringOptional

or

nullOptional

Responses

200Success

application/json

conversationIdstringOptional

İstek–cevap eşleştirmesi ve işlem takibi için üye işyeri tarafından gönderilen benzersiz değer.

localestring · enumOptional

Yanıt dili

Possible values:

deviceUniqueIdstringOptional

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringOptional

Satış uygulaması tarafından üretilen, işlem bazında benzersiz referans numarası.

statusstringOptional

İşlem sonucu. (SUCCESS, FAILURE vb.)

errorCodestringOptional

İşlem başarısız ise dönen hata kodu. Başarılı işlemlerde boş döner.

errorMessagestringOptional

Hata oluşması durumunda açıklayıcı hata mesajı.

errorGroupstringOptional

Hatanın ait olduğu grup / kategori bilgisi.

systemTimeinteger · int64Optional

İşlemin iyzico sistemlerinde işlendiği zamanın Unix timestamp değeri.

transactionDateTimestringOptional

İşlemin terminal/host üzerinde gerçekleştiği tarih ve saat bilgisi (ISO-8601).

authCodestringOptional

Banka/host tarafından üretilen onay (authorization) kodu.

paymentIdstringOptional

iyzico tarafından üretilen, işlem bazında benzersiz ödeme kimliği.

paymentDatestringOptional

İşlemin muhasebeleştirildiği tarih (YYYYMMDD).

pricenumber · doubleOptional

İşlem tutarı.

installmentinteger · int32Optional

Taksit sayısı. Tek çekim işlemlerde 0 veya 1 olarak döner.

currencystringOptional

İşlem para birimi (örn. TRY).

binNumberstringOptional

Kartın ilk 6 hanesi (BIN).

lastFourDigitsstringOptional

Kart numarasının son 4 hanesi.

hostReferencestringOptional

Banka/host sistemi tarafından üretilen işlem referans numarası.

cardTypestringOptional

Kart tipi. (CREDIT_CARD, DEBIT_CARD vb.)

acquirerIdstringOptional

İşlemi gerçekleştiren banka (acquirer) kurum kimliği.

issuerIdstringOptional

Kartı çıkaran banka (issuer) kurum kimliği.

bankMerchantIdstringOptional

Banka nezdinde üye işyerine tanımlı merchant numarası.

bankTerminalIdstringOptional

Banka nezdinde terminal için tanımlı terminal numarası.

batchNostringOptional

İşlemin dahil olduğu batch (günsonu) numarası.

stanNostringOptional

Sistem Takip Numarası (STAN – System Trace Audit Number).

posEntryModeCodestringOptional

Kart bilgilerinin POS’a giriş yöntemini belirten kod (örn. chip, manyetik, contactless).

cancelHostReferencestringOptional

İptal işlemi referans numarası

refundHostReferencestringOptional

İade işlemi referans numarası

400Error

application/json

post

/v2/terminal-host/payment/query-transaction-status

HTTPcURLJavaScriptPython

POST /v2/terminal-host/payment/query-transaction-status HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "conversationId": "conversation2",
  "locale": "TR",
  "paymentId": "11001100",
  "deviceUniqueId": "PAV860047264",
  "transactionReferenceId": null
}

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

Query Status – Önemli Not

Query Status servisinde paymentId, transactionReferenceId ve deviceUniqueId alanlarının tamamı aynı anda zorunlu değildir. Servisin çalışabilmesi için aşağıdaki alan kombinasyonlarından en az biri gönderilmelidir:

• Sadece paymentId gönderilirse İlgili satış (payment) işleminin bilgileri döner.

• transactionReferenceId + deviceUniqueId birlikte gönderilirse İlgili payment / void / refund işlemleri sorgulanabilir.

• paymentId + transactionReferenceId birlikte gönderilirse Satış işlemi ile birlikte, ödeme ilişkili void ve refund işlemleri de sorgulanabilir.

Örnek Collection

Postman

Void Payment

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/void

Bu servis, uygun durumdaki bir ödemeyi iptal eder. Örnek: "paymentId ve paymentDate ile iptal işlemi başlatılır. Kart pos cihazı üzerinde okutularak iptal işlemi tamamlanır."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

Ödeme İade Servisi.

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

Yanıt dili.

Possible values:

paymentIdstringRequired

İptal Edilecek Ödeme Numarası

paymentDatestringRequired

İşlemin muhasebeleştirildiği tarih (YYYYMMDD).

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringRequired

İptal işlemine ait üretilen benzersiz bir referans numarası

reasonstringOptional

İptal nedi

descriptionstringOptional

İptal açıklaması

Responses

200Success

application/json

conversationIdstringOptional

İstek–cevap eşleştirmesi ve işlem takibi için üye işyeri tarafından gönderilen benzersiz değer.

localestring · enumOptional

Yanıt dili

Possible values:

deviceUniqueIdstringOptional

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringOptional

Satış uygulaması tarafından üretilen, işlem bazında benzersiz referans numarası.

statusstringOptional

İşlem sonucu. (SUCCESS, FAILURE vb.)

errorCodestringOptional

İşlem başarısız ise dönen hata kodu. Başarılı işlemlerde boş döner.

errorMessagestringOptional

Hata oluşması durumunda açıklayıcı hata mesajı.

errorGroupstringOptional

Hatanın ait olduğu grup / kategori bilgisi.

systemTimeinteger · int64Optional

İşlemin iyzico sistemlerinde işlendiği zamanın Unix timestamp değeri.

transactionDateTimestringOptional

İşlemin terminal/host üzerinde gerçekleştiği tarih ve saat bilgisi (ISO-8601).

authCodestringOptional

Banka/host tarafından üretilen onay (authorization) kodu.

paymentIdstringOptional

iyzico tarafından üretilen, işlem bazında benzersiz ödeme kimliği.

paymentDatestringOptional

İşlemin muhasebeleştirildiği tarih (YYYYMMDD).

pricenumber · doubleOptional

İşlem tutarı.

installmentinteger · int32Optional

Taksit sayısı. Tek çekim işlemlerde 0 veya 1 olarak döner.

currencystringOptional

İşlem para birimi (örn. TRY).

binNumberstringOptional

Kartın ilk 6 hanesi (BIN).

lastFourDigitsstringOptional

Kart numarasının son 4 hanesi.

hostReferencestringOptional

Banka/host sistemi tarafından üretilen işlem referans numarası.

cardTypestringOptional

Kart tipi. (CREDIT_CARD, DEBIT_CARD vb.)

acquirerIdstringOptional

İşlemi gerçekleştiren banka (acquirer) kurum kimliği.

issuerIdstringOptional

Kartı çıkaran banka (issuer) kurum kimliği.

bankMerchantIdstringOptional

Banka nezdinde üye işyerine tanımlı merchant numarası.

bankTerminalIdstringOptional

Banka nezdinde terminal için tanımlı terminal numarası.

batchNostringOptional

İşlemin dahil olduğu batch (günsonu) numarası.

stanNostringOptional

Sistem Takip Numarası (STAN – System Trace Audit Number).

posEntryModeCodestringOptional

Kart bilgilerinin POS’a giriş yöntemini belirten kod (örn. chip, manyetik, contactless).

cancelHostReferencestringOptional

İptal işlemi referans numarası

refundHostReferencestringOptional

İade işlemi referans numarası

422Error

application/json

post

/v2/terminal-host/payment/void

HTTPcURLJavaScriptPython

POST /v2/terminal-host/payment/void HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 201

{
  "conversationId": "conversation3",
  "locale": "TR",
  "paymentId": "28251028",
  "paymentDate": "20260112",
  "deviceUniqueId": "PAV860047264",
  "transactionReferenceId": "voidtransaction1",
  "reason": "",
  "description": ""
}

{
  "conversationId": "string",
  "locale": "string",
  "deviceUniqueId": "string",
  "transactionReferenceId": "string",
  "status": "string",
  "errorCode": "string",
  "errorMessage": "string",
  "errorGroup": "string",
  "systemTime": 0,
  "paymentId": "string",
  "price": 50,
  "currency": "TRY",
  "authCode": "552238",
  "hostReference": "mock0007iyzihostrf",
  "cancelHostReference": "mock0007iyzihostrfrfn"
}

Örnek Collection

Postman

Refund Payment

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/refund

Bu servis, uygun durumdaki bir ödemeye iade işlemi uygular (partial/total). Örnek: "paymentId ve price ile iade işlemi başlatılır. Kart pos cihazı üzerinde okutularak iptal işlemi tamamlanır."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

İstek dili.

Possible values:

paymentIdstringRequired

İade yapılacak ödeme numarası

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

pricenumber · doubleRequired

İşlem tutarı.

transactionReferenceIdstringRequired

İade işlemi için satış uygulaması tarafından üretilen, benzersiz referans numarası.

reasonstringOptional

İade Nedeni

descriptionstringOptional

İade Açıklaması

Responses

200Success

application/json

conversationIdstringOptional

İstek–cevap eşleştirmesi ve işlem takibi için üye işyeri tarafından gönderilen benzersiz değer.

localestring · enumOptional

Yanıt dili

Possible values:

deviceUniqueIdstringOptional

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringOptional

Satış uygulaması tarafından üretilen, işlem bazında benzersiz referans numarası.

statusstringOptional

İşlem sonucu. (SUCCESS, FAILURE vb.)

errorCodestringOptional

İşlem başarısız ise dönen hata kodu. Başarılı işlemlerde boş döner.

errorMessagestringOptional

Hata oluşması durumunda açıklayıcı hata mesajı.

errorGroupstringOptional

Hatanın ait olduğu grup / kategori bilgisi.

systemTimeinteger · int64Optional

İşlemin iyzico sistemlerinde işlendiği zamanın Unix timestamp değeri.

transactionDateTimestringOptional

İşlemin terminal/host üzerinde gerçekleştiği tarih ve saat bilgisi (ISO-8601).

authCodestringOptional

Banka/host tarafından üretilen onay (authorization) kodu.

paymentIdstringOptional

iyzico tarafından üretilen, işlem bazında benzersiz ödeme kimliği.

paymentDatestringOptional

İşlemin muhasebeleştirildiği tarih (YYYYMMDD).

pricenumber · doubleOptional

İşlem tutarı.

installmentinteger · int32Optional

Taksit sayısı. Tek çekim işlemlerde 0 veya 1 olarak döner.

currencystringOptional

İşlem para birimi (örn. TRY).

binNumberstringOptional

Kartın ilk 6 hanesi (BIN).

lastFourDigitsstringOptional

Kart numarasının son 4 hanesi.

hostReferencestringOptional

Banka/host sistemi tarafından üretilen işlem referans numarası.

cardTypestringOptional

Kart tipi. (CREDIT_CARD, DEBIT_CARD vb.)

acquirerIdstringOptional

İşlemi gerçekleştiren banka (acquirer) kurum kimliği.

issuerIdstringOptional

Kartı çıkaran banka (issuer) kurum kimliği.

bankMerchantIdstringOptional

Banka nezdinde üye işyerine tanımlı merchant numarası.

bankTerminalIdstringOptional

Banka nezdinde terminal için tanımlı terminal numarası.

batchNostringOptional

İşlemin dahil olduğu batch (günsonu) numarası.

stanNostringOptional

Sistem Takip Numarası (STAN – System Trace Audit Number).

posEntryModeCodestringOptional

Kart bilgilerinin POS’a giriş yöntemini belirten kod (örn. chip, manyetik, contactless).

cancelHostReferencestringOptional

İptal işlemi referans numarası

refundHostReferencestringOptional

İade işlemi referans numarası

400Error

application/json

post

/v2/terminal-host/payment/refund

HTTPcURLJavaScriptPython

POST /v2/terminal-host/payment/refund HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "conversationId": "conversation4",
  "locale": "TR",
  "paymentId": "11001100",
  "deviceUniqueId": "PAV860047264",
  "price": 50,
  "transactionReferenceId": "refundtransaction2",
  "reason": "",
  "description": ""
}

{
  "conversationId": "string",
  "locale": "string",
  "deviceUniqueId": "string",
  "transactionReferenceId": "string",
  "status": "string",
  "errorCode": "string",
  "errorMessage": "string",
  "errorGroup": "string",
  "systemTime": 0,
  "paymentId": "string",
  "price": 50,
  "currency": "TRY",
  "authCode": "552238",
  "hostReference": "mock0007iyzihostrf",
  "refundHostReference": "mock0007iyzihostrfrfn"
}

Örnek Collection

Postman